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

TL;DR: Connecting Koji to Claude Code takes about three minutes. Add Koji as a remote MCP server with claude mcp add --transport http koji https://www.koji.so/api/mcp, run /mcp to complete the OAuth handshake in your browser, and every Claude Code session can now list your studies, read full interview transcripts with structured answers, fetch reports, create new studies, and configure branding — all without leaving the terminal. This is the most powerful surface for engineers who want customer evidence in the same loop where they ship code.

---

Why Run Koji Inside Claude Code

Claude Code is Anthropic's terminal-native coding agent. It already reads your repo, runs your tests, and edits files. What it does not see by default is what your customers actually say in research interviews. Adding the Koji MCP server closes that gap.

Once connected, a Claude Code session can answer questions like:

• "Pull the last five completed interviews from the onboarding study and tell me what users said about the empty state."
• "Create a new study called Q3 Pricing Sensitivity using the Jobs-to-be-Done framework and three scale questions."
• "Show me the quality score distribution for this study, then draft a PRD section based on the top three themes."
• "Read the full transcript for respondent r_abc123, summarize their pain points, and open the file in src/onboarding/ that handles the flow they complained about."

The MCP integration uses the same 15 production tools that Koji exposes to Claude Desktop, Cursor, VS Code Copilot Chat, and Windsurf — so anything you can do in those clients works here too. The difference is workflow: Claude Code keeps you in the terminal, which is where most engineers already live.

Traditional research tools (SurveyMonkey, Typeform, Qualtrics) cannot do this at all. They are dashboards that produce CSVs. Platforms like Koji are AI-native by design, which is why they can speak the Model Context Protocol fluently — every study, interview, and report is addressable as structured data an agent can reason over.

---

Prerequisites

Before you start, make sure you have:

1. Claude Code installed. Install with npm install -g @anthropic-ai/claude-code and confirm with claude --version. You need a recent version with mcp subcommand support.
2. A Koji account. Sign up free — every new account gets 10 free credits for trying out interviews and reports before you commit to a plan.
3. An active internet connection. OAuth authentication redirects through your browser to www.koji.so.
4. A terminal with browser access. OAuth will pop a browser window for sign-in. If you are on a headless server, use the API-key fallback described later in this guide.

You do not need to install any package, run a Docker container, or self-host anything. The Koji MCP server is hosted by Koji at https://www.koji.so/api/mcp and uses HTTP transport with OAuth 2.1.

---

Step 1: Add the Koji MCP Server

From any terminal, run:

claude mcp add --transport http koji https://www.koji.so/api/mcp

This registers Koji as an MCP server named koji in your global Claude Code configuration. To scope it to just the current project instead, add --scope project — this writes a .mcp.json file in the project root that teammates can commit.

Verify the server is registered:

claude mcp list

You should see koji in the output. The server is registered but not yet authenticated.

---

Step 2: Authenticate with OAuth

Open a Claude Code session in any directory:

claude

Inside the session, run:

/mcp

Claude Code shows the list of configured MCP servers. Highlight koji and choose Authenticate. Your default browser opens to a Koji sign-in page. Sign in with the email you used for your Koji account (or sign up if you have not yet). After approving the connection, the browser redirects back to a confirmation page and the terminal updates to show koji: connected.

That is the entire setup. The OAuth token is stored encrypted in your local Claude Code config and refreshed automatically.

---

Step 3: Verify the Connection

Still inside Claude Code, type a natural-language test:

List my Koji studies and show their status.

Claude Code calls the koji_list_studies tool and returns a markdown table of every study in your account: name, status (draft, published, archived), interview count, completed count, and brief completion percentage. If you see your studies, the MCP integration is fully wired.

If you have no studies yet, try:

Create a new Koji study called "Claude Code MCP Test" with the Generative Discovery framework.

Claude Code calls koji_create_study, returns the new study ID, and offers to walk through building the research brief.

---

What You Can Do From Claude Code

The Koji MCP server exposes 15 tools. They split into five clusters:

Read-Only Discovery

• koji_list_studies — list every study with status and counts.
• koji_get_study — fetch a single study with its full brief and progress percentage.
• koji_get_interviews — list completed interviews for a study, each with quality score and themes.
• koji_get_transcript — full transcript plus the structured-answer analysis (quality score, themes, sentiment, follow-up insights).
• koji_get_account — your plan, credit balance, and BYOK status.

Study Creation and Editing

• koji_create_study — create a new study with a full StudyQuestion[] including type, configuration, and probing depth.
• koji_update_brief — iteratively edit the brief: problem, target audience, methodology, and the question list.
• koji_publish_study — flip the study to published so participants can take it.

Analysis and Reports

