MCP Troubleshooting Guide: Fix Koji MCP Server Connection and Tool Errors

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.

How to read this guide

Skim 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.

Symptom triage table

If your symptom is not here, scroll to the bottom — there's a "still stuck" section with the exact info to gather before contacting support.

Auth errors {#auth-errors}

Symptom: Red dot, "Failed to connect", or 401 returned from every tool call.

Fix 1: Confirm the URL

The Koji MCP endpoint is:

https://www.koji.so/api/mcp/http

Common mistakes:

• Using koji.so without the www — both work, but mixing them across config files can confuse some clients
• Using /mcp instead of /api/mcp/http
• 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)

Open your client's MCP config (claude_desktop_config.json, .cursor/mcp.json, .vscode/mcp.json, or Windsurf settings) and compare the URL exactly.

Fix 2: Regenerate the API key

API keys can be revoked from Koji's settings page. If your key was created more than a few months ago, regenerate it:

1. Open Koji → Settings → API Keys
2. Click "Revoke" next to the old key
3. Generate a new one
4. Update every MCP config file that references it
5. Restart your MCP client (most do not pick up config changes hot)

Fix 3: Check workspace scoping

If 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.

Fix 4: Header formatting

The Authorization header must be exactly:

Authorization: Bearer <your-api-key>

No 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).

No tools listed {#no-tools}

Symptom: The server shows as connected but the tool list is empty, or only some tools appear.

Koji's MCP server exposes exactly 15 tools:

• Read (7): koji_list_studies, koji_get_study, koji_get_interviews, koji_get_transcript, koji_get_account, koji_get_study_data, koji_get_report
• 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

If you see fewer than 15:

1. 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.
2. 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.
3. 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.
4. Check koji_get_account works. If that one call succeeds, the connection is healthy — the issue is client-side caching.

Network issues {#network}

Symptom: Tool calls hang for 30+ seconds, then error out. Or you get "Connection refused" / "ENOTFOUND".

Corporate network or VPN

Most corporate firewalls block unknown HTTPS endpoints by default. Allowlist:

• koji.so
• *.koji.so
• Port 443

If 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.

DNS

A surprising number of "broken" MCP setups are actually DNS issues. Try:

nslookup www.koji.so

If that fails, your DNS resolver is the problem, not Koji.

Proxy authentication

If 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.

Credits and rate limits {#credits}

Symptom: "credit limit reached", 402, or 429 errors.

Read tools never consume credits

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.

Write tools consume credits

koji_create_study and koji_import_respondents consume credits according to your plan tier. If you hit the limit, two options:

1. Upgrade your plan in Settings → Billing
2. Wait for the next billing cycle (Free plan resets monthly)

For 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.

429 rate limits

Koji applies per-key rate limits to prevent runaway agent loops. If you hit 429:

• Wait 60 seconds and retry — the limit is sliding-window
• Audit your prompts; agents often fall into "list studies, get every interview, get every transcript" loops that explode the call count
• Consider pre-filtering: ask the agent to list studies first, choose the relevant one, and only then pull interviews from that study

For detailed limits by plan, see the rate limits documentation.

Confirmation prompts blocking calls {#prompts}

Symptom: Agent mode says "I can't call that tool" or silently skips Koji.

Most 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:

• Claude Desktop: Settings → Developer → Reset tool permissions
• Cursor: Settings → MCP → click the server → "Reset auto-approvals"
• VS Code: Settings → search chat.tools.autoApprove and edit the JSON

We recommend the following defaults: auto-approve all read tools, require confirmation for every write tool.

Validation errors on koji_create_study {#validation}

Symptom: koji_create_study returns an error like "questions[2].config invalid".

Koji supports 6 structured question types:

• open_ended — free text, AI follow-up
• scale — numeric rating (default 1–5, can be set up to 1–10)
• single_choice — radio buttons
• multiple_choice — checkboxes
• ranking — drag-to-order
• yes_no — boolean

Each type has a required config object. The most common mistakes:

• Passing options to an open_ended question (not allowed)
• Forgetting min and max on a scale question
• Passing fewer than 2 options on a single_choice or multiple_choice question
• Passing fewer than 3 items on a ranking question

If 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.

Empty results from koji_get_interviews {#quality}

Symptom: You know completions exist, but koji_get_interviews returns an empty array.

By 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:

• Pass include_low_quality: true to koji_get_interviews
• Or check koji_get_study_data which returns aggregated counts including filtered-out interviews

For most workflows, the default filter is the right default. Quality scores 1–2 usually indicate gibberish, accidental submissions, or completion farming.

Still stuck

If none of the above resolves your issue, gather the following before contacting support at [email protected]:

1. MCP client and version (e.g. "Cursor 0.47.2", "Claude Desktop 1.4.1")
2. Exact MCP config block (redact the API key)
3. The full error message and any stack trace
4. Whether koji_get_account works (if yes, it's a tool-specific issue; if no, it's auth or network)
5. Approximate time the error first appeared

Most issues are resolved within a few hours. For enterprise customers, response SLAs are part of your contract.

Why this works the way it does

The 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.

Related resources

• MCP Overview — what the Koji MCP server does and why it matters
• Connect Koji to Claude (MCP) — Claude Desktop setup
• Connect Koji to Cursor (MCP) — Cursor setup
• Connect Koji to VS Code (MCP) — VS Code Copilot Chat setup
• Koji MCP Tool Reference — full list of 15 tools and parameters
• MCP Authentication and Security — API key best practices
• Rate Limits and CORS — exact per-plan limits
• Koji Structured Questions Guide — the 6 question types koji_create_study accepts
• How the Quality Gate Works — why some interviews get filtered out