Windsurf MCP: Setup, Servers, and the 2026 Stack

Windsurf without MCP is a strong AI editor that knows your codebase.

Windsurf with MCP is a strong AI editor that also knows your live database, your GitHub issues, the current docs of the framework you are pasting into right now, and the stack of saved tweets you swore you would re-read. The gap between those two setups is one JSON file and a restart.

This is the practical guide for 2026. What MCP is in Windsurf, where Cascade reads its config, the servers worth wiring up, and the small mistakes that quietly burn an afternoon.

What MCP actually is in Windsurf

The Model Context Protocol is an open standard released by Anthropic in late 2024 that defines how an AI client talks to tools and data sources outside its own runtime.

In Windsurf, the AI agent is called Cascade. The IDE is the client. MCP servers are separate processes (or remote URLs) that expose tools the agent can call. When you start a conversation with Cascade, it reads the list of available tools from each connected server. When it decides it needs one, it calls the tool, gets the result, and folds the result back into its reasoning.

Without MCP, your AI editor knows whatever was true at training time plus whatever you paste in. With MCP, it queries live systems. The difference between “the docs probably look like this” and “I just read your repo and the docs look like this” is the difference between guessing and knowing.

Windsurf’s official MCP docs are short and practical. The setup is shorter than the docs. Windsurf sits in the “strong native support” tier alongside Cursor and VS Code in our overview of which AI tools support MCP in 2026.

How to add an MCP server to Windsurf (the actual steps)

There are three places to set things up. Pick whichever annoys you least.

The MCP Marketplace. Open the Cascade panel, click the MCP icon in the top right, browse the listed servers, hit Install. Windsurf wires the JSON for you. Best for popular servers (GitHub, Notion, Linear, Postgres). Same registry the rest of the integration ecosystem points at.

Add custom server. Same panel, scroll to the bottom, click Add custom server. Windsurf opens mcp_config.json directly in the editor. Best for anything that is not in the marketplace, or anything you want to manage as code.

Edit the file by hand. The file lives at ~/.codeium/windsurf/mcp_config.json on macOS and Linux, and %USERPROFILE%\.codeium\windsurf\mcp_config.json on Windows. Open it, paste, save. Best when you want a known-good template and zero clicks.

The structure is the same in every case.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${env:GITHUB_TOKEN}"
      }
    },
    "contextbolt-bookmarks": {
      "serverUrl": "https://api.contextbolt.app/mcp/your-token-here"
    }
  }
}

Two transport types matter in 2026.

Stdio servers run locally. Windsurf spawns the process and talks to it through standard input and output. Most local tools (Filesystem, Postgres, SQLite, Git) use stdio. They get command, args, and optional env.

HTTP servers run remotely. Windsurf talks to a URL over the network. Hosted services and personal endpoints (such as the ContextBolt MCP) use this transport. They get a single serverUrl key.

A useful Windsurf-specific touch: mcp_config.json supports variable interpolation. Anywhere in command, args, env, serverUrl, url, or headers you can write ${env:VAR_NAME} and Windsurf swaps in the value of that environment variable at load time. That is the right place to put GitHub tokens, database passwords, and any other secret you do not want sitting in plaintext in a file synced to iCloud.

Once the file is saved, fully quit Windsurf and reopen it. MCP servers load at startup only. A window reload does not pick up new servers. If your server does not appear in Cascade’s MCP panel, the file did not parse, or you reloaded instead of restarting.

The mistakes that eat an afternoon

I have hit enough of these to make a list. Five things that fail silently.

