@karzounchat/mcp-server

MCP server that exposes the Karzoun public GraphQL API as MCP tools (allowlisted in public-api-manifest.yaml).

Tools are grouped into packs (same taxonomy is ready for future GraphQL docs modules).

Install / Cursor (stdio)

1. Create an API key in Developer → API keys with the scopes the pack needs
2. Know your tenant GraphQL URL: https://{subdomain}.api.{domain}/graphql

{
  "mcpServers": {
    "karzoun-support": {
      "command": "npx",
      "args": ["-y", "@karzounchat/mcp-server"],
      "env": {
        "KARZOUN_API_URL": "https://YOUR_SUBDOMAIN.api.YOUR_DOMAIN/graphql",
        "KARZOUN_API_KEY": "kz_live_…",
        "KARZOUN_MCP_PACK": "customer-support"
      }
    }
  }
}

| Env | Meaning | |-----|---------| | KARZOUN_API_URL | GraphQL endpoint | | KARZOUN_API_KEY | API key (kz_live_…); tools outside its scopes are refused | | KARZOUN_APP_TOKEN | Legacy app token JWT, used only when no API key is set | | KARZOUN_MCP_PACK | Pack id (default full) | | KARZOUN_MCP_FETCH_TIMEOUT_MS | GraphQL fetch timeout (default 30000) | | KARZOUN_MCP_MAX_RESPONSE_BYTES | Max tool response size (default 524288) |

Hosted gateway also supports:

| Env | Meaning | |-----|---------| | MCP_RATE_LIMIT_PER_MIN | POST /mcp rate limit per app token (default 120; 0 / off disables) |

Tool annotations

Each tool includes MCP annotations from GraphQL kind:

| Kind | Hints | |------|--------| | Query | readOnlyHint: true, idempotentHint: true | | Mutation | readOnlyHint: false, destructiveHint: true |

All tools set openWorldHint: true (live workspace API). Annotations are client hints — app-token scopes remain the authorization boundary.

Tool Zod schemas are cached per pack in-process so hosted HTTP does not rebuild them on every POST. Tokens stay request-scoped and are never cached.

Packs

| Pack | Use for | |------|---------| | customer-support | Inbox, contacts, companies, tags, fields, reply templates | | marketing | Broadcasts, segments, forms, email templates, products | | operations | Tasks, team chat, org, users, products | | whatsapp | WhatsApp messaging, templates, flows, catalog, calling | | automations | Automation flows, nodes, triggers | | integrations | Apps, webhooks, MiniApps, channel integrations | | ai | Knowledge base (+ future AI APIs) | | full | Entire public API (large) |

Products appear in both marketing and operations.

Remote HTTP

https://{subdomain}.api.{domain}/mcp
https://{subdomain}.api.{domain}/mcp/{pack}
GET  https://{subdomain}.api.{domain}/mcp/packs

• Auth: x-app-token (required)
• Pack: path /mcp/customer-support, query ?pack=, or header x-mcp-pack
• Transport: Streamable HTTP stateless JSON mode (multi-pod safe)

Public schema (SDL)

GET https://{subdomain}.api.{domain}/public-api.graphql

Docs/CI canonical: https://dev.api.karzoun.chat/public-api.graphql

Runtime tools use committed generated/mcp-tools.json (includes module + packs).

Regenerating tools

export PUBLIC_API_SDL_URL=https://dev.api.karzoun.chat/public-api.graphql
yarn workspace gateway generate-mcp-tools --schema-url "$PUBLIC_API_SDL_URL" --stats

Requires every allowlisted op to have an operationModules entry and valid packs in the manifest.

Publishing

cd packages/mcp-server
yarn build
npm publish --access public