Integration Guides7 min read

MCP Integration Guide: Windsurf IDE (2026)

Step-by-step guide to setting up MCP servers in Windsurf IDE. Connect filesystem, databases, GitHub, and web search to supercharge Cascade AI with structured tool access.

By MyMCPTools Team·

Windsurf IDE's Cascade AI is one of the most capable agentic coding assistants available — and MCP servers extend it significantly. With the right MCP configuration, Cascade can read your databases, search the web, manage GitHub issues, and navigate your entire codebase with structured tool access.

This guide walks through setting up MCP servers in Windsurf, from installation to advanced configuration.

MCP Support in Windsurf

Windsurf added MCP server support through its AI plugin system. Cascade can invoke MCP tools natively during its agentic flows — meaning your AI assistant can use these tools proactively while working on tasks, not just when you explicitly ask.

This is different from some editors where MCP is purely prompt-driven. Windsurf's Cascade integration allows the AI to decide when to query a database or search the web as part of solving your problem.

Finding the MCP Configuration File

Windsurf stores MCP configuration in:

  • macOS: ~/.codeium/windsurf/mcp_config.json
  • Windows: %APPDATA%Codeiumwindsurfmcp_config.json
  • Linux: ~/.codeium/windsurf/mcp_config.json

If the file doesn't exist, create it. Windsurf reads this configuration on startup.

Prerequisites

Before configuring MCP servers, ensure:

  • Node.js 18+ installed (node --version to verify)
  • npm available (npm --version)
  • Windsurf version 1.0+ (MCP support requires a recent release)

Step 1: Install Core MCP Servers

Start with the three most useful MCP servers for development workflows:

# Install globally for reliable PATH resolution
npm install -g @modelcontextprotocol/server-filesystem
npm install -g @modelcontextprotocol/server-github
npm install -g @modelcontextprotocol/server-brave-search

Step 2: Create the Configuration File

Create or edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "node",
      "args": [
        "/usr/local/lib/node_modules/@modelcontextprotocol/server-filesystem/dist/index.js",
        "/path/to/your/projects"
      ]
    },
    "github": {
      "command": "node",
      "args": [
        "/usr/local/lib/node_modules/@modelcontextprotocol/server-github/dist/index.js"
      ],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    },
    "brave-search": {
      "command": "node",
      "args": [
        "/usr/local/lib/node_modules/@modelcontextprotocol/server-brave-search/dist/index.js"
      ],
      "env": {
        "BRAVE_API_KEY": "your_brave_api_key"
      }
    }
  }
}

Important: Use absolute paths to the installed modules. Windsurf may not resolve npx the same way your terminal does.

Step 3: Restart Windsurf

Close and reopen Windsurf completely (not just the window — quit the application). MCP servers initialize on startup.

To verify servers loaded, open the Windsurf command palette and search for "MCP" — you should see your configured servers listed as available tools.

Adding Database Access

For projects with database dependencies, the PostgreSQL MCP server is particularly valuable. Cascade can query your schema, check data, and generate migrations with actual knowledge of your database structure.

npm install -g @modelcontextprotocol/server-postgres

Add to your config:

"postgres": {
  "command": "node",
  "args": [
    "/usr/local/lib/node_modules/@modelcontextprotocol/server-postgres/dist/index.js",
    "postgresql://user:password@localhost:5432/your_database"
  ]
}

Use a read-only database user unless you specifically need write access. For development databases, a full-access user is generally fine.

Adding Browser Automation

The Puppeteer MCP server lets Cascade test UI changes, scrape reference data, or verify that your code actually works in a browser — without leaving the IDE.

npm install -g @modelcontextprotocol/server-puppeteer
"puppeteer": {
  "command": "node",
  "args": [
    "/usr/local/lib/node_modules/@modelcontextprotocol/server-puppeteer/dist/index.js"
  ]
}

Using MCP Tools in Cascade

Once configured, Cascade uses MCP tools automatically in agentic mode. You can also invoke them explicitly:

  • Implicit: "Fix the bug in the auth module" — Cascade reads relevant files, queries the database schema if needed, and searches for error patterns
  • Explicit: "Search GitHub issues for any open bugs related to this error" — Cascade invokes the GitHub MCP server directly

Cascade will show you which MCP tools it's using in its action trace, so you can see exactly what it's accessing.

Troubleshooting

