Karzoun Docs

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.

Open Developer → MCP setup in Karzoun (/developer/mcp-setup) for your tenant-specific endpoint URL and a copy-ready initialize curl example.

Your connection details

Collect these once before connecting any client:

Field	Value
MCP URL	`https://{subdomain}.api.karzoun.chat/mcp`
Auth header	`x-app-token: YOUR_APP_JWT`
Transport	Streamable HTTP (POST + optional GET stream)
Token source	Developer → Apps — authentication guide

# 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.

Never paste app tokens into browser extensions, shared ChatGPT configs, or client-side code. Connect from a trusted AI host or your own backend. See Security.

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

Domain	Example tools	What an agent can do
Contacts & CRM	`customers`, `companies`, `tags`, `tagsTag`	Look up people, segment lists, apply tags
Inbox	`conversations`, `conversationMessageAdd`	Read threads, draft or send replies (within app scope)
Tasks	`tasks`, `tasksAdd`, `tasksBoards`	List work, create follow-ups, inspect boards
Webhooks	`webhooks`, `webhooksAdd`	Register outbound event subscriptions
Knowledge base	`knowledgeBaseSearch`, `knowledgeBaseArticles`	Ground answers in your help content
Apps	`apps`, `appsAdd`	Inspect or rotate integration credentials (admin scope)

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.

Coming soon: screen recording — connect hosted MCP, then run a CRM lookup + tag workflow in one prompt.

Choose the right client

Client	Local stdio	Hosted `/mcp`	Auth Karzoun expects
Cursor	Yes (recommended for dev)	Yes	`x-app-token` header
Claude Desktop	Yes	Remote via Connectors UI	Header or OAuth (client-dependent)
Claude.ai	—	Yes	Custom connector URL; see auth note below
Manus	—	Yes	HTTP + API key / custom headers
ChatGPT Apps	No	Yes (remote only)	Often OAuth 2.1 — see caveat
Claude Code	—	Yes	HTTP transport + headers
Your backend	—	Yes	`x-app-token` on every request

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).

Create an app token

In Karzoun: Developer → Apps → create an app with the permissions your agent needs (start read-only: customers, tags, tasks).

Add the connector

Open Claude Connectors (or Admin → Connectors on Team/Enterprise).
Click Add custom connector.
Server URL: https://{subdomain}.api.karzoun.chat/mcp
If the UI offers Advanced auth fields and your plan supports static credentials, prefer routing through a header-aware client (Cursor remote, Manus, or your backend) until OAuth is documented for Karzoun.

Enable in chat

Use the + menu in a conversation → Connectors → enable Karzoun for that chat.Test: “Using Karzoun tools, run currentUser and list my first 5 tags.”

Claude Desktop for local coding is still best with stdio. Remote connectors in Claude.ai are for cloud sessions — do not add the HTTPS URL to claude_desktop_config.json; use the Connectors UI instead.

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.

Open Custom MCP

Settings → Integrations → Custom MCP (or + Add custom MCP → Direct configuration).

Enter server details

Field	Value
Name	`Karzoun` (or your workspace name)
Transport	`HTTP` / Streamable HTTP
Server URL	`https://{subdomain}.api.karzoun.chat/mcp`
Authentication	API key / Bearer / custom — map to `x-app-token` if the UI exposes a custom header field

If Manus only offers a single API key field and sends Authorization: Bearer, use a thin reverse proxy on your infrastructure that translates Authorization: Bearer <token> → x-app-token: <token> (advanced; keep the proxy private).

Test and use

Manus verifies the server and lists discovered tools. Reference Karzoun in prompts:“Pull my top 10 customers by last updated date and create a Manus doc summarizing their tags.”Official reference: Manus custom MCP docs.

ChatGPT Apps and Connectors

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

Enable developer access

In ChatGPT: Settings → Apps & Connectors (or Connectors → Advanced) → enable Developer mode if available on your plan.

Add your MCP URL

Create a new app/connector and paste:

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

Review discovered tools before enabling the app in conversations.

Many ChatGPT connector flows expect OAuth 2.1 with dynamic client registration. Karzoun hosted MCP authenticates with x-app-token (same as the public GraphQL API), not OAuth discovery endpoints.What works today: connect via Manus, Cursor remote, Claude Code, or your own backend agent calling /mcp directly.For ChatGPT specifically: if connector setup fails at authentication, run Karzoun tools from a backend worker (your server holds the token) or use an MCP gateway that adds OAuth in front of Karzoun. We will document first-party OAuth for ChatGPT when available.

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.

POST initialize → capture mcp-session-id
POST tools/list → discover operations
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:

Goal	App permissions	Optional env
Read-only CRM assistant	Query customers, tags, companies	`KARZOUN_MCP_TOOL_PREFIX` on stdio only
Support triage	Conversations + knowledge base read	Narrow app scope in UI
Integration admin	Webhooks + apps mutations	Separate high-privilege token

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

Troubleshooting connectors

Symptom	Likely cause	Fix
401 Missing `x-app-token`	Header not sent	Add header in client config or proxy
400 invalid session	Skipped `initialize` or stale session	Re-run handshake; see Hosted MCP
Tools empty / permission error	App scope too narrow	Widen permissions; test in Playground
Client cannot reach URL	Private network / localhost	Use public `*.api.karzoun.chat` only
ChatGPT auth fails	OAuth-only connector	Use Manus, Cursor remote, or backend agent

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

Overview

Setup

Guides

Tools

Connect AI apps to hosted MCP

Your connection details

What you unlock

By domain

Prompts that show the power

Choose the right client

Claude.ai

Manus

ChatGPT Apps and Connectors

Cursor (remote)

Claude Code

Build your own agent

Scope tokens for safer agents

Troubleshooting connectors

Next steps

​Your connection details

​What you unlock

​By domain

​Prompts that show the power

​Choose the right client

​Claude.ai

​Manus

​ChatGPT Apps and Connectors

​Cursor (remote)

​Claude Code

​Build your own agent

​Scope tokens for safer agents

​Troubleshooting connectors

​Next steps

Your connection details

What you unlock

By domain

Prompts that show the power

Choose the right client

Claude.ai

Manus

ChatGPT Apps and Connectors

Cursor (remote)

Claude Code

Build your own agent

Scope tokens for safer agents

Troubleshooting connectors

Next steps