Karzoun MCP is a thin bridge: one MCP tool = one public GraphQL operation. No hidden APIs, no extra abstraction layer.
- The agent picks a tool (e.g.
customerDetail) and passes arguments. - The MCP server builds a GraphQL query or mutation from the committed tool manifest.
- The server POSTs to your tenant GraphQL URL with
x-app-token. - The result is returned as JSON text to the agent.
The same app token permissions apply — if the app cannot run an operation in the Playground, MCP cannot run it either.
Tool names match GraphQL operation names exactly:
| Tool | GraphQL operation |
|---|---|
tags | query tags(...) |
customersAdd | mutation customersAdd(...) |
webhooks | query webhooks(...) |
Browse the full list in the tool catalog. Field-level documentation lives in the GraphQL reference.
Large manifests can overwhelm smaller models. Set a prefix to expose only what you need:
"env": {
"KARZOUN_API_URL": "https://YOUR.api.karzoun.chat/graphql",
"KARZOUN_APP_TOKEN": "YOUR_TOKEN",
"KARZOUN_MCP_TOOL_PREFIX": "customers"
}Only tools whose names start with customers are registered (e.g. customers, customersAdd, customerDetail).
Responses are capped at 512 KB by default (KARZOUN_MCP_MAX_RESPONSE_BYTES). If a list query returns too much data, the tool fails with a clear error — narrow page / perPage or filter arguments, same as pagination in GraphQL.
Failed tools return JSON with an error field:
{ "error": "Permission denied" }HTTP failures, GraphQL validation errors, and oversize responses all surface this way. Teach your agent to read the message and adjust arguments.
| Transport | Process | Token source |
|---|---|---|
| stdio | Local Node process spawned by the IDE | KARZOUN_APP_TOKEN in MCP config env |
| Hosted | Gateway route POST /mcp | x-app-token header per request |
Hosted mode also supports optional x-subdomain when routing through multi-tenant gateways. See Hosted MCP.