Hosted MCP (/mcp)

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Call Karzoun MCP over Streamable HTTP from your backend — or connect cloud AI apps (Claude, Manus, ChatGPT, remote Cursor) to the same endpoint.

New: Step-by-step connector guide → AI app connectors

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

When to use hosted

Authentication

Every request requires the same header as GraphQL:

x-app-token: YOUR_APP_TOKEN_JWT

Optional: x-subdomain when your gateway routes tenants by header.

Session handshake

1. POST initialize — no mcp-session-id yet
2. Read mcp-session-id from response headers
3. POST tools/list, tools/call, etc. with that header on every follow-up

Sessions are tied to the gateway process — re-initialize after deploys or long idle periods.

Initialize example

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

Save the mcp-session-id header from the response.

List tools

curl -X POST 'https://YOUR.api.karzoun.chat/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'x-app-token: YOUR_TOKEN' \
  -H 'mcp-session-id: YOUR_SESSION_ID' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

Call a tool

curl -X POST 'https://YOUR.api.karzoun.chat/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'x-app-token: YOUR_TOKEN' \
  -H 'mcp-session-id: YOUR_SESSION_ID' \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "tags",
      "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
• 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 — Session and 401 errors