How to Add & Configure MCP in Windsurf: Complete Cascade Setup Guide [2026]

Codeium's Windsurf IDE has emerged as one of the premier agentic development environments of 2026. At the core of Windsurf's capabilities is Cascade—an autonomous collaborative agent that doesn't just autocomplete code, but actively reasons over repository architecture, proposes multi-file diffs, and interacts with developer tools.

To unlock Cascade's full potential, Windsurf natively supports the Model Context Protocol (MCP). Through MCP, Cascade can inspect live PostgreSQL schemas, query local SQLite analytics, trigger headless browser tests via Puppeteer, and query private documentation vector stores.

However, many developers transitioning from Cursor or Claude Desktop stumble when configuring Windsurf. Config file locations, property naming conventions, and environment variable inheritance differ between editors.

In this guide, we break down how Windsurf's MCP subsystem functions, provide exact configuration schemas for Windows, macOS, and Linux, solve common connection drops, and show how to manage your toolchain with 1 command.

Why MCP Supercharges Windsurf's Cascade Agent

Without MCP, Cascade is limited to the files currently open in your workspace. When you ask questions like "Why did this background webhook fail in staging?" or "What foreign keys relate to user_billing?", Cascade has to guess.

With MCP servers attached:

1. Live State Inspection: Cascade calls MCP tools to query your database, inspecting live schemas and indexes before drafting migrations.
2. Deterministic Web Research: Through search servers like Brave Search MCP, Cascade fetches breaking library changes and official API docs without hallucinating outdated methods.
3. Automated Verification: Cascade can run test suites in isolated sandboxes and read formatted test outputs directly through MCP tool returns.

Windsurf Config Architecture & File Locations

Windsurf manages MCP configurations through a dedicated JSON file named mcp_config.json.

OS Configuration File Paths

• Windows:

  textCopy
  %USERPROFILE%\.codeium\windsurf\mcp_config.json

  (e.g., C:\Users\<Username>\.codeium\windsurf\mcp_config.json)

• macOS:

  textCopy
  ~/.codeium/windsurf/mcp_config.json

• Linux:

  textCopy
  ~/.codeium/windsurf/mcp_config.json

Step-by-Step: Adding an MCP Server in Windsurf

Windsurf uses the standard mcpServers root object. Here is a complete, working configuration file demonstrating both Node.js (via npx) and Python (via uvx) transports:

jsonCopy
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\Projects\\my-app"]
    },
    "postgres-inspector": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_URL": "postgresql://postgres:password@localhost:5432/production_replica"
      }
    },
    "git-manager": {
      "command": "uvx",
      "args": ["mcp-server-git"]
    }
  }
}

Activating the Servers in Windsurf:

1. Open Windsurf.
2. Open the Windsurf Settings (gear icon or Ctrl+, / Cmd+,).
3. Navigate to Cascade > Model Context Protocol (MCP).
4. Click Reload Servers.
5. When configured properly, each server will display an active status with a list of available tools.

Top Windsurf MCP Errors & How to Fix Them

1. or

• Cause: Windsurf launched from a desktop shortcut or taskbar does not always inherit your shell's customized $PATH (especially if Node or uv is installed via nvm, fnm, or local user directories).
• Fix: Specify the absolute path to the executable:
  • On Windows: "C:\\Program Files\\nodejs\\npx.cmd" or "C:\\Users\\<User>\\.local\\bin\\uvx.exe"
  • On macOS/Linux: "/usr/local/bin/npx" or "/Users/<User>/.cargo/bin/uvx"

2. Connection Closed (Exit Code 1)

• Cause: Missing environment variables or uninstalled runtime packages cause the process to crash immediately on launch.
• Fix: Run the command manually in your terminal first to verify it boots without error before adding it to mcp_config.json.

3. Stdio Stream Contamination

• Cause: Custom scripts printing log statements (print("Connected") or console.log("Starting server")) into stdout will corrupt the JSON-RPC wire protocol.
• Fix: Always redirect logs in custom servers to stderr (console.error or sys.stderr.write).

1-Click Installation with AIStoreHub CLI

Rather than manually managing JSON syntax and tracking executable paths, use the universal open-source AIStoreHub CLI:

bashCopy
# 1. Install or update the CLI
pip install -U aistorehub

# 2. Search for verified tools
aihub search "postgres"

# 3. Inject into Windsurf automatically
aihub mcp install community/postgres-mcp --client windsurf

The CLI automatically locates your Windsurf config file across Windows, macOS, and Linux, validates the JSON schema, creates a timestamped backup, and injects the verified server configuration.

Top 5 MCP Servers for Windsurf Developers

1. Omniroute MCP: High-performance multi-agent router for terminal execution and complex DAG flows.
2. Postgres Inspector: Allows Cascade to inspect tables, view constraints, and validate migrations.
3. Filesystem Server: Enhances Cascade's ability to search large codebases across project boundaries.
4. Brave Web Search: Gives Cascade live access to official documentation and breaking API releases.
5. Git Graph MCP: Enables Cascade to review diffs and generate conventional git commit messages.