Connect an AI Agent to Your Telegram Store

You can now run a Tiny Shops store from an AI agent. Cursor, Claude Code, Codex, and other clients that speak MCP connect to https://mcp.tiny-shops.com/mcp, open your dashboard in the browser, and wait for you to pick one store. After that, you talk to the agent the way you talk to a colleague: list this week's orders, add a product, ship a parcel, check revenue, draft a win-back.

This release is the connection itself, plus the store jobs that were still dashboard-only: bot status, the shopper greeting, currency and language, analytics, and win-back automations. Every one of those tools is also a plain HTTP call, so a warehouse script can use the same contract as the agent.

What you get#

One store, approved in the browser. The agent does not get a password and does not see your other shops. You sign in with the account you already use, choose exactly one store, and grant write access. Billing, account settings, and admin-only deletes stay out of that grant. Disconnecting it in the dashboard stops the agent immediately.

Day-to-day work in plain language. Products, orders, customers, promo codes, the theme, checkout, and payment providers were already tools. This release adds the rest of the morning routine: is the bot connected, what does the welcome message say, how did the last 7, 30, or 90 days look, and which win-back is waiting for people who favorited a product or left checkout.

A preview before anything wide goes out. A broadcast does not send on the first call. The agent comes back with the recipient count. A delete, and a currency change that relabels existing prices, waits for an explicit yes. You read the preview, then tell the agent to go ahead.

The same tools for scripts. Anything the agent can call is also POST https://mcp.tiny-shops.com/v1/<tool> with the same input. The full contract is public at openapi.json. Order changes still fire the store's signed webhook, so a fulfillment system can react without polling.

If the shop is not live yet, start with how to set up a Telegram store. The agent is most useful once there is a catalog and an order list to work on.

How to connect#

You need to be the store owner. Team members cannot mint this access.

1. In the dashboard sidebar, open Agents & API.
2. On the card Connect an AI agent, click Copy connection prompt.
3. Paste that prompt into Cursor, Claude Code, Codex CLI, or VS Code with an MCP client that supports remote HTTP and browser sign-in.
4. When the browser opens, sign in, pick one store, and click Connect.

The prompt the button copies is:

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 screen that opens lists two columns. The agent can view and change operational data in the store you picked, including products and orders. It cannot open billing, account settings, admin-only actions, or any other store. You can disconnect it later under Agents & API → Agent connections.

Update the client if the browser never opens. Client support for remote MCP moves quickly. Claude.ai and ChatGPT can add a custom connector at the same URL, then complete the same browser sign-in; Tiny Shops has not verified those two web flows yet. A normal chat, with no connector, will not connect because you pasted the address.

What to ask#

Talk in sentences. The agent looks up the live tool list and fills in ids. A few prompts that match what the server actually does:

Orders

• "List my 10 most recent paid orders."
• "Show me order 1042."
• "Mark order 1042 as paid." That status is PROCESSING — paid and being prepared.
• "Ship 1042 with DHL tracking JD014600003SE and message the buyer." Leave the message off unless you want Tiny Shops to send the shipping note.

Catalog and storefront

• "Add a product called Mint Mug for 12.99."
• "Which promo codes are active?"
• "Switch the storefront primary color to mint green."
• "What's the welcome message, and rewrite it so it mentions free shipping over $40?"

Numbers

• "How did the store do in the last 30 days?" The agent calls analytics for 7d, 30d, or 90d and gets revenue, order counts by status, unique visitors, and the top products.

Win-backs

Win-backs need a plan that includes messages. Ask the agent to list them, or to create one: a title, a trigger (favorited or abandoned checkout), a wait of 0–30 days, a discount of 5–50%, a code that expires within 1–168 hours, the message, and up to two buttons (a product or the shop). The setup in the dashboard is the same program — see how to win back shoppers.

Broadcasts

Ask for a message to every customer, or to specific customers, up to about 500 people per send. The first reply is a preview: who would receive it, and the text. Say yes only after you have read that preview. Larger lists need more than one send. Saved audience segments are not available on this path yet.

Bot token, currency, and deletes#

Bot. Ask "is my bot connected?" any time. The answer is a yes or no plus the username. The token never comes back. Connecting a new BotFather token through the agent does the same work as the dashboard: it checks the token with Telegram and registers the store webhook. The token still passes through the chat to get there, so paste it in the dashboard when you can, and use the agent for everything after the bot is connected.

Currency and language. Reading them is safe. Changing the currency relabels prices already on products, so the agent must send a confirmation flag. Read the warning before you approve it.

Deletes. Permanent deletes need an admin token, which a browser-connected agent never receives. Keep deletes in the dashboard, or on a short-lived admin token you revoke when the cleanup is done. Do not paste an admin token into an agent.

Scripts and warehouses#

Browser sign-in is the path for an assistant on your laptop. A server-side script has no browser, so it uses an API token.

On Agents & API, create a token with Read (reports and lookups) or Write (the same operational changes an agent gets). The token is shown once. Treat it like a password: it is stored only as a hash, and revoking it cuts off the next request.

curl -X POST https://mcp.tiny-shops.com/v1/ship_order \
  -H "Authorization: Bearer tsh_live_…" \
  -H "Content-Type: application/json" \
  -d '{"orderId": 1042, "carrier": "DHL", "trackingNumber": "JD014600003SE"}'

Replace ship_order with any other tool name. get_analytics takes { "period": "30d" }. Responses look like { "ok": true, "data": … } or { "ok": false, "error": { "code", "message" } }. The full setup, including order webhooks, is in the developer guide: Connect an AI agent.

Reads are limited to 100 protocol calls a minute per token, and tool calls to 30 a minute. A client that hits the cap gets a 429 and a wait time.

Disconnect it#

Open Agents & API → Agent connections, choose the client, and click Disconnect. Its access and refresh tokens stop on the next request. API tokens are a separate list on the same page: revoke the row, and that secret stops too.

Connect the agent to the store you are actually working in. A second shop is a second approval, on purpose — one conversation cannot see both.