Back to docs
Claude & MCP Integration

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.

TL;DR: VS Code supports the Model Context Protocol (MCP) inside GitHub Copilot Chat's Agent mode. Adding Koji's MCP server takes about three minutes: create a .vscode/mcp.json file in your workspace (or add to your user settings), paste the Koji server block, start the server and sign in to Koji in your browser. Once connected, Copilot Chat can list studies, fetch interview transcripts, pull structured answers, and even create new studies, so your editor becomes a research-aware coding environment without leaving the file you're working on. The MCP connector is included on the Interviews and Enterprise plans.

Why connect Koji to VS Code

Most engineering teams already live in VS Code. When a PRD lands, you read it there. When a ticket gets groomed, the spec gets pasted into a comment there. When a senior engineer reviews a PR, they leave inline feedback there. But the customer evidence that should be driving every one of those decisions usually lives somewhere else (a Notion doc, a research repo, a Loom recording, a Slack thread), and that distance is where bad product decisions get made.

The Koji MCP integration closes that gap. With MCP wired into VS Code, GitHub Copilot Chat can pull live customer interviews, structured answers, theme analyses, and full study reports directly into the conversation you're already having about code. That means you can:

  • Ask Copilot to write the empty-state copy for a checkout component using verbatim quotes from your last 30 onboarding interviews
  • Generate a one-paragraph PR description that cites the exact pain point a feature solves
  • Have the AI cross-reference a proposed API design against what users said in pricing-research interviews
  • Build a tasklist from a research report without copying a single line by hand

This is the modern alternative to manual research-to-code workflows. Tools like Koji automate the heavy lifting (transcription, quality scoring, structured answer extraction, theme generation) and the MCP server makes that output addressable from any AI surface, including the editor.

Prerequisites

Before you start, confirm you have:

  1. A recent version of VS Code with MCP support. MCP servers are configured through .vscode/mcp.json or your user settings. If you don't see MCP options in Copilot Chat, update VS Code from the command palette ("Check for Updates").
  2. GitHub Copilot. MCP runs inside Copilot Chat's Agent mode. Free Copilot users have limited agent access; paid users get the full experience.
  3. A Koji account on the Interviews or Enterprise plan. The MCP connector counts as API access, which is part of those two plans. On Free and Insights, Koji refuses the sign-in. See the Plan Comparison Guide for what each plan includes.

You don't need an API key. Koji's MCP server uses OAuth 2.1 sign-in: VS Code opens your browser, you sign in to Koji and approve the connection, and VS Code stores the token for you.

Step 1: Create the MCP configuration file

VS Code looks for MCP server definitions in two places:

  • Workspace-level: .vscode/mcp.json inside your project (best for team-shared configs that get checked into git)
  • User-level: your user profile's MCP configuration (best for personal configs you want available in every workspace)

For most engineering teams, workspace-level is the right default: your whole team gets the same toolset without anyone having to wire it up individually.

Create .vscode/mcp.json with the following content:

{
  "servers": {
    "koji": {
      "type": "http",
      "url": "https://www.koji.so/api/mcp/mcp"
    }
  }
}

That's the whole config. There is no headers block and no secret in the file. Koji publishes its OAuth discovery metadata, so VS Code finds the sign-in page on its own and registers itself as a client automatically.

Step 2: Start the server and sign in

Open Copilot Chat (Ctrl/Cmd + Alt + I) and switch to Agent mode from the dropdown. Open the tools picker above the input box; you should see "koji" listed as an available server. Start it (you can also click the Start link VS Code shows above the server entry in mcp.json).

VS Code asks you to confirm that you trust the server, then opens your browser on a Koji consent page. Sign in with your Koji account, review what the connection is asking for, and approve it. The consent page lists each permission in plain words: reading your studies, interviews and account, and, if the client asks for them, creating and publishing studies, generating and publishing reports, and adding respondents.

When you return to VS Code you'll see the Koji tools listed under the server. Access tokens refresh automatically, so you won't be asked to sign in again every session.

If the server doesn't start or no tools appear, jump to the troubleshooting section at the end of this guide.

Step 3: Try your first query

In Agent mode, ask Copilot:

"List my Koji studies and tell me which one has the most completed interviews this week."

Copilot will call koji_list_studies, then for each study call koji_get_interviews, and present a ranked summary. You will see each tool call appear as an expandable block in the chat so you can audit exactly what data was pulled.

High-impact VS Code workflows

The MCP integration becomes really useful when you wire it into your normal engineering rituals. A few patterns that work well:

Writing PR descriptions backed by research

Open the diff for a PR, switch to Copilot Chat Agent mode, and prompt:

