Connect an MCP server to Windsurf

Windsurf's agent, Cascade, reads MCP servers from one JSON file — ~/.codeium/windsurf/mcp_config.json — with a plugin store and an MCPs panel that write to the same place. Remote servers take a URL, local servers a launch command; every brand page here tells you which.

Where the config lives

Three routes to the same file: the MCPs icon in the Cascade panel's top-right menu, the MCP servers section of Windsurf's settings, or the plugin store for one-click installs of popular servers. Hand-editing works too:

Local (stdio) servers

{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "@vendor/mcp-server"],
      "env": { "VENDOR_API_KEY": "${env:VENDOR_API_KEY}" }
    }
  }
}

Python servers use uvx as the command. The ${env:…} form reads the value from your environment at launch, so the secret never sits in the file — ${file:/path} does the same from a key file. After saving, refresh the server list from the MCPs panel.

Remote (hosted) servers

Windsurf's remote config uses serverUrl where most clients use url:

{
  "mcpServers": {
    "linear": {
      "serverUrl": "https://mcp.linear.app/mcp"
    }
  }
}

Streamable HTTP and SSE are both supported, and OAuth sign-in kicks in automatically for servers that require it — token-based servers take a headers object instead. Servers you can add this way right now: fal.ai, Atlassian, Datadog, Buffer, Google Drive, Confluence.

The 100-tool budget

Cascade has a hard limit of 100 tools visible at once, summed across every enabled server. Big servers spend that budget fast — GitHub's alone ships dozens. When you cross the line, tools silently drop out. Treat servers like dependencies: enable what the project needs, toggle the rest off in the MCPs panel.

When it doesn't work

A word on trust

An MCP server runs with the credentials you give it, and Cascade acts on whatever it returns. Prefer official servers where they exist, and give community ones scoped, revocable keys. More in our MCP security guide.

Questions