The Complete Guide to Windsurf MCP: How to Configure Model Context Protocol in Codeium Cascade (2026)

Codeium's Windsurf editor has emerged as one of the most powerful AI-native IDEs in software engineering.

At the heart of Windsurf is Cascade—an agentic coding assistant capable of multi-file reasoning, proactive terminal command execution, and codebase-wide indexing.

With native support for the Model Context Protocol (MCP), Cascade can now extend its perception and execution capabilities far beyond the immediate workspace repository. It can query local database schemas, fetch real-time documentation, test live endpoints, and manage cloud resources directly during coding sessions.

However, many developers struggle with manual configuration, missing environment variables, and locating Windsurf's hidden configuration files. This guide details everything you need to set up, debug, and automate MCP in Windsurf.

Why MCP Supercharges Windsurf's Cascade Agent

In standard AI code completion, an LLM only knows what you paste into chat or what its local tree-sitter index extracts.

When you equip Windsurf's Cascade with MCP servers:

• Database Verification: Cascade writes a SQL migration, tests it against your local Docker PostgreSQL replica via MCP, and verifies column types without you switching to pgAdmin.
• Live Documentation: Cascade fetches real-time API reference docs via Brave Search or Fetch MCP servers instead of hallucinating deprecated package APIs.
• Repository Health: Cascade queries your GitHub issue tracker to verify pull request specifications before refactoring code.

Where is Windsurf's mcp_config.json Stored?

Windsurf manages MCP servers through a centralized configuration file named mcp_config.json.

The file is stored in your operating system's Codeium configuration directory:

Official Windsurf MCP Configuration Schema

Windsurf follows the standard Model Context Protocol schema. The root structure contains a mcpServers dictionary:

jsonCopy
{
  "mcpServers": {
    "sqlite-local": {
      "command": "uvx",
      "args": [
        "mcp-server-sqlite",
        "--db-path",
        "/Users/username/projects/analytics/data.db"
      ]
    },
    "github-tools": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_secret_token_here"
      }
    }
  }
}

How Cascade Discovers and Executes MCP Tools

Once you save your mcp_config.json, Windsurf automatically initializes background server processes:

1. Protocol Handshake: Windsurf sends an initialize JSON-RPC request over STDIO to each declared server.
2. Tool Listing: The server responds with tools/list, returning available function names and JSON Schema parameters.
3. Agentic Selection: When prompting Cascade ("Check the user table schema in SQLite and write a migration"), Cascade recognizes that sqlite-local has the read_query tool and invokes it autonomously.
4. Approval Gates: Windsurf displays a confirmation badge before executing state-mutating actions, ensuring full human-in-the-loop safety.

Troubleshooting Windsurf MCP Connection Failures

1. The Red 'Disconnected' Status Icon

• Cause: Windsurf launched the process, but the command exited immediately (Exit Code 1 or Command Not Found).
• Fix: Ensure Node.js and UV are in your system PATH, or provide absolute binary paths:

  jsonCopy
  "command": "/usr/local/bin/npx"  // macOS/Linux
  "command": "C:\\Program Files\\nodejs\\npx.cmd"  // Windows

2. Stdout Pollution Crashing JSON-RPC

• Cause: If your MCP server prints raw debug strings (console.log("Ready")) to stdout, Windsurf's JSON-RPC parser crashes.
• Fix: All custom logs in MCP servers must be routed strictly to stderr (console.error in Node, sys.stderr.write in Python).

3. Stale Tools After Config Edits

• Cause: Windsurf keeps long-lived background processes active.
• Fix: Open the Command Palette (Cmd+Shift+P or Ctrl+Shift+P) and run Developer: Reload Window to force a clean server handshake.

1-Click Installation with AIStoreHub CLI

Instead of manually editing JSON files and risking formatting errors, use the open-source AIStoreHub CLI (pip install aistorehub):

bashCopy
# 1. Install CLI
pip install aistorehub

# 2. Inject verified MCP server into Windsurf
aihub mcp install community/postgres-mcp --client windsurf

# 3. List active Windsurf tools
aihub list --client windsurf

AIStoreHub validates your schema, resolves executable paths, and creates timestamped backups of your ~/.codeium/windsurf/mcp_config.json before applying changes.

Explore hundreds of verified MCP servers, community tools, and autonomous agents in the AIStoreHub Registry.