MCP

ⓘ

Who can use this feature?

You need the Pro or Plus plan to create and manage API keys.
For developers building an external bot or agent that answers on your behalf.

Overview

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:

A customer sends a message.
Chatty fires a message.created webhook to your bot. Read senderType and act on customer only.
Your bot calls Chatty's MCP tools — look up a product, search FAQs, check an order.
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.

Connect


Endpoint	`POST https://app.chatty.net/mcp`
Protocol	JSON-RPC 2.0 over Streamable HTTP
Mode	Stateless — every request is self-contained. Only `POST` is accepted.

Headers

Header	Value
`X-App-Id`	Your App ID — the field at the top of Settings > General > Manage keys. Some tools call it a Client ID.
`Authorization`	`Bearer sk_...` — an API key from the same panel
`X-Chatty-Convo-Id`	Optional. The conversation the bot is acting in. Tools that read or write a conversation need it.

Both credentials sit in the same place, and the key is the same one the Chat Conversations API uses. See the API reference for how to create one.

A missing or malformed header returns 401 with Missing required headers: X-App-Id and Authorization (Bearer sk_...). An unknown or revoked key returns 401 Invalid or revoked API key.

Any MCP client can connect. Point it at the endpoint above and pass the two headers.

Tools

Your bot should call tools/list after connecting rather than hard-coding this table — the tool set is built per request from your store's AI agent settings, so it changes when you toggle a feature.

Always available

Tool	What it does
`send_message`	Send a bot message to a conversation. Call it after composing your answer.
`faq_retrieval`	Search your store's FAQ knowledge base.
`add_note`	Add an internal note to a conversation. Visible to your team only.
`update_tags`	Set tags on a conversation. Replaces the existing tags with the list you pass.
`assign_member`	Assign a team member to a conversation, or unassign.
`list_members`	List team members. Use it to find member ids before assigning.
`list_conversations`	List your store's test AI conversations, with cursor pagination.
`register_webhook`	Register a webhook to receive real-time events. The result returns your signing secret.

ⓘ

list_conversations returns test conversations only — the ones from the AI agent playground, not your live customer inbox. To read live conversations, use GET /chat/conversations on the Chat Conversations API.

Available when the matching feature is on

Tool	Turned on by
`product_lookup`	AI agent > Training data > Products
`product_faq_lookup`	AI agent > Training data > Products
`manage_cart`	AI agent > Training data > Products
`collection_lookup`	AI agent > Training data > Collections
`discount_lookup`	AI agent > Training data > Discounts
`size_guide_lookup`	AI agent > Instructions > Assistant skills > Size guide
`check_order_status`	AI agent > Instructions > Assistant skills > Order tracking
`customer_support`	AI agent > Instructions > Assistant skills > After-sale support
`human_agent_transfer`	AI agent > Instructions > Assistant skills > Human handover
`joy_loyalty_lookup`	The Joy loyalty integration

manage_cart reads and edits the Shopify cart: get reads it, add puts items in and creates a cart when you omit cartId, update changes quantity, remove takes items out.

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

Event	Fires when
`message.created`	A message is added to a conversation.
`message.updated`	A message is edited.
`message.removed`	A message is deleted.
`conversation.created`	A conversation starts.
`conversation.state_changed`	The conversation status changes.
`conversation.assigned`	The conversation is assigned to a member.
`conversation.tags_updated`	The tags on a conversation change.
`conversation.removed`	A conversation is deleted.
`customer.created`	A customer record is created.

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.

Do not set your own signing secret. Chatty generates it and ignores any secret you send. The generated value comes back in the register_webhook result, and in the response body of POST /chat/webhooks. It looks like whsec_ plus 48 hex characters. Store it when you register, and verify every payload with it.

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

Errors

Errors come back in JSON-RPC form:

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

Situation	Response
Any method other than `POST`	`405`, `Method not allowed. Only POST is supported in stateless mode.`
Missing or malformed headers	`401`
Unknown or revoked key	`401`
Store not found	`404`, `Shop not found.`

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.

SDK Reference Product Roadmap