Blog Guides Alternatives Compare
Back to Blog
AI

How to Add an MCP Server to Windsurf (2026 Guide)

View as Markdown Open in ChatGPT Open in Claude
DesignRevision Editorial DesignRevision Editorial · SaaS, frontend & developer tooling
• 6 min read
Human Written
Share:

To add an MCP server to Windsurf, add it to the ~/.codeium/windsurf/mcp_config.json file — or use the built-in UI at Cascade → Manage MCPs → Add Server — and then click Refresh. That gives Windsurf's Cascade agent a new set of tools it can call during a task. Remote servers use a serverUrl, local ones use a command, and this guide covers both, the exact config for a server that needs an auth token, and how to fix the connection when it fails.

Last updated: July 2026. Note: Windsurf (formerly Codeium) is now part of Cognition, and its documentation has moved — docs.windsurf.com redirects to docs.devin.ai. The editor and its MCP support are unchanged; everything here was verified against the current docs in July 2026.

An MCP server exposes tools that Cascade can call. Windsurf configures them in JSON, like Cursor, but with its own quirks — most notably the serverUrl key for remote servers. (Using Claude Code or Codex instead? See our guides for Claude Code and Codex.)

The Ways to Add an MCP Server to Windsurf

There are three routes, and they all end up in the same mcp_config.json:

  1. The plugin store / marketplace — click the hammer icon (🔨) at the top of the Cascade panel to browse and one-click-install popular servers.
  2. The Manage MCPs UI — Windsurf Settings → Cascade → Manage MCPs → + Add Server, with a "View raw config" button that opens the JSON.
  3. Editing mcp_config.json directly — the source of truth, and the only way to set custom headers and secrets precisely.

Whichever you use, click the Refresh button (🔄) in Manage MCPs afterward — Windsurf does not reload servers automatically, and forgetting this is the single most common "why isn't it working?" moment.

Add a Remote MCP Server (with an Auth Token)

Most hosted servers are remote. In Windsurf, the key for a remote endpoint is serverUrl — not url, which trips up people coming from Cursor. If the server needs authentication, add a headers block. Here's a real example adding DesignRevision MCP, a server that installs shadcn/ui components into your project:

{
  "mcpServers": {
    "design-revision": {
      "serverUrl": "https://mcp.designrevision.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:DESIGNREVISION_TOKEN}"
      }
    }
  }
}

Windsurf supports ${env:VAR_NAME} interpolation in every field, so you can keep the token in an environment variable instead of hard-coding it — set DESIGNREVISION_TOKEN in your shell and Windsurf reads it at launch. Two accuracy notes worth their own callout: use serverUrl for remote servers (Windsurf infers the transport from it — no type field needed), and include the literal Bearer prefix in the header. A known Windsurf bug can leave the Authorization header off tool calls and return 401s; the Bearer prefix, and on older builds the mcp-remote fallback below, are the fixes.

After saving, click Refresh and check the status dot in Manage MCPs.

Add a Local MCP Server (stdio)

Local servers run as a subprocess. Use command, args, and an optional env block for secrets:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${env:GITHUB_PAT}"
      }
    }
  }
}

command can be npx, uvx, python, node, or docker. On Windows, npx-based servers sometimes need to be wrapped as "command": "cmd", "args": ["/c", "npx", ...] to launch.

Older Windsurf builds and OAuth servers may not send a custom header correctly. In that case, bridge the remote server through mcp-remote as a local process:

{
  "mcpServers": {
    "design-revision": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.designrevision.com/mcp",
               "--header", "Authorization: Bearer ${env:DESIGNREVISION_TOKEN}"]
    }
  }
}

Use the native serverUrl form first; reach for this only if the header won't stick.

Verify and Manage: Status Dots and the 100-Tool Limit

Open Manage MCPs and check each server's status dot — green means connected with its tools loaded, red means it failed (see troubleshooting). Each server also shows a tool count, which matters because of Windsurf's two hard limits:

  • 100 total tools across all active servers at once. Enable a handful of busy servers and you'll blow past it, at which point tools silently drop.
  • ~20 tool calls per prompt.

If you're near the cap, toggle off individual tools or whole servers you aren't using — a focused set beats a crowded one.

