ZChat MCP server

Before you start

• Difficulty: Developer
• Time: 5 minutes
• You need: A ZChat API key (Settings → API keys). Read only is enough to look; Read & write to change things; tick "Can send messages to customers" only if the assistant may reply to customers
• You need: An MCP client that can send a header to a remote server (Claude Code, Cursor, VS Code, or mcp-remote for Claude Desktop)

Steps

1. The server

   URL: https://api.zchat.com/mcp, Streamable HTTP transport, authenticated with Authorization: Bearer <API key>. The assistant only sees the tools the key's permissions allow: a read-only key gets read-only tools (marked readOnlyHint), and reply_to_conversation appears only for keys with messages:send.

   URL:     https://api.zchat.com/mcp
   Header:  Authorization: Bearer zck_live_YOUR_KEY

2. Claude Code

   Add it once; the key stays in your local Claude Code config.

   claude mcp add --transport http zchat https://api.zchat.com/mcp \
     --header "Authorization: Bearer zck_live_YOUR_KEY"

3. Cursor

   In .cursor/mcp.json (or Settings → MCP):

   {
     "mcpServers": {
       "zchat": {
         "url": "https://api.zchat.com/mcp",
         "headers": { "Authorization": "Bearer zck_live_YOUR_KEY" }
       }
     }
   }

4. Claude Desktop

   Claude Desktop's config file starts local servers, so bridge with mcp-remote (Node.js required):

   {
     "mcpServers": {
       "zchat": {
         "command": "npx",
         "args": ["-y", "mcp-remote", "https://api.zchat.com/mcp",
                  "--header", "Authorization:${AUTH_HEADER}"],
         "env": { "AUTH_HEADER": "Bearer zck_live_YOUR_KEY" }
       }
     }
   }

5. ChatGPT and claude.ai connectors

   Hosted connectors in ChatGPT and on claude.ai sign in with OAuth rather than a pasted key. ZChat's OAuth sign-in for MCP is not available yet; until then use a client that sends a header (above).

Tools

• search_conversations: conversations:read, read-only. Search by text, status, channel, contact and start date.
• get_conversation: conversations:read, read-only. A conversation with its messages.
• reply_to_conversation: conversations:write and messages:send. Sends a message to the customer on their channel. Cannot be unsent.
• set_conversation_status: conversations:write. open, pending_human or resolved.
• list_tickets / get_ticket: tickets:read, read-only.
• create_ticket: tickets:write. Open a ticket for a customer.
• search_knowledge: knowledge:read, read-only. Keyword search over the knowledge base.
• add_qa: knowledge:write. Teach an exact question and answer.
• list_ai_agents: agents:read, read-only. AI settings (live and draft) and the per-site agents.
• update_ai_instructions: agents:write. Workspace instructions (to the draft when Require publish is on) or a site agent's instructions.
• publish_ai_settings: agents:write. Make the draft live.
• get_reports_summary: reports:read, read-only. Headline numbers.
• list_ai_tests / run_ai_test: agents:read / agents:write. Simulated customer tests; runs count against the monthly cap.

Good to know

• Same rate limit as the REST API for the key (600 requests a minute on paid plans, 60 on free). Every change is made by the same code as the dashboard: webhooks fire, the audit log records the key, and the AI allowance and test-run caps apply.
• Requests with a browser Origin header are refused, so a web page cannot drive the server with someone's key.
• Revoking the key in Settings → API keys disconnects the assistant immediately.