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

TL;DR: Windsurf (Codeium) supports the Model Context Protocol natively through Cascade. Add Koji as a remote MCP server in your ~/.codeium/windsurf/mcp_config.json file (or via the GUI in Settings → Cascade → MCP Servers), authenticate once over OAuth, and Windsurf gains 15 production tools for managing customer research — listing studies, reading transcripts with structured-answer analysis, creating new studies, generating AI reports, and exporting data — without leaving the editor. The same hosted Koji MCP server powers Claude Desktop, Cursor, Claude Code, and VS Code Copilot Chat, so Windsurf users get full capability parity.

---

Why Connect Koji to Windsurf

Windsurf is an AI-native code editor built around Cascade, an agentic assistant that can read your repo, run shell commands, and edit files across multiple steps. What it does not have by default is access to what your customers actually say in interviews.

Connecting the Koji MCP server changes that. Cascade can now answer:

• "Read the last ten interviews from the activation study and tell me which step of onboarding most users got stuck on."
• "Create a Koji study with five open-ended questions about the new pricing page and publish it."
• "Pull the full report for the Q3 Customer Retention study, then refactor the components in src/dashboards/retention/ to address the top three themes."
• "Search every transcript for participants who mentioned the export feature and quote their exact words for my PR description."

This is the workflow that turns customer evidence into shipped code without the copy-paste detour through a research dashboard. Traditional research tools (SurveyMonkey, Typeform, UserTesting) have no MCP server — they end at the CSV. Koji is AI-native by design, which is why every study, interview, transcript, theme, and report is addressable as structured data Cascade can reason over.

---

Prerequisites

Before you start, make sure you have:

1. Windsurf installed. Download from codeium.com/windsurf. You need a version with Cascade MCP support (most builds shipped after early 2025).
2. A Koji account. Sign up free. New accounts come with 10 credits for trying out AI interviews and reports.
3. A modern browser available for the one-time OAuth handshake.

You do not need to install any package or run a Docker container. Koji hosts the MCP server at https://www.koji.so/api/mcp and uses HTTP transport with OAuth 2.1.

---

Option 1: Configure Koji via the Windsurf GUI

This is the easiest path:

1. Open Windsurf.
2. Click the Cascade icon in the right sidebar to open the assistant panel.
3. Hit the hammer icon (or Settings → Cascade → MCP Servers) to open the MCP servers panel.
4. Click Add Server.
5. Fill in:
   • Name: koji
   • Transport: HTTP
   • URL: https://www.koji.so/api/mcp
6. Click Save.
7. Windsurf opens your default browser to a Koji sign-in page. Authenticate with the email on your Koji account.
8. After you approve the connection, the browser redirects to a confirmation screen and Windsurf shows the server as connected.

Verify with a quick prompt in Cascade:

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

Cascade calls koji_list_studies and returns a table. If the list appears, you are fully wired.

---

Option 2: Configure Koji via mcp_config.json

If you prefer to edit configuration files (or want to commit a shared config), open ~/.codeium/windsurf/mcp_config.json and add Koji to the mcpServers block:

{
  "mcpServers": {
    "koji": {
      "serverUrl": "https://www.koji.so/api/mcp"
    }
  }
}

Save the file and restart Windsurf (or reload the Cascade window). The next time you open the MCP panel, koji appears in the list. Click Authenticate and complete the OAuth flow in the browser.

For headless or remote-development setups where OAuth is awkward, use API-key auth instead:

{
  "mcpServers": {
    "koji": {
      "serverUrl": "https://www.koji.so/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KOJI_API_KEY"
      }
    }
  }
}

Generate the API key in the Koji web app at Settings → API Keys → Create API Key. Store it in your secrets manager — never commit it to the repo. See API Authentication for rotation and revocation.

---

The 15 Tools Cascade Can Call

The Koji MCP server exposes the same 15 production tools across every client. In Windsurf, they appear in the Cascade tool drawer:

Read-only discovery (Phase 1)

• koji_list_studies — list studies with status, counts, and brief completion percentage.
• koji_get_study — fetch a single study with its full brief and progress.
• koji_get_interviews — list completed interviews for a study with per-interview quality scores.
• koji_get_transcript — full transcript + structured analysis (themes, sentiment, quality score, structured answers, follow-up insights).
• koji_get_account — your plan, credit balance, BYOK status.

Study creation and editing (Phase 2)

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

Analysis and reports

• koji_get_study_data — aggregated per-question data: averages for scale, distributions for 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.
• koji_publish_report — generate a public shareable link.

Customization and distribution

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

