Karzoun Docs

MCP agents inherit exactly the permissions of the app token they use. Treat MCP as production API access, not a sandbox.

Token hygiene

Do	Don’t
Store tokens in env vars, secrets managers, or CI secrets	Commit tokens to git or share in Slack
Create separate apps per environment (dev/staging/prod)	Reuse one token across teams and bots
Rotate when someone leaves or a laptop is lost	Embed tokens in Cursor rules or client-side code
Use minimum scopes in Developer → Apps	Grant all-user access unless required

The JWT from appsAdd is shown once — same rules as authentication.

Tokens live in ~/.cursor/mcp.json or Claude Desktop config on your machine
Anyone with access to your laptop can read them — use full-disk encryption and separate dev tokens
Prefer a dedicated “MCP dev” app with read-only scopes when exploring

Call only from trusted servers you control
Terminate TLS at your edge; never downgrade to HTTP
Pass x-app-token server-side; never forward to browsers or mobile apps
Session ids (mcp-session-id) are not secrets, but tie activity to your server — do not publish them

Before giving an agent write tools (customersAdd, tagsRemove, …):

Create an app limited to the required user group
Test mutations in the Playground
Optionally set KARZOUN_MCP_TOOL_PREFIX to read-only prefixes during development

LLMs can call mutations unexpectedly. Mitigations:

Method	Credential exposure	Best for
MCP stdio	Local machine	Developer productivity
MCP hosted	Backend only	Production agents
GraphQL direct	Your service	Deterministic integrations
Webhooks	Signing secret on your server	Event-driven, no LLM

If a token leaks: