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

• The key’s scopes may not include the operation — edit it in Developer → API keys
• Key expired or revoked — create a new API key
• 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. Check Status if the outage looks platform-wide (GraphQL gateway or hosted MCP)
2. Verify GraphQL with curl (quickstart)
3. Compare tool name in catalog with what the agent called
4. Contact support with the key id (not the raw key), tool name, and redacted error message