{"site":{"name":"Koji","description":"AI-native customer research platform that helps teams conduct, analyze, and synthesize customer interviews at scale.","url":"https://www.koji.so","contentTypes":["blog","documentation"],"lastUpdated":"2026-05-21T02:09:03.603Z"},"content":[{"type":"documentation","id":"d81d8f78-b078-4406-b1cc-b57542e6e278","slug":"mcp-troubleshooting","title":"MCP Troubleshooting Guide: Fix Koji MCP Server Connection and Tool Errors","url":"https://www.koji.so/docs/mcp-troubleshooting","summary":"Most Koji MCP issues fall into five categories: authentication errors (401), network blocking (timeout/refused), version mismatches (tools missing from the client), credit and rate limits (402/429), and confirmation-prompt conflicts (Agent mode silently skipping tools). The triage table at the top maps each symptom to a section. Auth fixes cover URL format, API key regeneration, workspace scoping, and header formatting. Network fixes cover corporate firewalls, DNS, and proxy auth. The credits section explains that read tools are always free and only write tools consume plan credits. The quality-gate section explains why some interviews appear filtered out by default and how to include all interviews when needed.","content":"**TL;DR:** Most Koji MCP issues fall into five buckets: authentication errors (401), network blocking (timeout), version mismatches (tools not appearing), credit and rate limits (429), and confused write-tool confirmations (Agent mode refusing to run). This guide walks through each one in order — from quick triage to a deeper fix — so you can go from broken to fully working in under ten minutes. Every check is non-destructive and safe to run in production.\n\n## How to read this guide\n\nSkim the symptom table first. Find the row that matches what you're seeing in Claude Desktop, Cursor, VS Code, Windsurf, or any other MCP client, then jump to the section. Each section starts with the fastest fix and only escalates if that does not work.\n\n## Symptom triage table\n\n| What you see | Most likely cause | Jump to |\n|---|---|---|\n| \"Failed to connect\" or red dot next to koji | Auth or URL wrong | [Auth errors](#auth-errors) |\n| Server connects but no tools listed | Client cache or version | [No tools listed](#no-tools) |\n| Tools work briefly then return 401 | API key revoked or expired | [Auth errors](#auth-errors) |\n| Tool calls hang for 30+ seconds | Network or proxy blocking | [Network issues](#network) |\n| \"credit limit reached\" or 402 | Write tool exhausted plan credits | [Credits and rate limits](#credits) |\n| 429 \"rate limit exceeded\" | Too many calls in short window | [Credits and rate limits](#credits) |\n| Agent mode skips Koji tools silently | Auto-approve rules blocking | [Confirmation prompts](#prompts) |\n| `koji_create_study` returns validation error | StudyQuestion array malformed | [Validation errors](#validation) |\n| Empty results from `koji_get_interviews` | Quality gate filter applied | [Quality gate](#quality) |\n\nIf your symptom is not here, scroll to the bottom — there's a \"still stuck\" section with the exact info to gather before contacting support.\n\n## Auth errors {#auth-errors}\n\n**Symptom:** Red dot, \"Failed to connect\", or 401 returned from every tool call.\n\n### Fix 1: Confirm the URL\n\nThe Koji MCP endpoint is:\n\n```\nhttps://www.koji.so/api/mcp/http\n```\n\nCommon mistakes:\n\n- Using `koji.so` without the `www` — both work, but mixing them across config files can confuse some clients\n- Using `/mcp` instead of `/api/mcp/http`\n- Using the streamable HTTP path when your client only supports SSE, or vice versa (the `[transport]` segment handles both, so `http` is the safe default)\n\nOpen your client's MCP config (`claude_desktop_config.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, or Windsurf settings) and compare the URL exactly.\n\n### Fix 2: Regenerate the API key\n\nAPI keys can be revoked from Koji's settings page. If your key was created more than a few months ago, regenerate it:\n\n1. Open Koji → Settings → API Keys\n2. Click \"Revoke\" next to the old key\n3. Generate a new one\n4. Update every MCP config file that references it\n5. Restart your MCP client (most do not pick up config changes hot)\n\n### Fix 3: Check workspace scoping\n\nIf your account has access to multiple workspaces, API keys are workspace-scoped. A key created in Workspace A will return 401 for any data in Workspace B. Confirm you're operating in the workspace you expect by calling `koji_get_account` first — the response includes the active workspace ID.\n\n### Fix 4: Header formatting\n\nThe Authorization header must be exactly:\n\n```\nAuthorization: Bearer <your-api-key>\n```\n\nNo extra quotes, no \"Token\" prefix, no whitespace. If you used environment variable substitution like `${env:KOJI_API_KEY}`, confirm the variable is actually set in the shell that launched your MCP client (this is the #1 cause of \"but my config looks right!\" auth failures).\n\n## No tools listed {#no-tools}\n\n**Symptom:** The server shows as connected but the tool list is empty, or only some tools appear.\n\nKoji's MCP server exposes exactly 15 tools:\n\n- **Read (7):** `koji_list_studies`, `koji_get_study`, `koji_get_interviews`, `koji_get_transcript`, `koji_get_account`, `koji_get_study_data`, `koji_get_report`\n- **Write (8):** `koji_create_study`, `koji_update_brief`, `koji_publish_study`, `koji_generate_report`, `koji_publish_report`, `koji_configure_study`, `koji_export_data`, `koji_import_respondents`\n\nIf you see fewer than 15:\n\n1. **Restart the MCP client.** Many clients cache the tool list at startup. Cursor, Claude Desktop, and VS Code all need a full restart, not just a reload.\n2. **Check client version.** Older versions of Claude Desktop (pre-November 2025), Cursor (pre-0.45), and VS Code (pre-1.97) had bugs that truncated long tool lists.\n3. **Disable other MCP servers temporarily.** Some clients have a global tool cap (usually 50–100). Other MCP servers may be consuming the slots Koji needs.\n4. **Check `koji_get_account` works.** If that one call succeeds, the connection is healthy — the issue is client-side caching.\n\n## Network issues {#network}\n\n**Symptom:** Tool calls hang for 30+ seconds, then error out. Or you get \"Connection refused\" / \"ENOTFOUND\".\n\n### Corporate network or VPN\n\nMost corporate firewalls block unknown HTTPS endpoints by default. Allowlist:\n\n- `koji.so`\n- `*.koji.so`\n- Port 443\n\nIf you're behind a VPN, confirm split-tunneling is not stripping requests. The MCP transport is plain HTTPS — nothing exotic — so if `curl https://www.koji.so/api/mcp/http` from your terminal succeeds, the client should too.\n\n### DNS\n\nA surprising number of \"broken\" MCP setups are actually DNS issues. Try:\n\n```bash\nnslookup www.koji.so\n```\n\nIf that fails, your DNS resolver is the problem, not Koji.\n\n### Proxy authentication\n\nIf your network requires a proxy with authentication, most MCP clients respect the `HTTPS_PROXY` environment variable. Set it in the shell that launches the client.\n\n## Credits and rate limits {#credits}\n\n**Symptom:** \"credit limit reached\", 402, or 429 errors.\n\n### Read tools never consume credits\n\n`koji_list_studies`, `koji_get_study`, `koji_get_interviews`, `koji_get_transcript`, `koji_get_account`, `koji_get_study_data`, and `koji_get_report` are all free on every plan. If you're getting credit errors on a read tool, something is misconfigured — open a support ticket.\n\n### Write tools consume credits\n\n`koji_create_study` and `koji_import_respondents` consume credits according to your plan tier. If you hit the limit, two options:\n\n1. Upgrade your plan in Settings → Billing\n2. Wait for the next billing cycle (Free plan resets monthly)\n\nFor most teams running customer research at scale, the Growth or Pro tier is dramatically cheaper than the per-incident cost of trying to do this work manually.\n\n### 429 rate limits\n\nKoji applies per-key rate limits to prevent runaway agent loops. If you hit 429:\n\n- Wait 60 seconds and retry — the limit is sliding-window\n- Audit your prompts; agents often fall into \"list studies, get every interview, get every transcript\" loops that explode the call count\n- Consider pre-filtering: ask the agent to list studies first, choose the relevant one, and only then pull interviews from that study\n\nFor detailed limits by plan, see the rate limits documentation.\n\n## Confirmation prompts blocking calls {#prompts}\n\n**Symptom:** Agent mode says \"I can't call that tool\" or silently skips Koji.\n\nMost MCP clients require explicit user approval for tools that mutate state. The first time an agent tries to call `koji_create_study`, you should see a \"Allow once / Always / Deny\" prompt. If you accidentally clicked \"Deny always\" you can reset it:\n\n- **Claude Desktop:** Settings → Developer → Reset tool permissions\n- **Cursor:** Settings → MCP → click the server → \"Reset auto-approvals\"\n- **VS Code:** Settings → search `chat.tools.autoApprove` and edit the JSON\n\nWe recommend the following defaults: auto-approve all read tools, require confirmation for every write tool.\n\n## Validation errors on koji_create_study {#validation}\n\n**Symptom:** `koji_create_study` returns an error like \"questions[2].config invalid\".\n\nKoji supports 6 structured question types:\n\n- `open_ended` — free text, AI follow-up\n- `scale` — numeric rating (default 1–5, can be set up to 1–10)\n- `single_choice` — radio buttons\n- `multiple_choice` — checkboxes\n- `ranking` — drag-to-order\n- `yes_no` — boolean\n\nEach type has a required `config` object. The most common mistakes:\n\n- Passing `options` to an `open_ended` question (not allowed)\n- Forgetting `min` and `max` on a `scale` question\n- Passing fewer than 2 options on a `single_choice` or `multiple_choice` question\n- Passing fewer than 3 items on a `ranking` question\n\nIf you're getting validation errors, ask the agent: \"Show me the exact JSON you're about to send to koji_create_study.\" Reading the payload usually exposes the issue immediately.\n\n## Empty results from koji_get_interviews {#quality}\n\n**Symptom:** You know completions exist, but `koji_get_interviews` returns an empty array.\n\nBy default, the MCP server applies Koji's quality gate — interviews with a quality score below 3 are filtered out. This is intentional: it prevents low-quality data from contaminating downstream AI analysis. If you want raw access to every interview regardless of quality:\n\n- Pass `include_low_quality: true` to `koji_get_interviews`\n- Or check `koji_get_study_data` which returns aggregated counts including filtered-out interviews\n\nFor most workflows, the default filter is the right default. Quality scores 1–2 usually indicate gibberish, accidental submissions, or completion farming.\n\n## Still stuck\n\nIf none of the above resolves your issue, gather the following before contacting support at hi@koji.so:\n\n1. MCP client and version (e.g. \"Cursor 0.47.2\", \"Claude Desktop 1.4.1\")\n2. Exact MCP config block (redact the API key)\n3. The full error message and any stack trace\n4. Whether `koji_get_account` works (if yes, it's a tool-specific issue; if no, it's auth or network)\n5. Approximate time the error first appeared\n\nMost issues are resolved within a few hours. For enterprise customers, response SLAs are part of your contract.\n\n## Why this works the way it does\n\nThe Koji MCP server is deliberately strict about authentication, rate limits, and the quality gate because customer data is sensitive and AI agents are eager. A loose integration would let an enthusiastic agent burn through credits, leak data across workspaces, or surface garbage interviews to downstream analyses. The patterns above — explicit confirmation on writes, quality filtering on reads, per-key rate limits — are what make it safe to leave the integration on in production environments.\n\n## Related resources\n\n- [MCP Overview](/docs/mcp-overview) — what the Koji MCP server does and why it matters\n- [Connect Koji to Claude (MCP)](/docs/mcp-setup-claude) — Claude Desktop setup\n- [Connect Koji to Cursor (MCP)](/docs/mcp-setup-cursor) — Cursor setup\n- [Connect Koji to VS Code (MCP)](/docs/mcp-setup-vscode) — VS Code Copilot Chat setup\n- [Koji MCP Tool Reference](/docs/mcp-tool-reference) — full list of 15 tools and parameters\n- [MCP Authentication and Security](/docs/mcp-authentication-security) — API key best practices\n- [Rate Limits and CORS](/docs/rate-limits-and-cors) — exact per-plan limits\n- [Koji Structured Questions Guide](/docs/structured-questions-guide) — the 6 question types `koji_create_study` accepts\n- [How the Quality Gate Works](/docs/how-the-quality-gate-works) — why some interviews get filtered out\n","category":"Claude & MCP Integration","lastModified":"2026-05-20T03:24:24.169267+00:00","metaTitle":"Koji MCP Troubleshooting: Fix Connection, Auth, and Tool Errors","metaDescription":"Fix the most common Koji MCP server issues — 401 auth errors, network timeouts, missing tools, credit limits, and confirmation conflicts. Triage table plus targeted fixes for every supported client.","keywords":["mcp troubleshooting","koji mcp errors","mcp 401 unauthorized","mcp server not connecting","mcp tools not appearing","mcp rate limit","mcp authentication failed","mcp connection refused"],"aiSummary":"Most Koji MCP issues fall into five categories: authentication errors (401), network blocking (timeout/refused), version mismatches (tools missing from the client), credit and rate limits (402/429), and confirmation-prompt conflicts (Agent mode silently skipping tools). The triage table at the top maps each symptom to a section. Auth fixes cover URL format, API key regeneration, workspace scoping, and header formatting. Network fixes cover corporate firewalls, DNS, and proxy auth. The credits section explains that read tools are always free and only write tools consume plan credits. The quality-gate section explains why some interviews appear filtered out by default and how to include all interviews when needed.","aiPrerequisites":["A Koji account with at least one MCP client configured","Access to edit your MCP client config (Claude Desktop, Cursor, VS Code, or Windsurf)"],"aiLearningOutcomes":["Diagnose Koji MCP issues using the symptom triage table","Fix 401 authentication errors across all MCP clients","Resolve network and proxy issues blocking the Koji MCP endpoint","Understand why tools may be missing and how to refresh the client cache","Distinguish read-tool vs write-tool credit consumption","Configure confirmation prompts to avoid Agent mode silently skipping tools","Debug validation errors when creating studies with structured questions","Understand the quality gate and when to bypass it"],"aiDifficulty":"intermediate","aiEstimatedTime":"10 min read"}],"pagination":{"total":1,"returned":1,"offset":0}}