{"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-11-18T05:54:39.257Z"},"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 problems fall into five buckets: sign-in (the server never connects or returns 401), plan access (sign-in is refused), missing tools (you approved read access only), network blocking (timeouts), and write calls that need credits or your approval. Koji's MCP server signs you in with OAuth only: you add one URL, `https://www.koji.so/api/mcp/mcp`, approve access in your browser, and the app stores the token. API keys do not work with the MCP server, and an old `Authorization` header in your config is the most common cause of a broken setup. The connector is included on the Interviews and Enterprise plans. Every check below is safe to run.\n\n## How to read this guide\n\nSkim the symptom table first. Find the row that matches what you see in Claude, ChatGPT, Cursor, VS Code, Windsurf or any other MCP client, then jump to the section. Each section starts with the fastest fix.\n\n## Symptom triage table\n\n| What you see | Most likely cause | Jump to |\n|---|---|---|\n| Server never connects, or the browser sign-in never opens | Wrong URL, or an old API-key header in the config | [Sign-in problems](#sign-in) |\n| Koji's consent page refuses to connect | Your plan doesn't include API access | [Plan access](#plan-access) |\n| Tools worked, now every call returns 401 | Access revoked, or the plan changed | [Sign-in problems](#sign-in) |\n| Server connects but only some tools appear | You approved read access only | [Missing tools](#no-tools) |\n| Tool calls hang, then time out | Network or proxy blocking koji.so | [Network issues](#network) |\n| Report generation fails with a credits message | Not enough credits for a report refresh | [Credits](#credits) |\n| Agent mode skips Koji tools silently | A denied or unanswered tool approval | [Confirmation prompts](#prompts) |\n| `koji_create_study` returns a validation error | A question's settings don't match its type | [Validation errors](#validation) |\n| `koji_get_interviews` returns fewer interviews than expected | A filter or the page size | [Fewer interviews than expected](#interviews) |\n\nIf your symptom isn't here, the \"Still stuck\" section at the bottom lists what to send support.\n\n## Sign-in problems {#sign-in}\n\n**Symptom:** The server never connects, the client shows \"Failed to connect\" or a red dot, or every tool call returns 401.\n\n### Fix 1: Confirm the URL\n\nThe Koji MCP endpoint is:\n\n```\nhttps://www.koji.so/api/mcp/mcp\n```\n\nCommon mistakes are a bare `/api/mcp`, an extra path segment, or a typo. Open your client's MCP config (`claude_desktop_config.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, Windsurf's `mcp_config.json`) and compare the URL exactly. You can also copy it from Koji: open **Connect your AI** at the foot of the sidebar and pick the **Other** tab.\n\n### Fix 2: Remove any API key from the config\n\nKoji's MCP server accepts only the OAuth tokens it issues when you sign in through the browser. Koji API keys (from **Settings → API Keys**) are for the REST Headless API and are rejected here. Older setup guides told you to add a block like this:\n\n```json\n\"headers\": {\n  \"Authorization\": \"Bearer YOUR_KOJI_API_KEY\"\n}\n```\n\nDelete the whole `headers` block, so the entry holds only the URL. Then restart or refresh the server in your client. It should open a Koji consent page in your browser. Sign in, approve, and the client stores the token and refreshes it on its own.\n\n### Fix 3: Use the one-click setup\n\nFor Claude, Cursor and VS Code, Koji has a button that adds the server for you. Open **Connect your AI** in the Koji sidebar (or the **Use Koji inside ChatGPT or Claude** card on the dashboard), pick your app's tab and click **Add to Claude**, **Add to Cursor** or **Add to VS Code**. For Claude Code and Codex, the same dialog shows the command to run. Starting from a clean entry fixes most hand-edited configs.\n\n### Fix 4: Reconnect after a 401\n\nIf tools worked before and now return 401, the client's access was revoked or can no longer be refreshed, or your plan changed (see [Plan access](#plan-access)). Disconnect the `koji` server in your client, connect again and approve access.\n\n## Plan access {#plan-access}\n\n**Symptom:** The Koji consent page refuses to connect, or a working connection starts returning 401 after a plan change.\n\nThe MCP connector counts as API access, which is included on the **Interviews** and **Enterprise** plans. On Free and Insights, Koji won't approve the connection, and an existing connection stops working if the account moves to one of those plans. Check your plan in Koji's billing settings, and see the [Plan Comparison Guide](/docs/plan-comparison-guide).\n\n## Missing tools {#no-tools}\n\n**Symptom:** The server shows as connected but only some tools are listed, usually the read tools.\n\nKoji's MCP server has 15 tools, and each one needs a permission you approve on the consent page:\n\n| Permission you approve | Tools |\n|---|---|\n| Read your studies | `koji_list_studies`, `koji_get_study`, `koji_get_study_data`, `koji_get_report` |\n| Read your interviews | `koji_get_interviews`, `koji_get_transcript`, `koji_export_data` |\n| Read your account | `koji_get_account` |\n| Create and publish studies | `koji_create_study`, `koji_update_brief`, `koji_publish_study`, `koji_configure_study` |\n| Generate and publish reports | `koji_generate_report`, `koji_publish_report` |\n| Add respondents | `koji_import_respondents` |\n\nA tool you didn't approve simply doesn't appear. To add write tools, disconnect the server in your client, connect again, and approve the write permissions.\n\nIf tools are missing even though you approved everything:\n\n1. **Restart or refresh the MCP server.** Many clients read the tool list only when the server starts.\n2. **Update the client.** Older client versions handled remote servers and OAuth less reliably.\n3. **Check the client's tool cap.** Some clients limit how many tools can be active across all servers. Turn off servers you don't need.\n4. **Call `koji_get_account`.** If it works, the connection is healthy and the problem is on the client side.\n\n## Network issues {#network}\n\n**Symptom:** Tool calls hang, then time out. Or you get \"Connection refused\" or \"ENOTFOUND\".\n\n### Corporate network or VPN\n\nMany corporate firewalls block unknown HTTPS endpoints. Allowlist:\n\n- `koji.so`\n- `*.koji.so`\n- Port 443\n\nThe browser sign-in also needs to reach `www.koji.so`. If you're on a VPN, confirm split tunnelling isn't dropping requests. The MCP transport is plain HTTPS, so if `curl -I https://www.koji.so` from your terminal succeeds, the client's network path is usually fine.\n\n### DNS\n\nSome \"broken\" MCP setups are DNS problems. Try:\n\n```bash\nnslookup www.koji.so\n```\n\nIf that fails, your DNS resolver is the problem, not Koji.\n\n### Proxy\n\nIf your network requires a proxy, most MCP clients respect the `HTTPS_PROXY` environment variable. Set it in the shell or system settings the client launches from.\n\n## Credits {#credits}\n\n**Symptom:** `koji_generate_report` fails with a message that a report refresh costs credits and your balance is too low.\n\nReading data never uses credits: listing studies, reading interviews and transcripts, fetching reports and exporting data are free. Generating or refreshing a report through the MCP server costs the same as doing it in Koji, 5 credits, and the tool checks your balance first. If it's too low, top up credits or wait for your plan's monthly credits, then try again. Interviews themselves are charged as they are in Koji, whether you launched the study from an AI app or not. See [Plan Comparison Guide](/docs/plan-comparison-guide) for what each plan includes.\n\nAsk your AI app to call `koji_get_account` to see your plan and credit balance before a long session.\n\n### Runaway loops\n\nAI agents sometimes fall into \"list every study, get every interview, read every transcript\" loops. That's slow and can hit your client's own limits. Steer the agent: ask it to list studies first, pick the relevant one, then pull interviews from that study only, using `limit` and `offset` to page.\n\n## Confirmation prompts blocking calls {#prompts}\n\n**Symptom:** Agent mode says it can't call a tool, or silently skips Koji.\n\nMost MCP clients ask before running tools that change data. If you denied a tool, or set it to never run, the agent can't use it. Look in your client's MCP or tool-approval settings for the `koji` server and reset the tool's approval. In VS Code, auto-approval lives in Settings under Chat (search \"auto approve\").\n\nA sensible default: allow the read tools to run without asking, and require confirmation for every write tool (`koji_create_study`, `koji_update_brief`, `koji_publish_study`, `koji_configure_study`, `koji_generate_report`, `koji_publish_report`, `koji_import_respondents`).\n\n## Validation errors on koji_create_study {#validation}\n\n**Symptom:** `koji_create_study` returns an error about one of the questions.\n\nThe server accepts these question types:\n\n- `open_ended`: free text, with AI follow-up\n- `scale`: numeric rating; set the low and high ends and their labels (for example 0 to 10 for NPS, 1 to 5 for satisfaction)\n- `single_choice`: pick one option\n- `multiple_choice`: pick several options\n- `ranking`: put options in order\n- `yes_no`: a yes or no answer\n\nThe most common mistakes are giving options to an `open_ended` question, leaving out the ends of a `scale`, or giving a choice or ranking question too few options. Ask the agent: \"Show me the exact JSON you're about to send to koji_create_study.\" Reading the payload usually shows the problem. The [Structured Questions Guide](/docs/structured-questions-guide) explains each type.\n\n## Fewer interviews than expected {#interviews}\n\n**Symptom:** You know interviews exist, but `koji_get_interviews` returns fewer, or none.\n\n`koji_get_interviews` returns up to 50 interviews per call by default and at most 100. It filters only by what the agent asks for: a `status` (`active`, `completed`, `abandoned`) or an overall `sentiment`. Check:\n\n- **The study.** The agent may have picked a different study with a similar name. Ask it to show the study ID it used.\n- **Filters.** An agent that asked for `completed` only won't see interviews still in progress.\n- **Paging.** For larger studies, ask the agent to page with `offset` until it has them all, or use `koji_get_study_data` for per-question totals across the whole study.\n- **Previews.** Test interviews you ran yourself before launch are not responses and don't appear.\n\nEach interview carries its quality score, so the agent can weigh strong interviews over thin ones. See [Understanding Quality Scores](/docs/understanding-quality-scores).\n\n## Still stuck\n\nIf none of the above fixes it, gather the following before contacting support at hi@koji.so:\n\n1. MCP client and version\n2. The exact `koji` entry from your MCP config (it should contain only the URL)\n3. The full error message\n4. Whether `koji_get_account` works (if yes, it's a tool-specific issue; if not, it's sign-in, plan or network)\n5. Roughly when the error first appeared\n\n## Why it works this way\n\nCustomer interviews are sensitive and AI agents are eager. Koji's MCP server uses browser sign-in instead of pasted keys, so no secret sits in a config file, and you choose on the consent page whether an app can only read or can also create, publish and import. Each tool checks that permission, so an app you gave read access can't change anything.\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 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- [Connect Koji to Windsurf (MCP)](/docs/mcp-setup-windsurf): Windsurf setup\n- [Koji MCP Tool Reference](/docs/mcp-tool-reference): all tools and their parameters\n- [MCP Authentication and Security](/docs/mcp-authentication-security): how sign-in and permissions work\n- [Koji Structured Questions Guide](/docs/structured-questions-guide): the question types `koji_create_study` accepts\n\n\n---\n\n<!-- crosslink:dev-hub -->\n## Related: other ways to connect\n\nThe [Developer Hub](/docs/building-with-ai) is the single starting point for every way to connect to Koji: the MCP server (this section), the REST Headless API, and the embed widget. For a code integration, see [API Authentication](/docs/api-authentication) and [Starting Interviews via API](/docs/starting-interviews-via-api).","category":"Claude & MCP Integration","lastModified":"2026-11-03T05:14:18.161488+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}}