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, 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.
Here is everything you need to know about setting up, debugging, and automating 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 index extracts.
When you equip Windsurf's Cascade with MCP servers:
Live 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 another app.
Fresh Documentation: Cascade fetches real-time API reference docs via Brave Search or Fetch MCP servers instead of hallucinating deprecated package APIs.
Issue Tracking: 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:
Platform Default Config Path
macOS ~/.codeium/windsurf/mcp_config.json
Linux ~/.codeium/windsurf/mcp_config.json
Windows %USERPROFILE%.codeium\windsurf\mcp_config.json
Windsurf UI Shortcut: You can also open this directly from Windsurf by navigating to:
Windsurf Settings → Cascade → Model Context Protocol (MCP) → Open Config.
Official Windsurf MCP Configuration Schema
Windsurf follows the standard Model Context Protocol schema. The root structure contains a mcpServers dictionary:
json
{
"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 Uses MCP Tools
Once your configuration file is saved:
Open the Cascade panel in Windsurf (Cmd + L or Ctrl + L).
Type a prompt requiring external context, such as:
"Inspect the SQLite database schema and write a migration to add a status column to users."
Cascade will automatically list the available MCP tools and request approval before running them.
1-Click Automated Setup with AIStoreHub CLI
Instead of searching for hidden .codeium paths and manually editing JSON files, you can use the open-source AIStoreHub CLI
:
bash
1. Install CLI
pip install aistorehub
2. Add verified MCP servers directly to Windsurf
aistorehub add sqlite --client windsurf
aistorehub add github --client windsurf
The CLI locates your mcp_config.json, backs up your existing configuration, and merges the server safely.
Original deep-dive published at AIStoreHub: Windsurf MCP Setup & Best Practices Guide.
Top comments (0)