How to connect MCP servers to Windsurf

Windsurf stores MCP configuration in a global file at ~/.codeium/windsurf/mcp_config.json. Unlike Cursor and VS Code, Windsurf does not support project-level MCP configuration — all servers are configured globally. If the file does not exist, create it along with the parent directories.

1# macOS/Linux — create the directory and file if they do not exist
2mkdir -p ~/.codeium/windsurf
3touch ~/.codeium/windsurf/mcp_config.json
4
5# Open in your default editor
6open ~/.codeium/windsurf/mcp_config.json

Add a mcpServers object (same key as Claude Desktop and Cursor). Each server entry has a unique name, a command to execute, args for command-line arguments, and optional env for environment variables. Start with one or two servers and verify they work before adding more.

1// ~/.codeium/windsurf/mcp_config.json
2{
3  "mcpServers": {
4    "filesystem": {
5      "command": "npx",
6      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/projects"]
7    },
8    "memory": {
9      "command": "npx",
10      "args": ["-y", "@modelcontextprotocol/server-memory"]
11    }
12  }
13}

Use the env field for API keys and secrets. This works identically to Claude Desktop and Cursor configurations. Be mindful of the 100-tool limit when adding servers that expose many tools (like the GitHub server which exposes 20+ tools).

1{
2  "mcpServers": {
3    "filesystem": {
4      "command": "npx",
5      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/projects"]
6    },
7    "brave-search": {
8      "command": "npx",
9      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
10      "env": {
11        "BRAVE_API_KEY": "your-brave-api-key"
12      }
13    },
14    "github": {
15      "command": "docker",
16      "args": ["run", "-i", "--rm",
17        "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
18        "ghcr.io/github/github-mcp-server"],
19      "env": {
20        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
21      }
22    }
23  }
24}

Windsurf enforces a hard limit of 100 tools across all connected MCP servers. If your servers collectively expose more than 100 tools, the excess tools are silently dropped. To work within this limit: check how many tools each server exposes (use MCP Inspector), prioritize the most useful servers, and consider building custom servers that expose only the tools you need instead of connecting large general-purpose servers.

1// Typical tool counts for popular MCP servers:
2// Filesystem: ~11 tools
3// GitHub: ~20+ tools
4// Brave Search: ~2 tools
5// Memory: ~5 tools
6// PostgreSQL: ~5 tools
7// Puppeteer: ~10 tools
8//
9// Total if all connected: ~53 tools — well within the 100 limit
10// Be careful adding many servers — it adds up fast

After saving mcp_config.json, fully restart Windsurf. Open Cascade (Windsurf's AI assistant) and check for available MCP tools. You can verify connections by asking Cascade to use a tool from one of your configured servers.

Open Cascade and ask a question that requires an MCP tool. For example, with the filesystem server connected, ask about files in your project directory. Cascade will use the MCP tools autonomously as part of its response, similar to how Claude Desktop and Cursor handle tool calls.