MCP
Overview
💬Get free consultation

MCP

ⓘ

Who can use this feature?

  • You need the Pro or Plus plan to create and manage API keys.
  • Setting this up needs a developer. You create the key yourself in Settings → General → Manage keys, then someone who writes code connects the bot to it.

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.

The Tool Reference lists all 144 tool names, including 23 Helpdesk tools, with scopes, writes and API-key/OAuth availability.


Connect with an API key

EndpointPOST https://app.chatty.net/mcp
Server namechatty-mcp, version 1.0.0
ProtocolJSON-RPC 2.0 over Streamable HTTP
ModeStateless, so every request is self-contained. Only POST is accepted.

Headers

HeaderRequiredValue
X-App-IdYesYour App ID, the field at the top of Settings → General → Manage keys. Some clients call it a Client ID.
AuthorizationYesBearer sk_..., an API key from the same panel.
X-Chatty-Convo-IdNoThe conversation the bot is acting in. add_note, update_tags, and assign_member read convoId from this header when you omit the parameter.

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 the key scopes, AI agent settings and connected integrations.


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_..."
      }
    }
  }
}
!

Grant only the scopes the bot needs. conversations:write allows sending messages as your store. Storefront tools remain available independently of key scopes, including cart edits when Products is enabled. Keep these files out of version control and off shared machines.


Connect with OAuth

A merchant assistant can connect to the same https://app.chatty.net/mcp endpoint through OAuth. Use the client's OAuth connection flow, sign in and select the store and permissions. Send Authorization: Bearer <access_token> and omit X-App-Id: that header selects API-key authentication.

Discovery is available at /.well-known/oauth-protected-resource/mcp and /.well-known/oauth-authorization-server on the same host. OAuth supports the authorization-code flow with PKCE S256; request offline_access when the client needs refresh tokens.

OAuth scopeAccess
conversations:readConversations and AI traces
conversations:writeReply and perform permitted conversation actions as the connected member
customers:readMinimized customer profiles and memory
campaigns:readCampaign setup and engagement
analytics:readConversation, sales, intent, satisfaction and chat-to-sale analytics
knowledge:readTraining data, scenarios, knowledge, FAQ exports and deletion progress
settings:readAgent configuration, public settings, translations, channel and integration status
helpdesk.helpcenter:readHelp center settings, overview and search analytics
setup:readSetup progress
knowledge:writeKnowledge proposals for human review
settings:writeSettings proposals for human review

The member's current role and permissions cap the grant. Admins may receive all OAuth scopes. Staff and members can receive conversations:write with current Inbox conversation edit access, checked again for each write, and helpdesk.helpcenter:read with Help center view access. An existing connection does not gain new scopes automatically; connect again to grant them. Knowledge/settings write scopes remain admin-only proposals. OAuth still excludes webhook operations and conversation/customer deletion; it does not grant conversations:delete.

OAuth exposes up to 71 tools: 47 existing read/identity tools, 16 public resource tools, and eight proposal tools. The resource tools are 12 conversation tools (including member and customer-conversation reads), get_shop_analytics, and read-only versions of manage_translations, manage_faq and manage_help_center. Channel, integration, translation, FAQ and Help center writes stay API-key only; OAuth clients read status and follow connectUrl. Conversation writes act immediately as the connected member. send_message and start_conversation do not accept a client-selected OAuth sender; ask_ai discards a supplied customer object. A proposal creates a pending record. Applying or rejecting it requires an admin, the appropriate scope and human confirmation. See OAuth proposal tools.

Which tools your store gets

The API-key server exposes up to 136 tools: eight core tools, ten storefront tools, four admin tools, 47 additional merchant tools, 44 public resource tools and 23 Helpdesk tools. The public tools cover 180 actions with per-action scope checks. These overlap with OAuth; there are 144 names across the two servers. Helpdesk tools need the matching helpdesk.* scope and are API-key only.

Key typeCore toolsAdmin and merchant toolsStorefront tools
Explicit scopesEach tool requires its listed scopeEach tool/action requires its listed scopes; chatty_whoami needs no scopeControlled by the conditions below, not scopes
Empty scope list ([])NoneOnly chatty_whoamiStill available when enabled
Legacy key (no scopes field)All eightNone, including public resource toolsStill available when enabled

