Back to docs
Claude & MCP Integration

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

Diagnose and fix the five most common Koji MCP issues: 401 auth errors, network timeouts, missing tools, credit and rate limits, and confirmation-prompt conflicts. Includes a triage table and copy-paste fixes for Claude Desktop, Cursor, VS Code, and Windsurf.

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.

How to read this guide

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

Symptom triage table

What you seeMost likely causeJump to
Server never connects, or the browser sign-in never opensWrong URL, or an old API-key header in the configSign-in problems
Koji's consent page refuses to connectYour plan doesn't include API accessPlan access
Tools worked, now every call returns 401Access revoked, or the plan changedSign-in problems
Server connects but only some tools appearYou approved read access onlyMissing tools
Tool calls hang, then time outNetwork or proxy blocking koji.soNetwork issues
Report generation fails with a credits messageNot enough credits for a report refreshCredits
Agent mode skips Koji tools silentlyA denied or unanswered tool approvalConfirmation prompts
koji_create_study returns a validation errorA question's settings don't match its typeValidation errors
koji_get_interviews returns fewer interviews than expectedA filter or the page sizeFewer interviews than expected

If your symptom isn't here, the "Still stuck" section at the bottom lists what to send support.

Sign-in problems {#sign-in}

Symptom: The server never connects, the client shows "Failed to connect" or a red dot, or every tool call returns 401.

Fix 1: Confirm the URL

The Koji MCP endpoint is:

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

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

Fix 2: Remove any API key from the config

Koji'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:

"headers": {
  "Authorization": "Bearer YOUR_KOJI_API_KEY"
}

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

Fix 3: Use the one-click setup

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

Fix 4: Reconnect after a 401

If 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). Disconnect the koji server in your client, connect again and approve access.

Plan access {#plan-access}

Symptom: The Koji consent page refuses to connect, or a working connection starts returning 401 after a plan change.

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

Missing tools {#no-tools}

Symptom: The server shows as connected but only some tools are listed, usually the read tools.

Koji's MCP server has 15 tools, and each one needs a permission you approve on the consent page:

Permission you approveTools
Read your studieskoji_list_studies, koji_get_study, koji_get_study_data, koji_get_report
Read your interviewskoji_get_interviews, koji_get_transcript, koji_export_data
Read your accountkoji_get_account
Create and publish studieskoji_create_study, koji_update_brief, koji_publish_study, koji_configure_study
Generate and publish reportskoji_generate_report, koji_publish_report
Add respondentskoji_import_respondents

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

If tools are missing even though you approved everything:

  1. Restart or refresh the MCP server. Many clients read the tool list only when the server starts.
  2. Update the client. Older client versions handled remote servers and OAuth less reliably.
  3. 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.
  4. Call koji_get_account. If it works, the connection is healthy and the problem is on the client side.

Network issues {#network}

Symptom: Tool calls hang, then time out. Or you get "Connection refused" or "ENOTFOUND".

Corporate network or VPN

Many corporate firewalls block unknown HTTPS endpoints. Allowlist:

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

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

DNS

Some "broken" MCP setups are DNS problems. Try:

nslookup www.koji.so

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

Proxy

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

Credits {#credits}

Symptom: koji_generate_report fails with a message that a report refresh costs credits and your balance is too low.

Reading 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 for what each plan includes.

Ask your AI app to call koji_get_account to see your plan and credit balance before a long session.

Runaway loops

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

Confirmation prompts blocking calls {#prompts}

Symptom: Agent mode says it can't call a tool, or silently skips Koji.

Most 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").

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

Validation errors on koji_create_study {#validation}

Symptom: koji_create_study returns an error about one of the questions.

The server accepts these question types:

  • open_ended: free text, with AI follow-up
  • scale: numeric rating; set the low and high ends and their labels (for example 0 to 10 for NPS, 1 to 5 for satisfaction)
  • single_choice: pick one option
  • multiple_choice: pick several options
  • ranking: put options in order
  • yes_no: a yes or no answer

The 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 explains each type.

Fewer interviews than expected {#interviews}

Symptom: You know interviews exist, but koji_get_interviews returns fewer, or none.

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:

  • The study. The agent may have picked a different study with a similar name. Ask it to show the study ID it used.
  • Filters. An agent that asked for completed only won't see interviews still in progress.
  • 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.
  • Previews. Test interviews you ran yourself before launch are not responses and don't appear.

Each interview carries its quality score, so the agent can weigh strong interviews over thin ones. See Understanding Quality Scores.

Still stuck

If none of the above fixes it, gather the following before contacting support at [email protected]:

  1. MCP client and version
  2. The exact koji entry from your MCP config (it should contain only the URL)
  3. The full error message
  4. Whether koji_get_account works (if yes, it's a tool-specific issue; if not, it's sign-in, plan or network)
  5. Roughly when the error first appeared

Why it works this way

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

Related resources


<!-- crosslink:dev-hub -->

Related: other ways to connect

The Developer Hub 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 and Starting Interviews via API.

Related Articles

How the Quality Gate Works

Understand Koji's quality gate — conversations scoring below 3/5 are completely free and don't consume credits, protecting your research budget.

Managing API Keys

Create, configure, and revoke project-level API keys for integrating with the Koji API.

MCP Authentication & Security

How Koji MCP authenticates with OAuth 2.1 and PKCE. Covers the authorization flow, token lifecycle, security model, data privacy, and how to revoke access.

Koji MCP Integration Overview

Connect Koji to Claude, Cursor, and other AI assistants using the Model Context Protocol (MCP). Manage your entire research workflow conversationally — create studies, run interviews, analyze data, and generate reports without leaving your AI assistant.

Connect Koji to Claude (Setup Guide)

Step-by-step guide to connect your Koji account to Claude Desktop, Claude.ai, Cursor, and other MCP clients. Takes under 2 minutes with OAuth — no API keys required.

Connect Koji to Claude Code (CLI): MCP Setup for Engineers

Step-by-step guide to wiring Koji into Anthropic's Claude Code CLI via the Model Context Protocol so you can launch studies, read transcripts, and ship research-informed code from your terminal.

Connect Koji to Cursor: MCP Setup Guide for Product Engineers

Wire the Koji MCP server into Cursor so the editor can pull live customer interview insights, themes, and quality scores while you ship features. Five-minute setup, fifteen tools.

Connect Koji to VS Code (MCP): Setup Guide for Copilot Chat Engineers

Connect Koji's MCP server to VS Code Copilot Chat in under 3 minutes. Pull live customer interviews, transcripts, themes, and structured answers directly into Agent mode for every coding session.

Connect Koji to Windsurf: MCP Setup for AI-Native Coding

Wire Koji into Windsurf (Cascade) in three minutes via the Model Context Protocol so the editor can read interview transcripts, run reports, and ship features grounded in real customer voice.

MCP Tool Reference

Complete reference for all 17 Koji MCP tools. Includes parameters, return data, plan requirements, and example prompts for each tool across read, create, analyze, customize, and distribute categories.

Rate Limits and CORS

Per-key rate limits, X-RateLimit headers, 429 handling with backoff, quota errors, and how CORS works on the Koji API.

Structured Questions in AI Interviews

Mix quantitative data collection — scales, ratings, multiple choice, ranking — with AI-powered conversational follow-up in a single interview.