MCP

Overview

MCP lets an AI assistant you run yourself work inside your Chatty inbox: read a conversation, look up a product, an order, or an FAQ, and post its reply where the customer sees it. That assistant can be a bot your team builds, or a tool such as Claude.

Chatty exposes your store's chat capabilities as an MCP (opens in a new tab) server. An external bot connects once, discovers the tools your store has enabled, calls them to gather what it needs, and posts its answer back into the conversation.

A typical loop:

1. A customer sends a message.
2. Chatty fires a message.created webhook to your bot. Read senderType and act on customer only.
3. Your bot calls Chatty's MCP tools: look up a product, search FAQs, check an order.
4. Your bot calls send_message to reply. The answer appears in the conversation.

Use it to run your own model, apply your own logic before answering, or plug Chatty into an agent framework you already have.

Every parameter, type, and return value is listed in the Tool Reference.

Connect

Headers

Both credentials sit in the same place, and the key is the same one the Chat Conversations API uses. The two APIs read it from different headers: MCP wants Authorization: Bearer sk_..., the Chat Conversations API wants X-Api-Key: sk_.... Sending it the wrong way returns 401 on either side.

Each store can hold up to 5 active keys. See the API reference for how to create one.

Check the connection

List the tools your store exposes

curl -s -X POST "https://app.chatty.net/mcp" \
  -H "X-App-Id: $CHATTY_APP_ID" \
  -H "Authorization: Bearer $CHATTY_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

Call tools/list after connecting rather than hard-coding a list. The tool set is rebuilt on every request from your store's AI agent settings, so it changes the moment you flip a switch in the app.

Connect from an MCP client

Clients that speak Streamable HTTP take the URL and the two headers as they are. Clients that expect a local command need the mcp-remote bridge.

Claude Desktop

Add this to claude_desktop_config.json, then restart the app.

{
  "mcpServers": {
    "chatty": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://app.chatty.net/mcp",
        "--header", "X-App-Id:${CHATTY_APP_ID}",
        "--header", "Authorization:Bearer ${CHATTY_API_KEY}"
      ],
      "env": {
        "CHATTY_APP_ID": "YOUR_APP_ID",
        "CHATTY_API_KEY": "sk_..."
      }
    }
  }
}

Cursor

Add this to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json for every project. Cursor speaks Streamable HTTP directly, so no bridge is needed.

{
  "mcpServers": {
    "chatty": {
      "url": "https://app.chatty.net/mcp",
      "headers": {
        "X-App-Id": "YOUR_APP_ID",
        "Authorization": "Bearer sk_..."
      }
    }
  }
}

Which tools your store gets

Chatty exposes 17 tools. Eight are always registered. Nine more depend on switches in your AI agent settings, and Chatty reads those switches on every single request.

Three tools share one switch. Turning on AI agent > Training data > Products registers product_lookup, product_faq_lookup, and manage_cart together. There is no separate switch for the cart — if the AI can read products, it can also edit the cart.

Four switches are off until you turn them on. Products, Collections, Discounts, and Size guide all default to off. A store that has never touched its AI agent settings exposes 11 tools: the 8 always-on ones plus order tracking, after-sale support, and human handover, which are on by default.

No tool is plan-gated at the MCP layer. The plan check happens earlier, on the switch itself and on the API key: order tracking needs the Basic plan or higher, size guide needs Pro, and creating any key at all needs Pro or Plus.

Rules for your bot

Six rules cover the mistakes that break a Chatty bot in production.

1. Ask before you assume. Call tools/list after connecting. The tool set is rebuilt from your settings on every request, so a hard-coded list goes stale the moment someone flips a switch.
2. Answer customers, not yourself. message.created fires for every message, including the ones your bot sends. Act only when senderType is customer.
3. Copy ids verbatim. Every id comes from an earlier call. Never build, shorten, or reformat one. See Identifiers.
4. Read before you replace. update_tags overwrites the whole tag list rather than merging. Read the current tags first if you mean to add one.
5. Confirm before you escalate. customer_support and human_agent_transfer take two calls. The first asks the customer; the second sends isConfirmed: true. Send it only after the customer has actually agreed.
6. Nothing reaches the customer until you send it. Every tool returns text to your bot. send_message is the only one that posts into the conversation.

Receive customer messages

Your bot needs to know when to act. Register a webhook, either with the register_webhook tool or with POST /chat/webhooks on the Chat Conversations API:

curl -s -X POST "https://app.chatty.net/chat/webhooks" \
  -H "X-Api-Key: $CHATTY_KEY" -H "Content-Type: application/json" \
  -d '{
        "url": "https://your-bot.example.com/hooks/chatty",
        "events": ["message.created"]
      }'

Events you can subscribe to

message.created fires for every message added to a conversation, whichever side added it. The payload carries senderType. Act only when it is customer, so your bot never answers itself.

Verify every delivery before acting on it. See Webhooks for the payload shape and signature check.

Rate limits

The absence of an MCP limit is not a licence to hammer it. Your bot almost always calls the Chat Conversations API with the same key for reading live conversations, and those calls are counted. A tool-call loop that also polls /chat/conversations will hit 429 on the REST side long before anything complains on the MCP side. See Errors and rate limits.

Errors

Authentication is checked before anything else, and it answers with a plain object rather than JSON-RPC:

{ "error": "Invalid or revoked API key." }

Everything after that comes back in JSON-RPC form:

{ "jsonrpc": "2.0", "error": { "code": -32000, "message": "Shop not found." }, "id": null }

Because the header check runs first, an unauthenticated GET returns 401 rather than 405. Test for a top-level error string before parsing a JSON-RPC response.

Tool-level failures are not protocol errors. A tool that cannot do its job returns 200 with an ordinary result whose text is {"error": "..."} — for example Conversation abc not found or Member is not active. Parse the result text and check for an error key.

Security

What that means when you hand a key to a bot:

• A leaked key is a leaked inbox. Treat it like a password to your storefront, not like a public app token.
• Give each bot its own key. You get 5 per store. One key per bot means you can revoke one without taking the others down.
• Never ship it to the browser. The key belongs on your server. Anything in storefront JavaScript is public.
• Rotate on suspicion, not on schedule. Delete the key in Settings → General → Manage keys and generate a replacement. MCP verifies the key against the database on every request, with no cache, so deletion stops MCP traffic immediately. The Chat Conversations API caches for 5 minutes, so REST calls with the same key can survive that long.
• Watch the webhooks. register_webhook is available to every key. A stolen key can quietly point a copy of your message stream at someone else's server, so audit your subscriptions with GET /chat/webhooks after any incident.

Need help?

Contact the Chatty support team from your dashboard. Include the tool name, the timestamp of a failing call, and the returned error message.

For parameters and return values, see the Tool Reference. For reading live conversations over REST, see the Chat Conversations API.