topmcps
Browse MCPs
Tutorial5 min readMay 5, 2026

How to Install an MCP Server on Windsurf

Windsurf wires MCP servers into Cascade — its agent — through a single mcp_config.json. Add a server, click Refresh, and the tools appear inside Cascade's next turn. No window reloads, no full restarts.

Goal

Connect any MCP server to Windsurf Cascade

Time

~5 minutes

Prereq

Windsurf installed, Node.js for npx-based servers

Steps

1

Open the Cascade MCP panel

Inside Windsurf, click the hammer icon on the Cascade panel and choose Configure. This opens (or creates) ~/.codeium/windsurf/mcp_config.json in your default editor. You can also edit the file directly with any editor — both routes work and read the same file.

2

Add an mcpServers block

The JSON shape is identical to Claude Desktop and Cursor. Each entry under "mcpServers" needs a "command" and "args" field. Paste any install snippet from a top-mcps.com detail page and it works as-is.

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

Set tokens via env

Credentialed servers (GitHub, Supabase, Stripe) read tokens from the env block. Windsurf passes them to the server process at launch but does not echo them in the chat transcript. Avoid putting tokens directly in args — they show up in process listings.

"github": {
  "command": "npx",
  "args": ["@github/github-mcp-server"],
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
  }
}
4

Click Refresh in the Cascade MCP panel

Windsurf re-reads mcp_config.json without a full app restart. Click the Refresh button at the top of the MCP panel; connected servers show a green dot, with the tool list expanding when you click the server name. A red dot means the server failed — hover for the underlying error.

Cascade thrives on tool-rich MCPs

Cascade plans across many tool calls per turn. Pick MCPs with broad operation surfaces — Filesystem, GitHub, Puppeteer, a database server — so Cascade can chain them confidently. Single-tool MCPs work but rarely change Cascade's behaviour at the level you can feel.

Sample mcp_config.json

Three popular servers, no API keys needed. Drop into ~/.codeium/windsurf/mcp_config.json and click Refresh.

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/code"
      ]
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
    }
  }
}

When it does not work

Refresh did not pick up the change

A second click on Refresh forces a full re-spawn. If still stale, fully quit Windsurf and reopen — sometimes a wedged child process holds the old config. The Refresh button only kills servers Cascade still tracks.

Tools missing in agent runs

Cascade does not always pick up new MCP tools mid-conversation. End the current turn, start a new one, and Cascade reloads the available tool list. Confirm in the MCP panel that the server is green before assuming a bug.

Cascade does not call the MCP autonomously

Cascade is autonomous but selective — it only calls tools it thinks help the task. If your prompt does not invite tool use, the agent may skip the MCP entirely. Try a more explicit prompt or add the MCP's capability to your project memory so Cascade considers it earlier.

FAQ

Where is Windsurf's MCP config stored?

At ~/.codeium/windsurf/mcp_config.json. The Cascade hammer icon → Configure opens it directly. There is no project-scoped config file today — every Windsurf workspace shares the same MCP setup.

Do I need to restart Windsurf after editing mcp_config.json?

No. Click Refresh in the Cascade MCP panel and Windsurf re-reads the config. A full restart is only needed if a child process is wedged or a server refuses to disconnect.

Can I share my MCP config with teammates?

Yes, but manually. Windsurf does not auto-discover a project-level mcp_config.json. The simplest approach: commit a redacted template to dotfiles and ask each teammate to copy the relevant entries into their own ~/.codeium/windsurf/mcp_config.json.

Will my Claude Desktop config work in Windsurf unchanged?

Yes. The mcpServers JSON shape is identical. Copy the mcpServers block from claude_desktop_config.json into mcp_config.json and click Refresh — the servers connect immediately. Only the file path differs.

Next steps

One server is wired up. Now pick the rest of the stack — the six MCPs every Windsurf user should install.

Best MCPs for WindsurfDebug an MCP →