Connect an AI agent (EN)

Tiny Shops exposes its tools at:

https://mcp.tiny-shops.com/mcp

For order-only scripts, HTTP endpoints, and signed fulfillment events, see Orders API & Webhooks.

Which clients can connect?

MCP desktop and CLI clients

• Cursor, Claude Code, Codex CLI, and VS Code with an MCP extension can connect when their current version supports remote HTTP MCP and browser OAuth.
• Client support changes quickly. If browser sign-in does not open, update the client and check its MCP documentation; use an API token only for a trusted script or a client that truly lacks browser sign-in.

Web connectors

• Claude.ai: add a custom connector using https://mcp.tiny-shops.com/mcp, then complete the browser sign-in flow when prompted. This flow is not yet verified by Tiny Shops.
• ChatGPT: add a custom connector in connector/developer settings using https://mcp.tiny-shops.com/mcp, then complete browser sign-in. This flow is not yet verified by Tiny Shops.

Plain chats

A normal Claude.ai, ChatGPT, or other chat conversation cannot connect just because you paste the server URL. It needs an MCP connector/client feature. Never paste an API token into a plain chat.

Browser OAuth (recommended)

Paste this into an MCP-capable agent:

Connect to my Tiny Shops store using the MCP server at https://mcp.tiny-shops.com/mcp. Use browser OAuth; do not ask me for an API token.

The client discovers OAuth automatically, opens the Tiny Shops dashboard, and asks you to:

1. Sign in with your existing dashboard account.
2. Pick exactly one store.
3. Grant write access.

The connection cannot access another store and does not receive admin scope. Revoke it at Settings → API tokens → Agent connections.

API-token fallback

For a server-side script or a client without browser OAuth, create a tsh_… token at Settings → API tokens. Use write for changes or read for read-only scripts, then send:

Authorization: Bearer tsh_live_…

Never paste an admin token into an agent.

Tool behavior

The live tool reference is maintained with the MCP server. Important rules:

• Use the exact names returned by tools/list.
• Every MCP tool is also available over HTTP at POST https://mcp.tiny-shops.com/v1/<tool> with the same input, token scope, rate limit, and tenant isolation.
• “Mark paid” means set_order_status with PROCESSING.
• For destructive tools, do not send confirm on the first call. Let the tool return its preview, show that to the merchant, and only retry with confirm: true after explicit approval.

Setup, analytics, and win-backs

• get_bot reports connection status and username without exposing the token; connect_bot validates a BotFather token and registers the store webhook.
• get_welcome_message / update_welcome_message manage the shopper greeting.
• get_store_settings / update_store_settings manage currency and primary language. Changing currency relabels existing product prices and requires confirm: true.
• get_analytics returns revenue, order and status counts, unique visitors, and top products for 7d, 30d, or 90d.
• list_winbacks, create_winback, and update_winback configure win-back automations when the plan includes messages.

Clients that do not speak MCP can discover the complete HTTP contract at GET /v1/openapi.json.

See Orders API & Webhooks for the fulfillment payload and HTTP examples.