MCP agents inherit exactly the permissions of the app token they use. Treat MCP as production API access, not a sandbox.
| 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.jsonor 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-tokenserver-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_PREFIXto read-only prefixes during development
LLMs can call mutations unexpectedly. Mitigations:
- System prompts that require confirmation before deletes/merges (agent patterns)
- Read-only tokens for analytics agents
- Audit app usage via Karzoun logs where available
| 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:
- Disable or remove the app in Developer → Apps
- Create a new app and update MCP config or server secrets
- Review recent GraphQL activity if audit tools are enabled
- Troubleshooting — Permission and 401 errors
- Tenant webhooks — Outbound events (different threat model)