Write scopes include reads of the same resource. settings:write includes settings domain writes, and a settings domain write also grants settings:read. Use the scope reference and per-tool table when creating a key.

Setting or integrationStorefront toolsCondition
AI agent > Training data > Productsproduct_lookup, product_faq_lookup, manage_cartEnabled; off by default
AI agent > Training data > Collectionscollection_lookupEnabled; off by default
AI agent > Training data > Discountsdiscount_lookupEnabled; off by default
AI agent > Skills > Size guidesize_guide_lookupEnabled; off by default; Pro
AI agent > Skills > Order trackingcheck_order_statusEnabled; on by default; Basic or higher
AI agent > Skills > After-sale supportcustomer_supportEnabled; on by default
Human handoffhuman_agent_transferAlways registered on the API-key server
Joy (opens in a new tab)joy_loyalty_lookupConnected on a plan with API access

The Products setting enables cart reads and writes together; it has no separate cart switch. API-key scopes do not restrict these storefront tools. Creating API keys needs Pro or Plus; tool registration also follows the settings and scope conditions above.


Team and key administration

API-key connections can use manage_members, manage_api_keys and manage_ai_clients. They add member profiles/notifications, staff invitations and edits, delegated key management, and AI-client disconnection. These three tools are not registered on OAuth, even for an admin member.

manage_members reads require members:read; its writes and AI-client management require members:write. All API-key management actions require api_keys:write. Member writes and all key/client management calls also require the key creator to remain an active admin of the same shop. A scope grant does not bypass KEY_OWNER_NOT_ADMIN.

Keys created through MCP can receive only scopes covered by the calling key and cannot receive api_keys:write. The new secret is shown once. A caller cannot update/revoke itself; scopes: [] revokes another key. Read the administration contracts before inviting members, changing permissions or disconnecting clients.

Channels, monitoring, exports and content

API-key connections can also run work that used to need the admin:

  • manage_integrations changes channel preferences, adds email channels, connects integrations that use a credential, and disconnects channels and integrations. It needs settings.integrations:write. Connections that need the merchant to sign in show requiresMerchantAction and a connectUrl in get_channels and get_integrations.
  • manage_webhooks lists delivery attempts and failures, redelivers retained deliveries and sends test events.
  • get_shop_analytics reads intent, satisfaction, campaign, handling and chat-to-sale reports with the store's plan limits.
  • export_conversations and get_conversation_transcript return conversation data directly. export_customers emails customer data to the store's email address and needs customers:export.
  • manage_translations, manage_faq (import, export and delete all), manage_recommendations and update_shop_preferences cover content and settings. manage_help_center reads the Help center and, with helpdesk.helpcenter:write, changes its settings, store page, colors and assets.

Each tool uses the same rules, limits and audit records as its REST route; the tool reference links to them.

Conversation actions and files

Use Public resource tools for each action's IDs, body and scope. Grouped tools use conversationId plus body; the older send_message, update_tags and assign_member use flat convoId arguments. add_note remains API-key only; OAuth adds notes with manage_conversation_notes.

list_conversations now reads live conversations with REST filters and cursor, a default limit of 20 and maximum 100. Its old playground after, before, sort and search inputs are rejected. update_tags still replaces the complete tag list.

send_message accepts text or up to ten base64 files, each at most 5 MiB. start_conversation creates an email conversation and can send an initial message/files. Files are uploaded before sending. Both use the shared write controllers and authenticated audit actor. Existing Messenger, Instagram, WhatsApp and email replies follow channel delivery rules; new WhatsApp template conversations are not supported.

Deleting a conversation requires conversations:delete, separate from conversations:write. Deleting a customer also requires customers:write and removes associated conversations. OAuth exposes neither delete operation. Check errors and returned IDs before retrying a partially completed write.

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. Scope grants, settings and integrations determine the current tool set.
  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

EventFires when
message.createdA message is added to a conversation.
message.updatedA message is edited.
message.removedA message is deleted.
conversation.createdA conversation starts.
conversation.updatedThe email or phone detected in a conversation changes.
conversation.state_changedThe conversation status changes.
conversation.assignedThe conversation is assigned to a member.
conversation.tags_updatedThe tags on a conversation change.
conversation.removedA conversation is deleted.
customer.createdA customer record is created.
customer.updatedA customer profile is updated.

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 only when a new subscription is created. Re-registering the same URL, listing or updating a subscription does not return it. It looks like whsec_ plus 48 hex characters. Store it when you register. If lost, use POST /webhooks/:id/rotate-secret on the Public API; it returns a replacement once and invalidates the previous secret.

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