Forgetting the mcpServers root key. If your top-level JSON does not start with "mcpServers": {, Windsurf reads the file and ignores everything in it. No error, no warning, just no servers. Check the brackets first.

Skipping -y on npx commands. Without the -y flag, npx waits for an interactive “should I install this package” prompt. Windsurf cannot answer it, the process hangs, and the server never registers. Always include -y when you launch a server through npx.

Reloading instead of restarting. Cascade only reads mcp_config.json at full startup. Reload Window does not work. Use Cmd-Q on macOS or close every window on Windows, then reopen.

Cramming in 25 servers. Cascade has a hard ceiling of 100 tools across every connected server, documented in the Windsurf MCP integration page. Past that, Windsurf silently drops the extras. There is also a 20 tool calls per prompt cap. Three to six servers is the sweet spot. Anything you have not used in two weeks is dead weight.

Using stdio for a remote service. Stdio assumes the server runs on your machine. If you are pointing Windsurf at a hosted endpoint, you want HTTP transport (the serverUrl key). The ContextBolt MCP, for example, is HTTP only. Trying to npx-install a remote service will sit forever and never start.

The 2026 starter stack

Most “best Windsurf MCP servers” lists give you 15. That is not a stack, that is a tab graveyard. Here is the smaller version, picked by friction not hype.

That stack covers code (GitHub + Filesystem), data (Postgres), docs (Context7), specs (Notion or Linear), and your knowledge layer (ContextBolt). Six servers, well under the 100-tool ceiling, and every one of them earns its keep in a normal week. If you want a longer reasoned list of MCP servers, the 7 best MCP servers for knowledge workers post goes deeper on the non-coding side of the stack.

Adding your knowledge layer to Cascade

Most MCP setup guides stop at “install the GitHub server, you are done.” That misses the highest-leverage piece. The thing your AI editor knows least about is your own brain: the threads you saved when you were skimming X, the Reddit comments that changed how you think about a problem, the LinkedIn posts you bookmarked because the framing was good. None of that is in your repo.

ContextBolt is a Chrome extension that captures your X, Reddit, and LinkedIn bookmarks into a searchable AI knowledge base. The free tier ($0, 150 bookmarks) gives you AI tagging, topic clustering, and semantic search inside the extension. Pro ($6 a month) adds unlimited bookmarks, encrypted cloud sync, and a personal MCP endpoint that any MCP client (Cascade, Claude Desktop, Cursor, Claude Code) can call.

Wiring it into Windsurf is two lines of JSON.

{
  "mcpServers": {
    "contextbolt-bookmarks": {
      "serverUrl": "https://api.contextbolt.app/mcp/your-token-here"
    }
  }
}

Restart Windsurf, open Cascade, and ask “what did I bookmark about Drizzle migrations.” Cascade calls search_bookmarks against your collection, ranks results by semantic match, and you get the three things you actually saved instead of a generic answer pasted from training data. The endpoint also exposes list_clusters, get_cluster_bookmarks, get_recent_bookmarks, and save_bookmark, so Cascade can browse your topic clusters or save a new bookmark mid-chat.

This is the gap most 2026 MCP setup guides miss. Live docs and live code matter, but the difference between a competent agent and a personal one is whether it can read your saved context. For more on that argument, see Personal AI Context Stack for Claude.

Windsurf MCP vs Cursor MCP vs Claude Code MCP

If you use more than one editor, the question is “do I have to redo this everywhere.” The honest answer is: the servers travel, the config files do not.

Windsurf has the highest tool ceiling of the three (100 vs Cursor’s soft ~40). It is the only one of the three with no project-level config, which is fine for personal stacks but awkward in teams where each repo wants different servers. The marketplace is the slickest of the three for non-technical installs. If you also use Cursor, the Cursor MCP setup guide walks through the parallel flow with the same six-server stack.

The one opinion worth holding

You will read a lot of “install these 25 MCP servers” posts in 2026. Almost all of them are wrong.

The ceiling is real. Cascade degrades past 100 tools. Cursor degrades earlier. Claude Code is faster but still loses focus when there is too much surface area to choose from. The agent stops being smart when there are too many doors.

Pick servers the way you pick browser extensions. Three to six. Each one earns its slot or it gets uninstalled within a fortnight. Anything you have not used in two weeks is dead weight, no matter how cool the demo was.

The other thing nobody says out loud: the stack that matters most is not the one your AI vendor sells you. The marketplace is biased toward what is easy to integrate, not what makes you smarter. Your knowledge layer (notes, bookmarks, journal, whatever you are actually reading) is almost never on the front page. That is the slot that will move the needle for personal use, and it is the slot you have to wire up yourself.

What to wire up next

If you have just installed Windsurf and the editor itself feels new, start small. Install Context7. Use it for a week. Notice how often Cascade stops fabricating function names. Then add GitHub. Then a database server pointed at your dev DB.

Once those three feel routine, add your knowledge layer. ContextBolt’s MCP endpoint is two lines of JSON and one restart. Stack with Notion or Linear if your work lives there. That is the full setup most solo builders need.

The full Windsurf MCP integration docs are at docs.windsurf.com/windsurf/cascade/mcp. The MCP spec is at modelcontextprotocol.io. The starter stack above takes about ten minutes to wire up if you already have the tokens, and roughly twenty if you do not.

That is twenty minutes you spend once. The agent gets sharper every day after.