Setup guide

How to add an MCP server to Windsurf

Windsurf's Cascade agent reads `mcp_config.json`. Remote servers are keyed as `serverUrl` rather than `url` — the most common reason a copied Cursor config fails here.

Where the config lives

  • All platforms: ~/.codeium/windsurf/mcp_config.json

Servers go under the mcpServers key.

What Windsurf can run

  • Local servers (stdio)
  • Remote servers (HTTP)
  • Remote servers (SSE)

504 of the 508 servers in the catalog run natively in Windsurf.

Step by step

  1. Open Windsurf Settings → Cascade → MCP servers → View raw config.
  2. Add servers under `mcpServers`; use `serverUrl` for remote ones.
  3. Click refresh in the MCP panel.

Reloading: Use the refresh button in Cascade's MCP panel.

Example: the Filesystem server in Windsurf

The official reference server for file access. Replace the directory with the folder you want the assistant to see.

Edit ~/.codeium/windsurf/mcp_config.json

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

Troubleshooting

A remote server copied from Cursor's config doesn't connect
Rename `url` to `serverUrl` — Windsurf ignores `url`.
`npx` is not found, or the server exits immediately on Windows
Windows launches `npx` through cmd. Use `"command": "cmd"` with `"args": ["/c", "npx", "-y", "<package>"]`, and make sure Node.js 18+ is on the PATH of the user the client runs as.
`SyntaxError` or `Unsupported engine` when the server starts
Most MCP servers need Node.js 18 or newer (`node -v`). If you use nvm, the client may not see your shell's Node: point `command` at the absolute path of `npx`.
The server starts but every tool call fails with 401 or 403
Its API key is missing or wrong. Put it in the server's `env` block (or the header for remote servers) — never in a file you commit.

Official documentation: Windsurf MCP docs

Setting up several servers at once?

Tick them in the catalog and the setup builder merges them into one Windsurf config.

Open the setup builder for Windsurf

Best MCP servers for Windsurf

The highest health scores among servers that run natively in Windsurf.

See every server that runs in Windsurf →