Rate limits

LimitRequests per minute
Authenticated /mcp requests120 per shop, shared by API-key and OAuth connections
Failed MCP authentication60 per IP
ask_ai20 questions per key; OAuth uses a shop/member budget
OAuth metadata120 per IP
OAuth authorization30 per IP
Token/revocation requests600 per IP, plus 300 per client for code exchange or 30 per connection for refresh

Starting conversations and uploading file batches each have a separate 60/hour/shop budget. Webhook tests are limited to 10/hour/shop, redeliveries to 30/hour per subscription, customer exports to 10/hour/shop, translation resets to 5/hour/shop, and credential verification to 10/hour/key. Customer memory regeneration has a 10/hour/key budget. Member invitations are limited to 20/hour/shop, member notification updates to 30/hour/key, and API-key creation to 10/hour/shop; each shares its operation budget with REST. These operation limits also apply through MCP.

A rejected request returns HTTP 429 with X-RateLimit-Limit and X-RateLimit-Remaining. Wait before retrying and avoid repeated discovery or tool-call loops. REST endpoints have separate limits; see Errors and rate limits.


Errors

Authentication failures use a plain object rather than JSON-RPC. API-key failures include:

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

Protocol errors use JSON-RPC form:

{ "jsonrpc": "2.0", "error": { "code": -32000, "message": "Shop not found." }, "id": null }
SituationStatusResponse
X-App-Id present but Authorization missing or not starting with Bearer 401{ "error": "Missing required headers: X-App-Id and Authorization (Bearer sk_...)" }
X-App-Id absent and no valid OAuth bearer token401{ "error": "invalid_token" } with OAuth discovery in WWW-Authenticate
Key sent in X-Api-Key instead of Authorization401Same missing-headers message. The header check runs first and never sees the key.
Key unknown, revoked, or belonging to another store401{ "error": "Invalid or revoked API key." }
Any method other than POST405{ "jsonrpc": "2.0", "error": { "code": -32000, "message": "Method not allowed. Only POST is supported in stateless mode." }, "id": null }
App ID resolves to a store that no longer exists404{ "jsonrpc": "2.0", "error": { "code": -32000, "message": "Shop not found." }, "id": null }
Calling an API-key tool absent from tools/list because of scopes or settings200A JSON-RPC error from the MCP layer reporting that the tool does not exist. Compare against tools/list before calling.

An OAuth call without its required scope returns HTTP 403, { "error": "insufficient_scope" } and a WWW-Authenticate challenge naming the scope. A rate-limit rejection returns 429 with a plain error body. An unauthenticated GET returns 401 rather than 405. Check the HTTP status and top-level error before parsing a JSON-RPC response.

Tool failures may arrive in an HTTP 200 MCP result. Core tools can put {"error": "..."} in result text; merchant tools also use structuredContent and isError. Check these before reporting success. Proposal validation and confirmation failures are tool errors, not successful updates.


Security

!

Scope each key to its job. Core, admin and merchant tools enforce per-tool scopes, but storefront tools remain controlled by shop settings. An empty scope list does not disable cart edits when Products is enabled. Legacy keys retain all eight core tools; replace them with scoped keys when you need narrower access.

  • Keep API keys on your server and out of browser code, shared configuration and version control.
  • Give each bot its own key so you can revoke one without stopping the others. Each store can hold up to five active keys.
  • A bot that replies needs conversations:write; FAQ retrieval needs knowledge:read. Reading live conversations also needs conversations:read (included by its write scope).
  • MCP checks the key on each request. If it leaks, revoke it in Settings → General → Manage keys, create a replacement and audit webhook subscriptions. Webhook registration requires conversations:write on a scoped key.
  • Scope grants apply to the store, not a single conversation. Check webhook signatures and process only customer-originated messages.

Store credentials outside your code

Read them from environment variables or a secret manager.

Discover the permitted tools

Use tools/list. The API-key and OAuth servers expose different operations, even when a scope name is shared.

Log confirmed writes

Record successful replies, notes, tag changes and assignments. MCP records tool call outcomes, and shared write controllers carry the authenticated member/API-key actor into mutation audits. A tool error, queued job or pending proposal is not a completed change.


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.