Karzoun Docs

This page is the HTTP reference. If you are connecting Claude.ai, ChatGPT, Manus, or remote Cursor, start with Cloud apps. Stay here when your own server calls /mcp.

https://{subdomain}.api.karzoun.chat/mcp
https://{subdomain}.api.karzoun.chat/mcp/{pack}

Never call /mcp from browser JavaScript. The API key would be exposed to end users. Use your backend or a trusted worker.

When to use hosted

Use hosted	Use stdio instead
Deployed AI agent on your infrastructure	Local coding in Cursor / Claude
Cron or queue worker needs CRM tools	One-off exploration
Multi-tenant SaaS proxying per-customer tokens	Personal dev machine

Authentication

Send the same credential as GraphQL:

Authorization: Bearer kz_live_YOUR_API_KEY

x-api-key: kz_live_… is equivalent. Clients that sign the user in (Claude.ai, ChatGPT) use OAuth instead of a pasted key: give them the MCP URL and they complete login and consent. A legacy x-app-token still works until 31 March 2027. Optional: x-subdomain when your gateway routes workspaces by header.

Packs (tool subsets)

Prefer a pack so agents get a focused tool list:

Pack	URL
Customer support	`/mcp/customer-support`
Marketing	`/mcp/marketing`
Operations	`/mcp/operations`
WhatsApp	`/mcp/whatsapp`
Automations	`/mcp/automations`
Integrations	`/mcp/integrations`
AI (knowledge base)	`/mcp/ai`
Full public API	`/mcp` or `/mcp/full`

List packs:

curl -s 'https://YOUR.api.karzoun.chat/mcp/packs'

You can also pass ?pack=customer-support or header x-mcp-pack: customer-support on /mcp.

Transport

Hosted MCP is stateless Streamable HTTP (JSON responses). Official MCP clients still send initialize then tools/list / tools/call as separate POSTs — no sticky mcp-session-id is required across gateway pods.

Initialize example

curl -s -X POST 'https://YOUR.api.karzoun.chat/mcp/customer-support' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Authorization: Bearer kz_live_YOUR_API_KEY' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": { "name": "my-agent", "version": "1.0.0" }
    }
  }'

List tools

curl -X POST 'https://YOUR.api.karzoun.chat/mcp/customer-support' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Authorization: Bearer kz_live_YOUR_API_KEY' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

Call a tool

curl -X POST 'https://YOUR.api.karzoun.chat/mcp/customer-support' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Authorization: Bearer kz_live_YOUR_API_KEY' \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "customers",
      "arguments": { "page": 1, "perPage": 5 }
    }
  }'

Architecture pattern

Store tokens in a secrets manager; inject per tenant if you operate multi-tenant SaaS.

Limits

Same GraphQL permissions and rate behavior as direct API calls
Hosted /mcp POSTs: default 120 req/min per credential (MCP_RATE_LIMIT_PER_MIN)
GraphQL fetch timeout: default 30s (KARZOUN_MCP_FETCH_TIMEOUT_MS)
Default 512 KB tool response cap (configurable on self-hosted gateway mounts)
See Security for rotation and scoping

Next steps

AI app connectors — Claude, Manus, ChatGPT, Cursor remote
Agent patterns — Hosted worker prompts
How it works — Error and size limits
Troubleshooting — Auth and connection errors

Overview

Setup

Guides

Tools

Hosted MCP (/mcp)

When to use hosted

Authentication

Packs (tool subsets)

Transport

Initialize example

List tools

Call a tool

Architecture pattern

Limits

Next steps

​When to use hosted

​Authentication

​Packs (tool subsets)

​Transport

​Initialize example

​List tools

​Call a tool

​Architecture pattern

​Limits

​Next steps

When to use hosted

Authentication

Packs (tool subsets)

Transport

Initialize example

List tools

Call a tool

Architecture pattern

Limits

Next steps