• koji_get_study_data — aggregated per-question data: averages for scale questions, distribution for single/multiple choice, ranking counts.
• koji_generate_report — kick off a full AI report combining transcripts, structured answers, themes, and quotes.
• koji_get_report — fetch a completed report by ID.
• koji_publish_report — generate a public shareable link.

Customization and Distribution

• koji_configure_study — branding, lead-capture form, settings, and the public slug, all in one tool.
• koji_export_data — CSV or JSON export of any study.
• koji_import_respondents — bulk-import an external respondent list.

Every tool returns structured JSON the agent can reason over, not loose text — which is what makes Claude Code's responses feel grounded in the actual data rather than hallucinated.

---

Real Workflows Engineers Use Daily

Ship a Feature Backed by Evidence

Before opening a PR for the new empty-state design, ask Claude Code: "Pull the five most recent interviews from the onboarding study where the respondent mentioned the empty state. Quote three lines per respondent and tell me which segment they belong to." Paste the quotes straight into the PR description.

Auto-Triage a Bug Report

A support ticket lands. Ask Claude Code: "Are there any interview transcripts in the past 30 days that mention 'export to CSV failing'? Show me the segment and the exact quote." The model uses koji_get_interviews plus koji_get_transcript to surface evidence in seconds.

Generate a Pre-Mortem Research Study

Before shipping a risky feature, run: "Create a Koji study with five open_ended questions probing what could go wrong with the new pricing page, plus one scale question on willingness-to-pay from 1 to 7. Publish it and give me the share link." The model strings together koji_create_study → koji_update_brief → koji_publish_study and hands back the URL.

Draft a PRD From Real Customer Voice

"Run a full report on the Q3 Pricing Sensitivity study, then write a PRD section using the top three themes as headings and the most-quoted respondent line under each." Two MCP calls and one writing task — done.

---

API-Key Fallback for Headless Environments

If you are running Claude Code on a server without a browser (a CI runner, a remote VM, a Docker container), OAuth will not work. Use the API-key fallback instead:

1. In the Koji web app, go to Settings → API Keys → Create API Key. Copy the key.
2. Register the server with the key as a header:

claude mcp add --transport http koji https://www.koji.so/api/mcp \
  --header "Authorization: Bearer YOUR_KOJI_API_KEY"

Now claude sessions on that machine authenticate using the API key, no browser needed.

Store the key in your CI secret manager — never commit it. Rotate it from the same page if you suspect leakage. See API Authentication for the full key lifecycle.

---

Troubleshooting

/mcp shows koji: failed. Run claude mcp remove koji, then re-add with the exact command above. If the OAuth window did not open, check that you do not have a popup blocker on koji.so.

Tool koji_list_studies is unauthorized. Your OAuth session expired. Run /mcp and re-authenticate.

Studies are missing from koji_list_studies results. The tool only returns studies in the workspace you authenticated as. Switch workspaces from the Koji web app, then re-authenticate.

Tool calls time out. Long-running operations like koji_generate_report can take 30–60 seconds while the AI synthesises themes. Claude Code will stream a progress indicator; let it finish.

Claude Code does not see my new study. The list is fetched fresh on every call, but you may need to send a new prompt — Claude Code does not auto-poll. Just ask "List my studies" again.

For deeper debugging, see MCP Troubleshooting which covers HTTP error codes, OAuth scope mismatches, and rate-limit handling.

---

How This Compares to Claude Desktop and Cursor

The same Koji MCP server runs behind all three clients, so capability parity is total. The differences are workflow:

• Claude Desktop is the most natural surface for non-engineers — researchers, PMs, founders. It is a chat window. No code.
• Cursor keeps your code and research side-by-side in an editor. Best when you are actively writing UI that needs to reflect interview learnings.
• VS Code Copilot Chat is the right pick if your team has standardized on Copilot. Same tools, same MCP transport.
• Claude Code (this guide) is the terminal. Best when you live in git, kubectl, and vim, and you want research to be one command away.

Most power users connect Koji to multiple clients — Claude Desktop for browsing studies, Claude Code for shipping work informed by them. The OAuth tokens are scoped per client, so you authenticate each one independently and revoke any of them without affecting the others.

---

Related Resources

• Koji MCP Integration Overview — what MCP is and how Koji uses it
• Connect Koji to Claude Desktop — desktop chat client setup
• Connect Koji to Cursor — IDE-based research workflow
• Connect Koji to VS Code (Copilot Chat) — VS Code-native setup
• MCP Tool Reference — full list of every tool and its parameters
• Structured Questions Guide — the 6 question types Koji supports
• MCP Best Practices — how to prompt the model for the highest-quality research output