Where Windsurf’s MCP config lives, what goes in it, the marketplace and raw-config paths, and how to fix the common failures — plus how to put a policy gate in front of every tool call.
QUICK ANSWERQuick answer: ~/.codeium/windsurf/mcp_config.json (the legacy Codeium directory survived the rebrand). Top-level key is mcpServers.
| Scope | Path | Notes |
|---|---|---|
| Global | ~/.codeium/windsurf/mcp_config.json | One global file for all projects. On Windows, ~ is %USERPROFILE%. |
Servers can also be managed without touching the file: the MCPs icon in the Cascade panel, or Windsurf Settings → Cascade → MCP Servers.
A top-level mcpServers object, one entry per server. Local servers declare a command; remote servers declare a serverUrl.
| Key | What it does |
|---|---|
command | Executable for a stdio server. Use an absolute path if PATH resolution fails. |
args | Array of arguments passed to the command. |
env | Environment variables for the server process. |
serverUrl | Endpoint for a remote server (streamable HTTP or SSE). Plain url is also accepted. |
headers | HTTP headers for remote servers — where auth tokens go. |
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${env:GITHUB_TOKEN}"
}
}
}
} REMOTE SERVER (HTTP):
{
"mcpServers": {
"my-http-server": {
"serverUrl": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer ${env:TOKEN}"
}
}
}
} Windsurf interpolates ${env:VAR} and ${file:/path/to/file} inside command, args, env, serverUrl and headers — keep raw secrets out of the file.
| Transport | Status | How to declare it |
|---|---|---|
| stdio | Supported | Declare command + args. |
| Streamable HTTP | Supported | Declare serverUrl ending in /mcp. Teams/Enterprise admins must enable remote transports. |
| SSE | Supported | Declare serverUrl pointing at the SSE endpoint. Same admin gating on Teams plans. |
Click the MCPs icon at the top of the Cascade panel and browse the marketplace — Windsurf writes the config for you.
For servers not in the marketplace, edit ~/.codeium/windsurf/mcp_config.json directly and add an entry under mcpServers.
Windsurf Settings → Cascade → MCP Servers manages the same list — enable, disable, and toggle individual tools per server.
Recheck the JSON in mcp_config.json — a syntax error drops the whole file silently — and confirm you edited ~/.codeium/windsurf/mcp_config.json rather than another client’s config. Then reopen the MCP settings page.
Cascade allows at most 100 active tools at a time. Toggle off unneeded tools per server in the MCP settings — or route through a gateway that exposes a curated subset.
HTTP and SSE transports are admin-gated for managed plans — an admin must enable remote MCP in the org settings.
Use ${env:VAR} or ${file:/path} interpolation instead of pasting tokens into the config.
GUI-launched apps don’t always inherit your shell PATH — use an absolute path for command.
A standard Postgres MCP wired into Windsurf. Every query hits the database directly, with no audit trail and no statement-level controls.
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"],
"env": {}
}
}
} Register the Postgres MCP in PolicyLayer, mint a grant, point Windsurf at the proxy URL. PolicyLayer evaluates every call against the grant’s policy before it reaches the database.
{
"mcpServers": {
"postgres": {
"serverUrl": "https://proxy.policylayer.com/mcp/<server-uuid>/",
"headers": {
"Authorization": "Bearer <grant-token>"
}
}
}
} The <server-uuid> appears on each server's detail page. The <grant-token> shows once at mint time. See the Quick start for the full setup walk-through — and if you operate under SOC 2, HIPAA, GDPR or similar, the compliance hub maps how gateway-mediated MCP traffic evidences each framework.
Allow list_tables. Allow queries, but deny any statement containing DROP, TRUNCATE or DELETE.
{
"version": "1",
"default": "deny",
"tools": {
"query": {
"deny_if": [
{
"conditions": [
{ "path": "args.sql", "op": "regex", "value": "(?i)(DROP|TRUNCATE|DELETE)\\s" }
]
}
]
},
"list_tables": {}
}
} See Writing policies for the policy format, operators, and quota shapes.
At ~/.codeium/windsurf/mcp_config.json — the directory kept its Codeium name after the rebrand. Servers can also be managed from the MCPs icon in the Cascade panel or Windsurf Settings → Cascade → MCP Servers.
Usually a config problem: a JSON syntax error drops the whole mcp_config.json silently, or the entry went into another client’s config file. On Teams and Enterprise plans, remote (HTTP/SSE) servers also stay hidden until an admin enables them.
Cascade caps active tools at 100 across all servers. Beyond that, toggle individual tools off on each server’s MCP settings page, or expose a smaller curated set through a gateway.
Yes — declare a serverUrl for streamable HTTP or SSE endpoints, with auth in headers. On Teams and Enterprise plans, remote transports are off until an admin enables them.
Use Windsurf’s interpolation: ${env:VAR} reads an environment variable and ${file:/path} reads a file at launch. Both work in env, headers, serverUrl, command and args.
Route your MCP traffic through PolicyLayer. Every tool call is checked against your policy before it runs: allow, deny, or require approval. Per-identity grants. Full audit log. Live in minutes.
Instant setup, no code required.
46,500+ MCP servers and 515,000+ tools scanned and risk-classified.