MCP servers not appearing in Windsurf: Check that the config file path is exactly right for your OS. Verify Node.js is installed system-wide (not just via nvm). Try running the server command directly in your terminal to catch any errors.

"Module not found" errors: Use the full absolute path to the installed module. On macOS with Homebrew Node, the path might be /opt/homebrew/lib/node_modules/... instead of /usr/local/lib/node_modules/.... Run npm root -g to find your actual global modules directory.

GitHub authentication errors: Ensure your GitHub token has the right scopes: repo for private repos, read:org for organization repos. Generate a fine-grained token scoped to specific repositories for better security.

Cascade doesn't use MCP tools: Make sure you're in Cascade's agentic mode (not chat mode). Some MCP tools are only invoked in agentic flows. Try explicitly asking Cascade to use a specific tool: "Use the filesystem MCP to read the config file."

Recommended Windsurf MCP Stack

For most development workflows, this configuration covers the majority of use cases:

  • Filesystem — Navigate and edit your project files
  • GitHub — Issue tracking, PR context, code search across repos
  • Brave Search — Documentation lookup, error research, library comparisons
  • PostgreSQL — Database schema awareness and query generation

Add Puppeteer when you need browser-based testing, and Slack when you want Cascade to have context from team discussions.

Explore the full MCP server directory for additional integrations, and see our guides for other editors: Cursor, VS Code, and Claude Desktop.

Recommended Tools

Better Stack

Free Plan

Get alerted when your APIs, browser tests, payment pipelines, or MCP server dependencies go down. Used by 100K+ developers.

Start monitoring free →

1Password

14-day Free Trial

Store and inject API keys, payment credentials, tokens, and file access secrets into your MCP server configs. Trusted by 150K+ developers.

Try 1Password free →

🔧 MCP Servers Mentioned in This Article

📁

Filesystem

Secure file operations with configurable access controls. Read, write, and manage files safely.

Local
💻

GitHub MCP Server

The GitHub MCP server is GitHub's official Model Context Protocol integration, giving AI assistants like Claude and Cursor direct, authenticated access to the GitHub platform and its full developer surface. With this MCP server, you can ask your AI to read and write repository files, create and merge branches, open and review pull requests, comment on and close issues, trigger GitHub Actions workflows, search across code repositories with GitHub's code search, and inspect commit history — all through natural-language prompts in your AI interface. Developers use it to supercharge code review workflows, automate issue triage, generate PR descriptions from diffs, bulk-update repository settings, and wire AI agents into CI/CD pipelines. The GitHub MCP server connects via a GITHUB_PERSONAL_ACCESS_TOKEN environment variable with scopes for the operations you need, keeping authentication clean and auditable. Install with Docker: `docker run -e GITHUB_PERSONAL_ACCESS_TOKEN=<token> ghcr.io/github/github-mcp-server` — or configure it as a remote MCP server in Claude Desktop, Cursor, VS Code, Windsurf, and Cline. With over 8,000 GitHub stars, it is the most widely deployed official code-platform MCP server and the reference implementation for AI-native GitHub automation.

Auth required
🔍

Brave Search MCP Server

The Brave Search MCP Server is the official server from Brave that gives AI assistants privacy-first web search through the independent Brave Search API — no tracking, no profiling, and results drawn from Brave's own web index rather than Google or Bing. It exposes five distinct tools that map directly to the Brave Search API endpoints: brave_web_search for general queries with pagination, freshness filters, and safe-search controls; brave_local_search for businesses, restaurants, and points of interest with automatic location filtering; brave_news_search for recent articles and current events; brave_image_search for image discovery; and brave_video_search for finding videos across the web. Authentication uses a single BRAVE_API_KEY (free tier available at brave.com/search/api) or a mounted BRAVE_API_KEY_FILE for Docker-secret setups. Install in Claude Desktop, Cursor, Windsurf, or VS Code with one npx command and choose stdio or streamable-HTTP transport. Because Brave operates its own crawler and index, the Brave Search MCP server is a strong choice for developers who want an alternative to Google-dependent search tools, need reproducible non-personalized results, or care about data privacy in agent workflows — Claude can pull fresh web context, verify facts, and research topics without leaking queries to ad-tech pipelines.

Local
🌍

Puppeteer

Browser automation and web scraping with Puppeteer.

Local

📚 More from the Blog