Every tool returns structured JSON. That structure is what makes Cascade's responses feel grounded in real data instead of hallucinated paraphrase.

---

Real Workflows in Windsurf

Refactor a UI Component Based on Customer Voice

Open the file you're refactoring. Ask Cascade: "Read the most recent ten interviews from the dashboards study, find any quotes about the filters panel, and use the patterns the respondents described to refactor FiltersPanel.tsx." Cascade pulls the transcripts, extracts the relevant quotes, and modifies the file with a diff you can review.

Ground a PR Description in Evidence

Before opening a PR, ask: "Pull three direct quotes from interviews where respondents asked for an export feature, and draft a PR description that opens with the customer pain, lists the implementation, and references the quotes with attribution." Cascade composes the description in markdown ready to paste into GitHub.

Spin Up Pre-Launch Research in One Command

Right before shipping a risky feature, ask Cascade to scaffold a fast research study: "Create a Koji study called 'Pricing Page Pre-Launch Test' with three open_ended questions about the new pricing page, two scale questions on clarity and willingness-to-pay, and one yes_no question on intent to upgrade. Publish it and give me the share link."

Cascade strings together koji_create_study → koji_update_brief → koji_publish_study and hands back the URL. You can ship the link to a sample of users before the feature goes live.

Triage Support Tickets With Interview Data

A support ticket arrives. Ask Cascade: "Search every interview in the past 60 days for anyone mentioning 'sync to Salesforce'. Quote the exact lines and tell me which segment they belong to." Cascade returns a deduplicated list of customer pain points that may relate to the ticket — often surfacing a systemic issue rather than a one-off bug.

Generate a Cross-Study Report

Ask: "Generate a full report on the Q3 Customer Retention study and summarize the top three themes alongside the most-quoted line per theme." The model calls koji_generate_report, waits for the AI to complete, then fetches the result with koji_get_report and writes the summary inline.

---

Capability Parity Across MCP Clients

The Koji MCP server is identical no matter which client connects to it. Windsurf, Claude Desktop, Cursor, Claude Code, and VS Code Copilot Chat all see the same 15 tools, the same OAuth scopes, and the same response shapes.

The differences are workflow, not capability:

• Windsurf stands out for agentic, multi-step Cascade flows that span code edits and research lookups. Best when you want a single conversation to read transcripts, refactor a file, and run tests.
• Cursor has tighter inline editor integration if your IDE habits are closer to VS Code.
• Claude Desktop is a pure chat surface — ideal for researchers and PMs without an IDE.
• Claude Code lives in the terminal — best for CLI-native engineers.
• VS Code Copilot Chat is the right pick if your team is standardized on Copilot.

You can connect Koji to multiple clients. OAuth tokens are scoped per client, so revoking one does not affect the others.

---

Troubleshooting

Server stuck on "authenticating". Cancel and retry. Make sure your default browser is not blocked by a popup blocker on koji.so. If your default browser is misconfigured, copy the URL Cascade prints to a working browser.

Tool koji_list_studies returned 401. Your OAuth token expired. Re-authenticate from the MCP panel or, if using API-key auth, verify the key is still valid in the Koji web app.

Studies missing from the list. Each MCP connection is scoped to one workspace. If you have multiple Koji workspaces, sign in to the right one in the browser before re-authenticating.

Cascade times out on koji_generate_report. Report generation can take 30–60 seconds for large studies because the AI synthesises themes across all transcripts. Increase Cascade's tool timeout in settings if needed.

Windsurf does not show MCP servers in settings. Update to the latest Windsurf build — early versions did not include the Cascade MCP panel.

For deeper debugging, see MCP Troubleshooting.

---

Security and Permissions

OAuth is scoped to read and write only Koji data, and Cascade prompts before any write action (creating studies, publishing reports, exporting data) so you stay in control. API-key auth uses the same scopes as your account — revoke at any time from Settings → API Keys. Koji never sends interview content to Codeium or any third party; the MCP server returns data directly to Windsurf over HTTPS.

If your organization requires SSO, audit logs, or data residency guarantees, see the enterprise plan options in Bring Your Own Key and contact Koji for SOC 2 documentation.

---

Related Resources

• Koji MCP Integration Overview — what MCP is and how Koji uses it
• Connect Koji to Claude Desktop — chat-first client setup
• Connect Koji to Cursor — IDE-based research workflow
• Connect Koji to Claude Code (CLI) — terminal-native setup
• Connect Koji to VS Code (Copilot Chat) — Copilot-native setup
• MCP Tool Reference — full parameter list per tool
• Structured Questions Guide — the 6 question types you can configure
• MCP Best Practices — prompting patterns that produce the best research output