How to Set Up MCP Servers in Windsurf IDE (2026 Complete Guide)

TLDR: Windsurf IDE supports MCP servers through its Cascade AI assistant. You configure them in ~/.codeium/windsurf/mcp_config.json. The setup is nearly identical to Claude Desktop — same JSON format, same server types work. Takes under 5 minutes per server.

Last modified: March 22, 2026 | Published: March 22, 2026

---

What Is Windsurf and Why MCP Matters

Windsurf (by Codeium) is one of the fastest-growing AI-native IDEs, competing directly with Cursor. Its Cascade AI assistant handles everything from code generation to multi-file refactoring. MCP (Model Context Protocol) support in Windsurf means you can connect Cascade directly to external tools — databases, GitHub, Notion, file systems, APIs — so it has real-time context beyond just your open files.

If you've used MCP in Claude Desktop or Cursor, Windsurf's implementation will feel immediately familiar. The config format is the same; you just point to a different config file location.

---

Prerequisites

Before starting:

Windsurf IDE installed (download from codeium.com/windsurf)

Node.js 18+ installed (for stdio-based MCP servers)

A paid Windsurf plan (MCP is available on Pro and Teams plans as of early 2026)

Basic familiarity with JSON configuration

---

Step 1: Locate the Windsurf MCP Config File

Windsurf stores MCP configuration at:

macOS / Linux:

~/.codeium/windsurf/mcp_config.json

Windows:

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

If the file doesn't exist yet, create it. The directory should exist after installing Windsurf.

macOS/Linux: create the file if it doesn't exist

touch ~/.codeium/windsurf/mcp_config.json

---

Step 2: Understand the Config Format

The Windsurf MCP config uses the same format as Claude Desktop's claude_desktop_config.json:

{
  "mcpServers": {
    "server-name": {
      "command": "node",
      "args": ["/path/to/server/index.js"],
      "env": {
        "API_KEY": "your-key-here"
      }
    }
  }
}

Each key under mcpServers is the display name for the server. The command is the executable, args are the arguments passed to it, and env injects environment variables.

---

Step 3: Install Your First MCP Server

Let's start with the filesystem MCP server — the most useful one for getting context from local directories.

Install the Filesystem Server

npm install -g @modelcontextprotocol/server-filesystem

Add It to Your Config

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/Documents",
        "/Users/yourname/Projects"
      ]
    }
  }
}

Replace the paths with the directories you want Cascade to have access to. You can list multiple paths.

Restart Windsurf

After saving the config file, restart Windsurf completely (quit and reopen — not just a reload). MCP servers are initialized at startup.

Verify It Worked

Open Cascade in Windsurf and ask: "What MCP tools do you have available?"

If it lists filesystem tools (read_file, list_directory, write_file, etc.), the server is connected.

---

Step 4: Add a GitHub MCP Server

Connect Cascade to your GitHub repositories for context-aware code suggestions, PR summaries, and issue tracking.

Get a GitHub Personal Access Token

1. Go to github.com → Settings → Developer settings → Personal access tokens → Fine-grained tokens
2. Create a new token with permissions: Contents: Read, Issues: Read/Write, Pull requests: Read/Write
3. Copy the token

Install the GitHub Server

npm install -g @modelcontextprotocol/server-github

Add to Config

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/Projects"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "github_pat_your_token_here"
      }
    }
  }
}

Restart Windsurf. You can now ask Cascade to list your repos, read file contents from any branch, create issues, and more.

---

Step 5: Add a Database MCP Server (PostgreSQL / SQLite)

This is where Windsurf MCP gets genuinely powerful — you can ask Cascade to query your database directly while writing code.

PostgreSQL

npm install -g @modelcontextprotocol/server-postgres

"postgres": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-postgres"],
  "env": {
    "POSTGRES_CONNECTION_STRING": "postgresql://user:password@localhost:5432/mydb"
  }
}

SQLite

npm install -g @modelcontextprotocol/server-sqlite

"sqlite": {
  "command": "npx",
  "args": [
    "-y",
    "@modelcontextprotocol/server-sqlite",
    "--db-path", "/path/to/your/database.db"
  ]
}

With a database server connected, you can ask Cascade things like:

"What tables are in this database?"

"Write a query to find all users created in the last 30 days"

"Explain what this schema is doing"

---

Step 6: Connect Notion, Slack, or Other Tools

Notion

Requires a Notion integration token (create at notion.so/my-integrations):