Troubleshooting: When a Windsurf MCP Server Won't Connect

  • You didn't click Refresh. Edited the file but nothing changed? Hit the 🔄 button in Manage MCPs (or restart Windsurf).
  • Invalid JSON. A trailing comma or missing brace breaks the file — and a broken mcp_config.json can crash Cascade. Validate it before saving.
  • 401 / auth header not sent. For remote servers, confirm the Authorization header includes the literal Bearer prefix and the token env var is set. If it still fails, switch to the mcp-remote bridge above.
  • npx not found. The command isn't on your PATH; on Windows wrap it in cmd /c.
  • Over the 100-tool limit. Disable unused tools or servers.
  • Old doc links 404. docs.windsurf.com now redirects to docs.devin.ai — use the current path if you're following an older tutorial.

Which MCP Servers Should You Add to Windsurf?

Adding a server is easy; a focused set is what makes Cascade genuinely useful — especially under the 100-tool ceiling. GitHub, Playwright, Context7, and a database server cover most workflows, and DesignRevision MCP adds the one thing the others don't: installing real shadcn/ui components on request. The same servers work across agents; we break down the most useful ones, with a verdict each, in our roundup of the best MCP servers for Claude Code — they apply to Windsurf too, only the config format differs.

Conclusion

Adding an MCP server to Windsurf comes down to one file — ~/.codeium/windsurf/mcp_config.json — reached through the plugin store, the Manage MCPs UI, or your editor. Remote servers take a serverUrl plus headers; local ones take a command. Keep tokens in environment variables, click Refresh after every edit, watch the 100-tool limit, and check the status dot. Start with one server that fills a real gap and grow from there.

Related Resources

Frequently Asked Questions

Yes. Windsurf's Cascade agent is a full MCP client and supports local servers (stdio) plus remote servers over Streamable HTTP and SSE. You add them in ~/.codeium/windsurf/mcp_config.json or through Cascade → Manage MCPs, then click Refresh so Cascade loads the tools.

At ~/.codeium/windsurf/mcp_config.json on macOS and Linux, or %USERPROFILE%\.codeium\windsurf\mcp_config.json on Windows. You can open it from Cascade → Manage MCPs → "View raw config." The top-level key is mcpServers, the same shape Claude Desktop uses.

Give the server a serverUrl (not url) and, if it needs auth, a headers block: {"mcpServers": {"name": {"serverUrl": "https://…/mcp", "headers": {"Authorization": "Bearer YOUR_TOKEN"}}}}. Windsurf detects the remote transport from serverUrl. Save the file and click Refresh in Manage MCPs.

Add each one as its own entry under mcpServers in mcp_config.json. There's no limit on how many servers you configure, but Windsurf enforces a hard limit of 100 total tools across all active servers (and about 20 tool calls per prompt), so disable tools or servers you aren't using to stay under it.

Check the status dot in Manage MCPs — red means it failed. Common causes: invalid JSON (validate it; a broken file can crash Cascade), you forgot to click Refresh after editing, the auth header isn't being sent (a known bug — include the literal "Bearer " prefix), the npx command isn't on your PATH (Windows may need cmd /c), or you've exceeded the 100-tool limit.

Windsurf (formerly Codeium) was acquired by Cognition, the company behind Devin, in mid-2025. The editor still exists and its Cascade agent still supports MCP — but the docs moved: docs.windsurf.com now redirects to docs.devin.ai. The config path (~/.codeium/windsurf/mcp_config.json) is unchanged.

Most are free and open source — GitHub, Playwright, Filesystem, and many others cost nothing to run. Some call a paid API (Firecrawl, Brave Search) with a free tier, and some are freemium: DesignRevision MCP is free to browse and install shadcn/ui components, with paid plans for more. MCP works on Windsurf's free tier, though heavy tool use draws on Cascade credits.

Start with a focused few — GitHub for repos, Playwright for browser testing, Context7 for up-to-date docs, and DesignRevision MCP for installing real shadcn/ui components. Because Windsurf caps you at 100 total tools, a small, deliberate set works better than enabling everything.

Join 50k+ subscribers

Web dev, SaaS, growth & marketing. Weekly.

Thanks for subscribing! Check your email.

No spam, unsubscribe anytime.

Back to all articles

Keep Learning

More articles you might find interesting.