Connect Windsurf Editor to a Local MCP Server

Q: Where is the Windsurf MCP config file?

The Windsurf MCP config is at ~/.codeium/windsurf/mcp_config.json on macOS/Linux and %USERPROFILE%\.codeium\windsurf\mcp_config.json on Windows. Create it if it doesn't exist.

What is Windsurf?

Windsurf is Codeium's AI-native code editor with its signature Cascade agentic mode. Cascade can plan and execute multi-step coding tasks across your entire codebase, and with MCP support, it gains access to external tools — APIs, databases, file systems, and anything you build in Agent MCP Studio.

Prerequisites

Windsurf — codeium.com/windsurf
Node.js 18+ — nodejs.org
Agent MCP Studio open at agentmcp.studio

Step-by-Step Setup

Copy your relay URL from Agent MCP Studio

Open the studio → Settings → MCP Relay Bridge. Copy the session URL and click Connect.

Download bridge.js

curl -O https://agentmcp.studio/bridge.js
npm install ws

Edit Windsurf's MCP config

Windsurf stores its MCP configuration at:

macOS / Linux: ~/.codeium/windsurf/mcp_config.json
Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json

{
  "mcpServers": {
    "agent-mcp-studio": {
      "command": "node",
      "args": [
        "/absolute/path/to/bridge.js",
        "wss://agentmcp.studio/api/relay/YOUR-SESSION-UUID"
      ]
    }
  }
}

Restart Windsurf

Fully quit and reopen Windsurf. Open a Cascade chat and look for the tools indicator. Your browser-built tools will be available immediately for Cascade to call.

Troubleshooting

If tools don't appear, check Windsurf's Output panel (View → Output → MCP) for errors
Ensure the config file is valid JSON — trailing commas cause parse errors
Verify the studio shows 🟢 Live in the bridge chip before testing

Frequently Asked Questions

Yes. Windsurf (by Codeium) supports MCP in its Cascade agentic mode. Configure servers in ~/.codeium/windsurf/mcp_config.json and Windsurf's Cascade agent can call your MCP tools during conversations.

The Windsurf MCP config is at ~/.codeium/windsurf/mcp_config.json on macOS/Linux and %USERPROFILE%\.codeium\windsurf\mcp_config.json on Windows. Create it if it doesn't exist.

Cascade is Windsurf's multi-step AI agent that can autonomously plan and execute tasks. MCP tools extend Cascade's capabilities — with Agent MCP Studio you can give Cascade access to custom APIs, databases, and Python scripts built in your browser.

Check: (1) config file path is correct, (2) Node.js is installed and in PATH, (3) relay UUID matches Studio Settings, (4) you clicked Connect in the Studio, (5) Windsurf was fully restarted after editing the config.

Yes — each client connects via its own bridge.js process pointing to your relay URL. Multiple MCP clients can connect to the same relay session simultaneously.

Connect Windsurf's Cascade Agent to Browser-Based MCP Tools