How to Set Up MCP Servers in Windsurf: A Complete Guide

Windsurf's Cascade AI is a capable coding assistant out of the box. But without external connections, it works only with what's in your project — it can't check your GitHub issues, query your database, or fetch current library documentation.

MCP servers fix that. Here's how to set them up in Windsurf, which ones are worth adding, and where you'll run into the protocol's limits.

How MCP Works in Windsurf

Windsurf supports the Model Context Protocol (MCP) through its Cascade AI system. When you add an MCP server to Windsurf, Cascade gains access to the tools that server exposes — and can call them autonomously during agent sessions without you manually pasting in data.

Windsurf's MCP implementation follows the same open standard used by Claude Code, Cursor, and GitHub Copilot Agent. Any MCP server that runs in those environments generally works in Windsurf as well.

Setting Up MCP Servers in Windsurf

Via the Windsurf Settings UI

1. Open Windsurf
2. Go to Settings → AI Tools → MCP Servers (or search "MCP" in the Settings panel)
3. Click Add Server
4. Enter the server name, command, arguments, and environment variables
5. Save — Windsurf picks up the server on the next Cascade session

This is the recommended starting point for individual setup.

Via Configuration File

Windsurf reads MCP server configuration from your local settings. For team-wide configuration, consult your Windsurf version's documentation for the config file location — Windsurf has updated its configuration approach across versions, and the exact file path may vary between releases.

The configuration format follows the standard MCP structure:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token"
      }
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your_brave_key"
      }
    }
  }
}

Check Settings → AI Tools for the exact configuration file path in your installed version.

MCP Servers Worth Adding to Windsurf

GitHub

{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": { "GITHUB_TOKEN": "ghp_your_token" }
}

Cascade gains access to your repositories — it can fetch pull requests, read file contents, list issues, and check commit history without you copying and pasting that context in manually.

Best for: Feature development tied to GitHub issues, code review prep, release notes generation.

Brave Search

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

Gives Cascade real-time web access. It can search for current documentation, error resolutions, and recent package updates — instead of relying on training data from months ago.

Best for: Framework migrations, debugging unfamiliar errors, evaluating new dependencies.

PostgreSQL

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

Direct database access — Cascade can inspect your actual schema, run SELECT queries, and validate migration scripts against real data rather than guessing structure.

Security: Use a read-only database user. Never give an AI agent write access to production data through an MCP server.

Filesystem

{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"]
}

Extends Cascade's file access beyond the open project. Useful for referencing shared config files, documentation libraries, or code from other local projects.

Notion

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

Gives Cascade read access to your team's Notion workspace — specs, architecture decisions, runbooks, design docs. Windsurf users who work from detailed Notion specs benefit significantly from this.

Memory

{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-memory"]
}

Persistent storage across sessions. Cascade can remember project conventions, decisions from previous sessions, and custom preferences without you re-explaining them each time.

What Makes Windsurf's MCP Different from Claude Code

Windsurf and Claude Code both implement the MCP standard, but they differ in how the AI integrates tool calls into its workflow:

Claude Code — terminal-native, tool calls happen inline with shell commands. MCP servers feel like an extension of the CLI.

Windsurf Cascade — editor-native, tool calls happen within the AI's coding flow. MCP integrates into Cascade's suggestion and editing workflow rather than appearing as explicit command output.

The practical difference: Claude Code users often see explicit tool invocation in the terminal; Windsurf users more often see the results integrated into Cascade's responses and file edits. Both are valid; they reflect different interaction models.

The MCP configuration format and the servers themselves are interchangeable. A GitHub server configured for Claude Code works in Windsurf without modification.

Token Overhead in Windsurf

The same constraint applies in Windsurf as in any MCP-compatible environment: every server you add loads its tool schemas into Cascade's context window.

Windsurf's context window is large, but schema overhead still adds up across multiple servers. Add the servers you actively need; remove ones that aren't pulling their weight.

What MCP Doesn't Cover in Windsurf

Internal integrations — GitHub, databases, internal docs — are well covered by the MCP ecosystem. The gaps appear when workflows require:

Image generation — no production-grade MCP server provides reliable multi-model image generation for agent use.

Video generation — not meaningfully covered in the current MCP server catalog.

Cloud storage and file sharing — uploading files and getting shareable URLs is not unified across MCP servers.

Web page publishing — beyond the standard MCP server ecosystem.

Windsurf users who need these capabilities in their workflows typically use a capability runtime like AnyCap alongside their MCP servers:

# Generate a hero image for the feature you just built
anycap image generate "dashboard UI hero, dark SaaS style"

# Produce a demo video
anycap video generate "60-second product walkthrough, screen recording style"

# Upload build artifacts
anycap drive upload ./dist/assets/

# Publish a preview page
anycap page publish ./dist/index.html

One CLI. One auth flow. No additional schema tokens competing with your Cascade context.

How the two approaches fit together: MCP Servers vs Capability Runtimes →

Troubleshooting Windsurf MCP Issues

If you're unsure whether a server is working: start a Cascade session and ask "What external tools do you have access to?" — it will list tools from all connected servers.

FAQ

Does Windsurf support all MCP servers?

Windsurf supports the full MCP specification. Any server conforming to the standard — including all official Anthropic servers and community servers — works in Windsurf.

Can I use the same MCP servers I configured for Claude Code?

Yes. The servers are the same; only the configuration location differs. The same npx commands and environment variables apply. You'll need to add them again through Windsurf's settings rather than reusing the Claude Code config directly.

Can I share MCP config across my Windsurf team?

Check your Windsurf version's documentation for the config file location, then commit that file to your repo (with credentials managed via environment variables). The approach is the same as Claude Code's .mcp.json — the file path may differ.

Is there an MCP server for Windsurf-specific features?

No. MCP servers expose external capabilities to the AI — they don't give Cascade access to Windsurf's internal features. For Windsurf-specific settings and behavior, use Windsurf's built-in configuration.

Completing the Windsurf Capability Stack

MCP servers give Windsurf access to internal and external integrations. For the capabilities that MCP doesn't cover — media generation, publishing, storage — a capability runtime fills the gap cleanly.

The full picture for Windsurf users:

• Windsurf Image Generation Guide — Generate images directly from your Windsurf workflow
• Windsurf Video Generation Guide — Add video generation to Cascade sessions
• Windsurf Web Search Guide — Give Cascade grounded web search capabilities
• Windsurf Music Generation Guide — Generate audio assets from Windsurf
• Windsurf AI Agent Capabilities Guide — Full overview of everything Cascade can do with the right tools

Read Next

• What Is Model Context Protocol (MCP)? — Understand the protocol you're configuring.
• MCP Servers vs Capability Runtimes — Where MCP ends and the execution layer begins.
• How to Set Up MCP Servers in Cursor — The equivalent guide for Cursor users.