{"site":{"name":"Koji","description":"AI-native customer research platform that helps teams conduct, analyze, and synthesize customer interviews at scale.","url":"https://www.koji.so","contentTypes":["blog","documentation"],"lastUpdated":"2026-05-31T06:24:10.406Z"},"content":[{"type":"documentation","id":"57d1bde0-0fab-4144-8746-97a0c5a50b3b","slug":"mcp-setup-windsurf","title":"Connect Koji to Windsurf: MCP Setup for AI-Native Coding","url":"https://www.koji.so/docs/mcp-setup-windsurf","summary":"Windsurf (Codeium) supports MCP through Cascade. Add Koji as an HTTP MCP server with URL https://www.koji.so/api/mcp via the GUI (Settings → Cascade → MCP Servers) or by editing ~/.codeium/windsurf/mcp_config.json. Authenticate over OAuth 2.1 or use an API key in an Authorization header for headless setups. Cascade gains 15 production tools — read-only discovery (list_studies, get_study, get_interviews, get_transcript, get_account), study creation and editing (create_study, update_brief, publish_study), analysis and reports (get_study_data, generate_report, get_report, publish_report), and customization/distribution (configure_study, export_data, import_respondents). Capability parity with Claude Desktop, Cursor, Claude Code, and VS Code Copilot Chat.","content":"**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.\n\n---\n\n## Why Connect Koji to Windsurf\n\nWindsurf 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.\n\nConnecting the Koji MCP server changes that. Cascade can now answer:\n\n- \"Read the last ten interviews from the activation study and tell me which step of onboarding most users got stuck on.\"\n- \"Create a Koji study with five open-ended questions about the new pricing page and publish it.\"\n- \"Pull the full report for the Q3 Customer Retention study, then refactor the components in `src/dashboards/retention/` to address the top three themes.\"\n- \"Search every transcript for participants who mentioned the export feature and quote their exact words for my PR description.\"\n\nThis 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.\n\n---\n\n## Prerequisites\n\nBefore you start, make sure you have:\n\n1. **Windsurf installed.** Download from [codeium.com/windsurf](https://codeium.com/windsurf). You need a version with Cascade MCP support (most builds shipped after early 2025).\n2. **A Koji account.** [Sign up free](https://www.koji.so). New accounts come with 10 credits for trying out AI interviews and reports.\n3. **A modern browser available** for the one-time OAuth handshake.\n\nYou 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.\n\n---\n\n## Option 1: Configure Koji via the Windsurf GUI\n\nThis is the easiest path:\n\n1. Open Windsurf.\n2. Click the Cascade icon in the right sidebar to open the assistant panel.\n3. Hit the hammer icon (or **Settings → Cascade → MCP Servers**) to open the MCP servers panel.\n4. Click **Add Server**.\n5. Fill in:\n   - **Name:** `koji`\n   - **Transport:** HTTP\n   - **URL:** `https://www.koji.so/api/mcp`\n6. Click **Save**.\n7. Windsurf opens your default browser to a Koji sign-in page. Authenticate with the email on your Koji account.\n8. After you approve the connection, the browser redirects to a confirmation screen and Windsurf shows the server as connected.\n\nVerify with a quick prompt in Cascade:\n\n```\nList my Koji studies and tell me which one has the most completed interviews.\n```\n\nCascade calls `koji_list_studies` and returns a table. If the list appears, you are fully wired.\n\n---\n\n## Option 2: Configure Koji via mcp_config.json\n\nIf 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:\n\n```json\n{\n  \"mcpServers\": {\n    \"koji\": {\n      \"serverUrl\": \"https://www.koji.so/api/mcp\"\n    }\n  }\n}\n```\n\nSave 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.\n\nFor headless or remote-development setups where OAuth is awkward, use API-key auth instead:\n\n```json\n{\n  \"mcpServers\": {\n    \"koji\": {\n      \"serverUrl\": \"https://www.koji.so/api/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer YOUR_KOJI_API_KEY\"\n      }\n    }\n  }\n}\n```\n\nGenerate 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](/docs/api-authentication) for rotation and revocation.\n\n---\n\n## The 15 Tools Cascade Can Call\n\nThe Koji MCP server exposes the same 15 production tools across every client. In Windsurf, they appear in the Cascade tool drawer:\n\n**Read-only discovery (Phase 1)**\n- `koji_list_studies` — list studies with status, counts, and brief completion percentage.\n- `koji_get_study` — fetch a single study with its full brief and progress.\n- `koji_get_interviews` — list completed interviews for a study with per-interview quality scores.\n- `koji_get_transcript` — full transcript + structured analysis (themes, sentiment, quality score, structured answers, follow-up insights).\n- `koji_get_account` — your plan, credit balance, BYOK status.\n\n**Study creation and editing (Phase 2)**\n- `koji_create_study` — create a study with a full `StudyQuestion[]` including type, configuration, and probing depth.\n- `koji_update_brief` — iteratively edit problem, target audience, methodology, and the question list.\n- `koji_publish_study` — flip the study to published.\n\n**Analysis and reports**\n- `koji_get_study_data` — aggregated per-question data: averages for scale, distributions for choice, ranking counts.\n- `koji_generate_report` — kick off a full AI report combining transcripts, structured answers, themes, and quotes.\n- `koji_get_report` — fetch a completed report.\n- `koji_publish_report` — generate a public shareable link.\n\n**Customization and distribution**\n- `koji_configure_study` — branding, lead-capture form, study settings, and the public slug.\n- `koji_export_data` — CSV or JSON export of any study.\n- `koji_import_respondents` — bulk import an external respondent list.\n\nEvery tool returns structured JSON. That structure is what makes Cascade's responses feel grounded in real data instead of hallucinated paraphrase.\n\n---\n\n## Real Workflows in Windsurf\n\n### Refactor a UI Component Based on Customer Voice\n\nOpen 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.\n\n### Ground a PR Description in Evidence\n\nBefore 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.\n\n### Spin Up Pre-Launch Research in One Command\n\nRight 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](/docs/structured-questions-guide) questions about the new pricing page, two [scale](/docs/structured-questions-guide) questions on clarity and willingness-to-pay, and one [yes_no](/docs/structured-questions-guide) question on intent to upgrade. Publish it and give me the share link.\"\n\nCascade 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.\n\n### Triage Support Tickets With Interview Data\n\nA 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.\n\n### Generate a Cross-Study Report\n\nAsk: \"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.\n\n---\n\n## Capability Parity Across MCP Clients\n\nThe Koji MCP server is identical no matter which client connects to it. Windsurf, [Claude Desktop](/docs/mcp-setup-claude), [Cursor](/docs/mcp-setup-cursor), [Claude Code](/docs/mcp-setup-claude-code), and [VS Code Copilot Chat](/docs/mcp-setup-vscode) all see the same 15 tools, the same OAuth scopes, and the same response shapes.\n\nThe differences are workflow, not capability:\n\n- **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.\n- **Cursor** has tighter inline editor integration if your IDE habits are closer to VS Code.\n- **Claude Desktop** is a pure chat surface — ideal for researchers and PMs without an IDE.\n- **Claude Code** lives in the terminal — best for CLI-native engineers.\n- **VS Code Copilot Chat** is the right pick if your team is standardized on Copilot.\n\nYou can connect Koji to multiple clients. OAuth tokens are scoped per client, so revoking one does not affect the others.\n\n---\n\n## Troubleshooting\n\n**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.\n\n**`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.\n\n**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.\n\n**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.\n\n**Windsurf does not show MCP servers in settings.** Update to the latest Windsurf build — early versions did not include the Cascade MCP panel.\n\nFor deeper debugging, see [MCP Troubleshooting](/docs/mcp-troubleshooting).\n\n---\n\n## Security and Permissions\n\nOAuth 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.\n\nIf your organization requires SSO, audit logs, or data residency guarantees, see the enterprise plan options in [Bring Your Own Key](/docs/bring-your-own-key) and contact Koji for SOC 2 documentation.\n\n---\n\n## Related Resources\n\n- [Koji MCP Integration Overview](/docs/mcp-overview) — what MCP is and how Koji uses it\n- [Connect Koji to Claude Desktop](/docs/mcp-setup-claude) — chat-first client setup\n- [Connect Koji to Cursor](/docs/mcp-setup-cursor) — IDE-based research workflow\n- [Connect Koji to Claude Code (CLI)](/docs/mcp-setup-claude-code) — terminal-native setup\n- [Connect Koji to VS Code (Copilot Chat)](/docs/mcp-setup-vscode) — Copilot-native setup\n- [MCP Tool Reference](/docs/mcp-tool-reference) — full parameter list per tool\n- [Structured Questions Guide](/docs/structured-questions-guide) — the 6 question types you can configure\n- [MCP Best Practices](/docs/mcp-best-practices) — prompting patterns that produce the best research output","category":"Claude & MCP Integration","lastModified":"2026-05-31T03:25:20.643196+00:00","metaTitle":"Connect Koji to Windsurf (Cascade) via MCP | Koji Docs","metaDescription":"Wire Koji into Windsurf in 3 minutes. Cascade gains 15 tools to list studies, read transcripts with structured-answer analysis, run AI reports, and create studies — without leaving the editor.","keywords":["koji windsurf mcp","windsurf mcp setup","windsurf cascade mcp","windsurf customer research","ai research windsurf","codeium mcp koji"],"aiSummary":"Windsurf (Codeium) supports MCP through Cascade. Add Koji as an HTTP MCP server with URL https://www.koji.so/api/mcp via the GUI (Settings → Cascade → MCP Servers) or by editing ~/.codeium/windsurf/mcp_config.json. Authenticate over OAuth 2.1 or use an API key in an Authorization header for headless setups. Cascade gains 15 production tools — read-only discovery (list_studies, get_study, get_interviews, get_transcript, get_account), study creation and editing (create_study, update_brief, publish_study), analysis and reports (get_study_data, generate_report, get_report, publish_report), and customization/distribution (configure_study, export_data, import_respondents). Capability parity with Claude Desktop, Cursor, Claude Code, and VS Code Copilot Chat.","aiPrerequisites":["Koji account (free signup)","Windsurf installed with Cascade MCP support","Modern browser for OAuth handshake (or API key for headless)"],"aiLearningOutcomes":["Register Koji as an MCP server in Windsurf","Complete OAuth authentication via Cascade","Use 15 Koji tools from inside the editor","Run real Cascade workflows that combine code edits with research lookups","Configure API-key auth for shared and headless environments"],"aiDifficulty":"beginner","aiEstimatedTime":"5 min"}],"pagination":{"total":1,"returned":1,"offset":0}}