"Read my changes and write a PR description. Pull customer quotes from the study pricing-page-v2 to justify the change. Filter to interviews with quality score 4 or above."

Copilot reads the diff, calls koji_get_study_data to fetch structured answers and quality scores, calls koji_get_transcript for the highest-quality interviews, and writes a description that includes verbatim evidence. Reviewers like this because the "why" is quoted, not asserted.

Spec'ing new features against real pain points

When you start a new feature branch, ask Copilot to brief you:

"Before I start on the new search feature, summarize the top 5 themes from my search-pain-points study and identify the structured answers where users rated discoverability below 3 on the scale question."

This works because Koji's MCP server returns per-question aggregations (averages, distributions, and option counts), so the AI can do real quantitative reasoning, not just text retrieval.

Closing the loop on bug reports

When you fix a bug that came out of a customer interview, ask:

"Create a Koji study called 'Search relevance fix follow-up' with the participants from my previous search study who reported issues. Use a hybrid interview mode with 4 questions about whether the new behavior fixed their problem."

This calls koji_create_study with a full question list, which can use any of the 6 structured question types Koji supports (open ended, scale, single choice, multiple choice, ranking, yes/no), and koji_import_respondents to add the participants. Closed-loop research without leaving the editor.

Pre-deploy sentiment check

Before merging to main on a Friday, run:

"Check my last 50 interviews across all studies for any new mentions of 'crash', 'freeze', or 'login'. List the top 5 most urgent."

Copilot uses Koji's theme analysis output to scan recent interviews, surfacing anything that should block the release.

Sharing the config with your team

Once you have .vscode/mcp.json working, commit it to your repository. Every teammate who clones the repo will see the Koji server listed in their Copilot Chat tools. Each person signs in with their own Koji account on first use, so everyone sees only the studies they have access to, and the config file never contains a secret.

Some teams add a one-line note to their README.md:

"Open Copilot Chat in Agent mode, start the koji MCP server, and sign in to Koji when your browser opens. You need a Koji seat on our Interviews or Enterprise workspace."

This gets new hires productive in their first hour.

Configuring confirmation prompts for write tools

Koji's MCP server includes 7 write tools: koji_create_study, koji_update_brief, koji_publish_study, koji_configure_study, koji_generate_report, koji_publish_report and koji_import_respondents. Each one is only available when you approved the matching write permission on the consent page. You probably do not want Copilot calling these without your explicit approval.

VS Code's MCP implementation asks for confirmation before tool calls by default. You can adjust auto-approval in Settings (search for "auto approve" under Chat). We recommend leaving auto-approve off for any tool whose name starts with koji_create, koji_publish, koji_configure, koji_update or koji_import. Read tools (koji_list_*, koji_get_*, koji_export_data) can usually be auto-approved safely.

Quick troubleshooting

SymptomLikely causeFix
Browser sign-in never opensPopup or default-browser issueRestart the server from the tools picker and allow koji.so to open
Sign-in completes but the server stays unauthorizedYour account isn't on a plan with API accessThe MCP connector needs the Interviews or Enterprise plan
Server starts but no tools listedOlder VS Code version, or permissions not approvedUpdate VS Code, then restart the server and approve the consent page
"Connection refused" or timeoutCorporate network blocks koji.soAllow koji.so and *.koji.so in your proxy
Write tools missingYou approved read permissions onlySign out of the server in VS Code and sign in again, approving the write permissions

For a deeper troubleshooting walkthrough, see the dedicated MCP troubleshooting guide linked below.

Why this matters

Static surveys, screenshotted quotes, and stale PDF reports have always been the weakest part of customer research. They get out of sync the moment they're produced. The MCP integration is different: the AI inside your editor reads live data every time you ask, with each interview's quality score attached and structured by the same questions your research team designed. That makes the research durable: it can be referenced indefinitely without anyone updating a doc.

For engineering teams that want their code to match what customers said, the VS Code and Koji MCP setup is one of the quickest integrations to get running.

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.

MCP Best Practices — Getting the Most from Koji + Claude

Tips, patterns, and anti-patterns for using Koji MCP effectively. Learn how to write better prompts, choose methodologies, manage token budgets, and build efficient research workflows with AI.

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

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.

MCP Workflow Guide for Product Managers

End-to-end guide for product managers using Koji MCP with Claude to automate customer discovery, validate hypotheses, and generate stakeholder-ready research reports — all from a single conversation.

Real-Time Research Insights: How to See Themes, Quotes, and Quality Scores as Interviews Complete

Stop waiting weeks for analysis — modern AI research platforms surface themes, structured-question distributions, sentiment, and quality-scored quotes the moment each interview ends. Here is how real-time research insights work in Koji and how to design studies that take advantage of them.

Structured Questions in AI Interviews

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