Skip to main content
MCP agents inherit exactly the scopes of the API key or OAuth grant they use, and no more than the person or workspace behind it. Treat MCP as production API access, not a sandbox.

​
Token hygiene

The secret from Developer → API keys is shown once — same rules as authentication.

​
Stdio (local IDE)

  • Keys 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 a separate dev key
  • Prefer a dedicated read-only key when exploring

​
Hosted (/mcp)

  • Call only from trusted servers you control
  • Terminate TLS at your edge; never downgrade to HTTP
  • Pass Authorization: Bearer server-side; never forward the key to browsers or mobile apps
  • Hosted POSTs are rate-limited per credential (default 120/min, MCP_RATE_LIMIT_PER_MIN; set 0 to disable)
  • GraphQL tool calls time out by default after 30s (KARZOUN_MCP_FETCH_TIMEOUT_MS)

​
Permission scoping

Before giving an agent write tools (customersAdd, tagsRemove, …):
  1. Create a key limited to the required scopes (and a user group, for a workspace key)
  2. Test mutations in the Playground
  3. Optionally set KARZOUN_MCP_TOOL_PREFIX to read-only prefixes during development

​
Agent safety

LLMs can call mutations unexpectedly. Mitigations:
  • System prompts that require confirmation before deletes/merges (agent patterns)
  • Read-only keys for analytics agents
  • Audit key usage via Karzoun logs where available

​
Comparison with other integrations

​
Incident response

If a key leaks:
  1. Revoke it in Developer → API keys
  2. Create a new key and update the MCP config or server secrets
  3. Review recent GraphQL activity if audit tools are enabled
Last modified on August 8, 2026