{"templateId":"GuidePage","sharedDataIds":{"sidebar":"sidebar-mcp-server/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Troubleshooting","description":"Developer API, partner integration, MCP, SDK, and customer help center.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"troubleshooting","__idx":0},"children":["Troubleshooting"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"mcp-server-wont-start-stdio","__idx":1},"children":["MCP server won't start (stdio)"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Symptom"},"children":["Symptom"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Fix"},"children":["Fix"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Missing KARZOUN_API_URL"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Set GraphQL URL in MCP config ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["env"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Missing KARZOUN_APP_TOKEN"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Create app token in ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Developer → Apps"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["npx"]}," hangs or fails"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ensure Node 18+; try ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["npx -y @karzounchat/mcp-server@latest"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Server shows red in Cursor"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Open ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Settings → MCP"]}," → view logs; fix env typos"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Restart the MCP server after every config change."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"tools-list-is-empty","__idx":2},"children":["Tools list is empty"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Confirm the server status is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["connected"]}," (green) in Cursor MCP settings"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["KARZOUN_MCP_TOOL_PREFIX"]}," — an overly narrow prefix may filter out all tools"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Update package: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["npx -y @karzounchat/mcp-server@latest"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"tool-returns-permission-error","__idx":3},"children":["Tool returns permission error"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["App user group may not include the operation — edit scopes in ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Developer → Apps"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Token expired or revoked — create a new app token"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Test the same operation in the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://karzoun.chat/developer/playground"},"children":["Playground"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"response-exceeds-size-limit","__idx":4},"children":["Response exceeds size limit"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{ \"error\": \"Response exceeds 524288 bytes. Narrow your query parameters...\" }\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Reduce ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["perPage"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Add ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["searchValue"]}," or filters"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Raise cap only if needed: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["KARZOUN_MCP_MAX_RESPONSE_BYTES=1048576"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"hosted-mcp-errors","__idx":5},"children":["Hosted ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/mcp"]}," errors"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"HTTP / JSON-RPC"},"children":["HTTP / JSON-RPC"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401 Missing x-app-token"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Send ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-app-token"]}," on every request"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400 invalid or missing MCP session"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["initialize"]}," first; pass ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mcp-session-id"]}," header on follow-ups"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Connection drops"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Sessions are in-memory; re-initialize after gateway restarts"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/mcp-server/setup/hosted"},"children":["Hosted MCP"]}," for the full handshake."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"agent-ignores-karzoun-tools","__idx":6},"children":["Agent ignores Karzoun tools"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Explicitly ask: ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["\"Use Karzoun MCP tools to …\""]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Add ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/mcp-server/guides/agent-patterns"},"children":["agent patterns"]}," to project rules"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify tools appear in Cursor's MCP tool list for the session"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"still-stuck","__idx":7},"children":["Still stuck?"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify GraphQL with curl (",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/developers/getting-started/quickstart"},"children":["quickstart"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Compare tool name in ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/mcp-server/tools/_generated/catalog"},"children":["catalog"]}," with what the agent called"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Contact support with app id (not the raw token), tool name, and redacted error message"]}]}]},"headings":[{"value":"Troubleshooting","id":"troubleshooting","depth":1},{"value":"MCP server won't start (stdio)","id":"mcp-server-wont-start-stdio","depth":2},{"value":"Tools list is empty","id":"tools-list-is-empty","depth":2},{"value":"Tool returns permission error","id":"tool-returns-permission-error","depth":2},{"value":"Response exceeds size limit","id":"response-exceeds-size-limit","depth":2},{"value":"Hosted /mcp errors","id":"hosted-mcp-errors","depth":2},{"value":"Agent ignores Karzoun tools","id":"agent-ignores-karzoun-tools","depth":2},{"value":"Still stuck?","id":"still-stuck","depth":2}],"frontmatter":{"title":"Troubleshooting","titleTranslationKey":"sidebar.mcp.troubleshooting","audience":"developer","status":"published","locales":["en"],"template":"GuidePage","seo":{"title":"Troubleshooting"}},"lastModified":"2026-06-23T14:20:16.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/mcp-server/guides/troubleshooting","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}