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.

Transport
Advanced: environment variables

Config JSON

Where this file lives

    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 ~/.codeium/windsurf/mcp_config.json; 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.

    FAQ

    Where is Windsurf's MCP config file?

    At ~/.codeium/windsurf/mcp_config.json on every platform. 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.