Connect AI apps to hosted 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

Hosted MCP turns your Karzoun workspace into live tools for cloud AI agents — the same GraphQL operations you use in the Playground, exposed as named MCP tools an LLM can call on your behalf.

Use this guide when the AI app runs in the cloud (Claude.ai, Manus, ChatGPT, remote Cursor) and must reach Karzoun over HTTPS, not npx on your laptop.

Your connection details

Collect these once before connecting any client:

# Quick sanity check (save mcp-session-id from response headers)
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":"test","version":"1.0.0"}}}'

Full handshake: Hosted MCP.

What you unlock

Karzoun exposes 75+ tools mapped 1:1 to the public GraphQL API. The agent does not need to invent query syntax — it calls tools by operation name (customers, tasksAdd, webhooks, …).

Browse the full list: tool catalog.

By domain

Prompts that show the power

Once connected, try natural-language requests like:

• "List my 10 most recently updated customers and summarize their tags."
• "Find open tasks assigned to me on the Sales board and group by due date."
• "Search the knowledge base for return policy and draft a short customer reply."
• "Show webhook subscriptions for customer events — which URLs are active?"
• "Find the conversation with alice@example.com and summarize the last 5 messages."

Pair MCP with agent patterns so the model reads before it mutates.

Choose the right client

Rule of thumb: If the client lets you set custom HTTP headers, hosted Karzoun MCP works today. If the client only supports OAuth discovery (common for ChatGPT Apps), you need a small proxy or a backend agent until OAuth is available on Karzoun.

Claude.ai

Claude on the web supports custom remote MCP connectors (Settings → Connectors → Add custom connector).

Manus

Manus supports Custom MCP servers over HTTP — a strong fit for hosted Karzoun because you can point at a public /mcp URL and supply credentials.

ChatGPT Apps & Connectors

OpenAI supports remote MCP through Apps / Connectors (Developer Mode in ChatGPT settings). ChatGPT connects from OpenAI's cloud — local stdio does not work.

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

Cursor (remote)

For teams that prefer not to run npx locally, Cursor supports remote MCP via url + headers in mcp.json.

{
  "mcpServers": {
    "karzoun-hosted": {
      "url": "https://YOUR_SUBDOMAIN.api.karzoun.chat/mcp",
      "headers": {
        "x-app-token": "${env:KARZOUN_APP_TOKEN}"
      }
    }
  }
}

Export KARZOUN_APP_TOKEN in your shell profile (desktop apps may not load .zshrc — use system env or Cursor's supported secret patterns).

Cursor Settings → MCP should show connected with ~75 tools. Prefer local stdio for offline development; use hosted when npx is blocked or you want a single shared endpoint.

Docs: Cursor MCP — remote servers.

Claude Code

Claude Code can register HTTP MCP servers from the CLI:

claude mcp add --transport http karzoun \
  https://YOUR_SUBDOMAIN.api.karzoun.chat/mcp \
  --header "x-app-token: YOUR_APP_TOKEN"

Use a project .mcp.json for repo-scoped access. Rotate tokens via Developer → Apps if the CLI config is shared.

Build your own agent

Any stack that speaks Streamable HTTP MCP can call Karzoun:

Typical hosts: LangGraph, custom Node/Python workers, Zapier-style automations, internal Slack bots.

1. POST initialize → capture mcp-session-id
2. POST tools/list → discover operations
3. POST tools/call → execute with GraphQL-shaped arguments

Examples and curl: Hosted MCP. Prompt design: Agent patterns.

Scope tokens for safer agents

Before connecting a powerful client:

Start with a read-only app, validate prompts, then issue a broader token if needed.

Troubleshooting connectors

More: Troubleshooting.

Next steps

• Hosted MCP — Protocol details and curl reference
• Agent patterns — Reliable multi-step prompts
• Tool catalog — Every operation name
• Security — Token rotation and incident response