How to Set Up MCP Servers in Windsurf (Cascade)

A precise, verified walkthrough for connecting MCP servers to Windsurf’s Cascade AI — covering the config file path, JSON format, the Windows cmd /c wrapper, the Cascade panel refresh step, and how to confirm everything is working.

What Is Windsurf MCP Support?

Windsurf is an AI-powered code editor made by Codeium. Its AI agent, Cascade, gained native Model Context Protocol (MCP) support, allowing it to call external tools and data sources through MCP servers — the same protocol used by Claude Desktop, Cursor, and VS Code.

Cascade supports three MCP transport types: stdio (subprocess piped over stdin/stdout), Streamable HTTP, and SSE. For most local servers you will use stdio.

Step 1 — Locate (or Create) the Config File

Windsurf reads MCP configuration from a single JSON file. The file is not created automatically; if it does not exist, create it yourself.

On Windows, the path expands to something like:

Create the windsurf folder inside .codeium if it does not yet exist, then create an empty mcp_config.json file there.

Step 2 — Write the mcpServers JSON

The file must contain a top-level mcpServers object. Each key is a name you choose; the value describes how to start the server.

Minimal stdio example (macOS / Linux)

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

With environment variables

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_yourTokenHere"
      }
    }
  }
}

The command and args fields also support variable interpolation: ${env:VAR_NAME} is replaced with the value of the named environment variable, and ${file:/path/to/file} is replaced with the trimmed contents of a file. This lets you keep secrets out of the JSON file itself.

Step 3 — The Windows cmd /c Wrapper

On Windows, Windsurf spawns the command value as a subprocess directly. Commands like npx and node are often not found unless the subprocess shell resolves PATH properly. The standard fix is to route through cmd with the /c flag.

{
  "mcpServers": {
    "memory": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-memory"
      ]
    }
  }
}

The pattern is always: "command": "cmd", then "args": ["/c", <actual-command>, ...rest-of-args]. This applies whether the real command is npx, node, python, or any other executable that relies on the Windows PATH being inherited through a shell.

Step 4 — Refresh and Enable in Cascade

1. Save the config file. Write and save mcp_config.json. Valid JSON is required — a trailing comma or missing brace will prevent Windsurf from loading any server.
2. Open the Manage MCPs page. In Windsurf, go to File › Preferences › Windsurf Settings, then click Manage MCPs in the left sidebar (under the Cascade section). Alternatively, open the Command Palette with Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (macOS) and search for Open Windsurf Settings, then navigate to Cascade › Manage MCPs.
3. Click Refresh. On the Manage MCPs page, click the Refresh button next to your new server. Windsurf will attempt to spawn the process and fetch its tool list.
4. Toggle individual tools (optional). Click the MCPs icon in the top-right corner of the Cascade panel. Select a server to open its detail page, where you can enable or disable individual tools. Cascade has a hard limit of 100 total tools across all connected servers; use this to stay under the limit.

Step 5 — Verify the Connection

After refreshing, check the Cascade panel MCPs icon. A red indicator next to a server name means the process failed to start; re-check your JSON syntax and, on Windows, confirm the cmd /c wrapper is present.

When the server is connected, ask Cascade something that exercises a tool from it. For example, if you added a filesystem server you might type:

// In Cascade chat:
List the files in my project root using the filesystem MCP server.

Cascade will show which tool it is calling before it calls it. Seeing the tool name appear in the Cascade response confirms end-to-end connectivity.

Remote HTTP / SSE Servers

For servers that expose an HTTP endpoint instead of a local process, use the serverUrl field instead of command/args:

{
  "mcpServers": {
    "my-remote-server": {
      "serverUrl": "https://your-server.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MY_API_KEY}"
      }
    }
  }
}

Windsurf will auto-detect whether to use Streamable HTTP or SSE based on the server’s response. The headers and url/serverUrl fields support the same ${env:VAR} interpolation as the stdio fields.

Quick Troubleshooting Reference