Troubleshooting

​

MCP server won’t start (stdio)

​

Tools list is empty

• 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

​

Tool returns permission error

• 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

​

Response exceeds size limit

{ "error": "Response exceeds 524288 bytes. Narrow your query parameters..." }

• Reduce perPage
• Add searchValue or filters
• Raise cap only if needed: KARZOUN_MCP_MAX_RESPONSE_BYTES=1048576

​

Hosted /mcp errors

​

Agent ignores Karzoun tools

• 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

​

Still stuck?

1. Verify GraphQL with curl (quickstart)
2. Compare tool name in catalog with what the agent called
3. Contact support with app id (not the raw token), tool name, and redacted error message