How to add an MCP server to Windsurf

Windsurf keeps its MCP servers in a single config file and surfaces them in Cascade once you refresh.

Where Windsurf keeps its MCP config

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

Open the config

Windsurf stores MCP servers at ~/.codeium/windsurf/mcp_config.json. You can reach it from the Cascade panel: open the MCP servers view and choose Configure, which opens the same file.

Add the server

The format matches Claude Desktop and Cursor, under the mcpServers key, so config from those guides works here unchanged.

mcp_config.json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/projects"]
    }
  }
}

Refresh Cascade

Open the MCP servers panel in Cascade and hit refresh. Windsurf re-reads the config and reconnects without a full restart, and the new server's tools appear under the hammer icon.

If the server does not appear

Check the JSON parses. A trailing comma is the single most common cause of a server that silently never appears — the client cannot read the file, so it falls back to no servers rather than reporting an error.

Use an absolute path to the command. Clients do not always launch with your shell's PATH, so `npx` may resolve interactively and fail on startup. `which npx` gives you the full path to paste in.

Check the server actually runs on its own. Paste the same command into a terminal: if it exits immediately, the problem is the server or its credentials, not the client config.

Frequently asked questions

Where is the Windsurf MCP config file?

At ~/.codeium/windsurf/mcp_config.json. The Configure button in the Cascade MCP servers panel opens the same file.

Do I need to restart Windsurf?

Usually not. Open the MCP servers panel in Cascade and press refresh — Windsurf re-reads the config and reconnects in place.