npm install -g @modelcontextprotocol/server-notion

"notion": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-notion"],
  "env": {
    "NOTION_API_TOKEN": "secret_your_notion_token"
  }
}

Brave Search (Web Search)

Give Cascade the ability to search the web in real time:

npm install -g @modelcontextprotocol/server-brave-search

"brave-search": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-brave-search"],
  "env": {
    "BRAVE_API_KEY": "your_brave_api_key"
  }
}

Get a free Brave Search API key at brave.com/search/api.

---

Windsurf vs. Cursor: MCP Configuration Differences

If you've used Cursor, here's how Windsurf compares for MCP setup:

| Feature | Windsurf | Cursor |
|---------|----------|--------|
| Config file location | ~/.codeium/windsurf/mcp_config.json | .cursor/mcp.json (project) or ~/.cursor/mcp.json (global) |
| Config format | Same as Claude Desktop | Same as Claude Desktop |
| Server types supported | stdio, HTTP/SSE | stdio, HTTP/SSE |
| Activation | Restart required | Hot-reload in some versions |
| MCP in UI | Cascade sidebar | Agent panel |
| Plan required | Pro+ | Pro+ |

The core experience is very similar. If you have a working Cursor MCP config, you can copy the mcpServers object directly into your Windsurf config and it will work.

---

Troubleshooting Common Windsurf MCP Issues

Server Not Showing Up in Cascade

1. Make sure Windsurf was fully restarted (not just reloaded)
2. Validate your JSON is syntactically correct — use jsonlint.com
3. Check that the command binary is in your PATH (which npx should return a path)
4. Open the Windsurf developer console (Help → Toggle Developer Tools) and look for MCP-related errors

"Tool Not Available" Errors

This usually means the server started but failed to initialize properly. Common causes:

Missing API keys in the env block

Wrong file paths

Server package not installed (npm install -g may have failed)

Test by running the server manually in your terminal:

npx @modelcontextprotocol/server-filesystem /tmp

If it throws an error, that's your issue to fix before it will work in Windsurf.

Slow Response Times

Some MCP servers (especially those making external API calls) can slow down Cascade responses. If this is an issue:

Disable unused MCP servers in the config

Use local servers (filesystem, SQLite) which have no network latency

Consider running only one server at a time for complex tasks

Config File Location on Windows

Windows paths in JSON need forward slashes or escaped backslashes:

"args": ["C:/Users/yourname/Documents"]
// OR
"args": ["C:\\Users\\yourname\\Documents"]

---

Complete Working Config Example

Here's a full mcp_config.json with 5 commonly used servers:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/Projects",
        "/Users/yourname/Documents"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "github_pat_xxxxxxxxxxxx"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://localhost/myapp_development"
      }
    },
    "notion": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-notion"],
      "env": {
        "NOTION_API_TOKEN": "secret_xxxxxxxxxx"
      }
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "BSAxxxxxxxxxx"
      }
    }
  }
}

---

What You Can Do With MCP in Windsurf

Once your servers are running, practical use cases with Cascade:

"Read the README in my Projects/myapp folder and summarize the architecture" (filesystem)

"Find all open GitHub issues labeled 'bug' in my repo and group them by component" (github)

"Write a migration to add an index to the users table based on the current schema" (postgres)

"Search my Notion workspace for documentation about our API authentication flow" (notion)

"Search the web for the latest Windsurf release notes" (brave-search)

The combination of code context (open files) + MCP tool access (databases, GitHub, docs) is what makes Windsurf with MCP significantly more capable than a standard AI code assistant.

---

Frequently Asked Questions

Does Windsurf MCP work on the free plan?
As of early 2026, MCP support requires a Pro or Teams plan. The free tier does not include MCP server connections.

Can I use the same MCP servers in Windsurf and Cursor simultaneously?
Yes — each IDE reads from its own config file. You can run the same servers in both IDEs at the same time as long as you configure each separately.

How many MCP servers can I connect to Windsurf?
There's no documented hard limit. Practically, 5–10 servers is manageable. More than that can slow down Cascade's tool-selection process.

Does Windsurf support remote MCP servers over HTTP?
Yes — HTTP/SSE transport is supported. Use the url field instead of command:

"my-remote-server": {
  "url": "https://your-server.com/mcp"
}

Is my data sent to Codeium's servers when using MCP?
MCP tool calls (the data read from files, databases, etc.) are included in the context sent to the AI model for processing. Review Codeium's privacy policy for specifics on how this data is handled.