| Symptom | Fix |
|---|---|
Missing KARZOUN_API_URL | Set GraphQL URL in MCP config env |
Missing KARZOUN_APP_TOKEN | Create app token in Developer → Apps |
npx hangs or fails | Ensure Node 18+; try npx -y @karzounchat/mcp-server@latest |
| Server shows red in Cursor | Open Settings → MCP → view logs; fix env typos |
Restart the MCP server after every config change.
- Confirm the server status is connected (green) in Cursor MCP settings
- Check
KARZOUN_MCP_TOOL_PREFIX— an overly narrow prefix may filter out all tools - Update package:
npx -y @karzounchat/mcp-server@latest
- App user group may not include the operation — edit scopes in Developer → Apps
- Token expired or revoked — create a new app token
- Test the same operation in the Playground
{ "error": "Response exceeds 524288 bytes. Narrow your query parameters..." }- Reduce
perPage - Add
searchValueor filters - Raise cap only if needed:
KARZOUN_MCP_MAX_RESPONSE_BYTES=1048576
| HTTP / JSON-RPC | Meaning |
|---|---|
401 Missing x-app-token | Send x-app-token on every request |
400 invalid or missing MCP session | Call initialize first; pass mcp-session-id header on follow-ups |
| Connection drops | Sessions are in-memory; re-initialize after gateway restarts |
See Hosted MCP for the full handshake.
- Explicitly ask: "Use Karzoun MCP tools to …"
- Add agent patterns to project rules
- Verify tools appear in Cursor's MCP tool list for the session
- Verify GraphQL with curl (quickstart)
- Compare tool name in catalog with what the agent called
- Contact support with app id (not the raw token), tool name, and redacted error message