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

> Add an MCP server to Windsurf via mcp_config.json or Cascade's Manage MCPs — remote and local servers, auth headers, and the 100-tool limit.

Source: https://designrevision.com/blog/add-mcp-server-to-windsurf

---

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](/blog/add-mcp-server-to-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](/blog/add-mcp-server-to-claude-code) and [Codex](/blog/add-mcp-server-to-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](/mcp)**, a server that installs [shadcn/ui components](/components) into your project:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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](/blog/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

- [DesignRevision MCP — the shadcn/ui MCP server](/mcp)
- [How to Add an MCP Server to Claude Code (2026 Guide)](/blog/add-mcp-server-to-claude-code)
- [How to Add an MCP Server to Cursor (2026 Guide)](/blog/add-mcp-server-to-cursor)
- [How to Add an MCP Server to Codex CLI (2026 Guide)](/blog/add-mcp-server-to-codex)
- [Claude Desktop MCP Config: How to Add a Server (2026)](/blog/claude-desktop-mcp-config)
- [Best MCP Servers for Claude Code (2026): Tested & Ranked](/blog/best-mcp-servers-for-claude-code)
- [Browse the shadcn/ui component registry](/components)