How to Add an MCP Server to Windsurf

Windsurf is Codeium's AI editor, and it loads MCP servers for its Cascade agent from a single global file: mcp_config.json. The file uses the standard mcpServers structure and lives in Windsurf's home configuration directory rather than inside your project, so one setup serves every workspace.

Config file location

Generate a Windsurf config

The tool below is pre-set to Windsurf. Fill in the server and copy the JSON — it never leaves your browser.

Files are read locally; nothing is uploaded.

Working example

A Windsurf config for the PostgreSQL server. Because the file is global, every workspace gets database tools once Cascade reloads.

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost/mydb"
      ]
    }
  }
}
~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-puppeteer"
      ]
    }
  }
}
Global mcp_config.json for Windsurf with a Puppeteer browser-automation server.

How to add the server, step by step

  1. Open Windsurf Settings and find the Cascade > MCP servers section.
  2. Click "View raw config" to open mcp_config.json directly.
  3. Paste the generated server into the existing mcpServers object - merge, do not replace.
  4. Save the file, then hit the refresh/reload button in the MCP panel.
  5. Ask Cascade to use one of the new tools to confirm the server is live.

Windsurf-specific pitfalls

Replacing instead of merging wipes your other servers

mcp_config.json is one shared file. Pasting a whole new {"mcpServers": {...}} document over it silently deletes every server you already had. Add your new server as an entry inside the existing mcpServers object - or validate the merged result before saving.

Cascade does not hot-reload

Editing mcp_config.json does not restart running servers. Use the refresh button in the MCP panel after every edit, and fully restart Windsurf when a server gets stuck in a failed state - the refresh alone sometimes reuses the dead process.

The raw config is hidden behind the UI

New users hunt for a file that the settings UI abstracts away. The direct path is %USERPROFILE%\.codeium\windsurf\mcp_config.json on Windows and ~/.codeium/windsurf/mcp_config.json on macOS and Linux; in the app, Settings > Cascade > MCP servers > "View raw config" opens the same file. There is no per-project Windsurf MCP file.

Too many servers slow Cascade down

Every configured server injects its tool list into Cascade's context. A dozen rarely used servers measurably degrade responses - keep the file lean and remove servers you are not actively using instead of accumulating them.

Related troubleshooting

Client compatibility matrix

Windsurf's serverUrl field next to the url and type tokens of the other clients.

spawn ENOENT / npx not found

When Cascade shows a server that never launches - reading the error target first.

FAQ

Where is Windsurf's MCP config file?

At %USERPROFILE%\.codeium\windsurf\mcp_config.json on Windows and ~/.codeium/windsurf/mcp_config.json on macOS and Linux. You can also open it from inside the app via Settings > Cascade > MCP servers > "View raw config".

Why is my new MCP server not working in Windsurf?

The most common cause is forgetting to reload Cascade after saving mcp_config.json - use the refresh button in the MCP panel. Second most common: the pasted JSON replaced the whole file and broke the remaining servers, so validate the merged file.

Does Windsurf support per-project MCP configs?

No. Windsurf reads a single global mcp_config.json, unlike Cursor or VS Code which support project-level files. All workspaces share the same server set.

Configuring other clients too? See the guides forClaude Desktop,Cursor,VS Code,Windsurf,Zed andCline, or readhow MCP transports differ.