How to Set Up MCP Servers in Windsurf: Complete Guide

Windsurf by Codeium supports MCP servers through its Cascade AI assistant. The setup is straightforward JSON, but Windsurf has two quirks that trip up developers coming from Cursor or Claude Code: the config file lives at a non-obvious path, and remote servers use serverUrl instead of url.

TL;DR: Put your config at ~/.codeium/windsurf/mcp_config.json (not ~/.windsurf/). For remote servers, use serverUrl instead of url. Local stdio servers work identically to Cursor's format.

graph TD
    A[Create ~/.codeium/windsurf/mcp_config.json] --> B[Add server config]
    B --> C[Reload Windsurf]
    C --> D{Server connected?}
    D -->|Yes| E[Test with Cascade]
    D -->|No| F[Check serverUrl vs url]
    F --> G[Check JSON syntax]

Where Windsurf Stores Its MCP Config

macOS / Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json

Note: it is .codeium/windsurf/, not .windsurf/. The file is mcp_config.json, not mcp.json. Windsurf only supports global config -- no project-level MCP files.

mkdir -p ~/.codeium/windsurf
touch ~/.codeium/windsurf/mcp_config.json

The Config Format

Standard stdio servers use the same format as Cursor:

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    }
  }
}

The serverUrl Difference

This is the most common Windsurf config mistake. For remote HTTP/SSE servers:

Cursor (uses url):

{ "url": "https://mcp.example.com/sse" }

Windsurf (uses serverUrl):

{ "serverUrl": "https://mcp.example.com/sse" }

If you copy a remote server config from Cursor docs and use url, Windsurf silently ignores it -- no error message, no connection.

Example Server Configurations

GitHub MCP

GitHub MCP | npm | Tools: 20 | ~10,300 tokens

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

Needs a GitHub PAT with repo scope from github.com/settings/tokens. See the GitHub MCP guide for workflow details.

Supabase MCP

Supabase MCP | npm | Tools: 25 | ~12,875 tokens

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server-supabase@latest"],
      "env": {
        "SUPABASE_ACCESS_TOKEN": "sbp_your_token_here"
      }
    }
  }
}

Context7 MCP

Context7 MCP | npm | Tools: 2 | ~800 tokens

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    }
  }
}

No API key required.

Playwright MCP

Playwright MCP | npm | Tools: 20 | ~10,300 tokens

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"]
    }
  }
}

Multiple Servers Together

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    },
    "supabase": {
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server-supabase@latest"],
      "env": {
        "SUPABASE_ACCESS_TOKEN": "sbp_your_token_here"
      }
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"]
    }
  }
}

Step-by-Step Setup

1. Create the config file

mkdir -p ~/.codeium/windsurf
touch ~/.codeium/windsurf/mcp_config.json

2. Add your server configuration

Start with one server to verify the setup:

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    }
  }
}

3. Reload Windsurf

Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux) > "Reload Window"

4. Verify the connection

Open Cascade and check for MCP server status. Test it: "Look up the Next.js documentation for server components." If Cascade calls Context7 and returns results, the setup is working.

Troubleshooting

Server does not appear after config change

• Forgot to reload: MCP config is read at startup. Always reload after editing.
• JSON syntax error: Validate with python3 -c "import json; json.load(open('$HOME/.codeium/windsurf/mcp_config.json'))"

"Server failed to start"

• Verify Node.js is installed: node --version
• Check package name spelling
• Test manually: npx -y @upstash/context7-mcp@latest

Remote server not connecting

1. Verify you are using serverUrl, not url
2. Check the URL is correct and the server is running
3. Ensure auth headers are configured if required

Tools load but Cascade does not use them

• Cascade needs the right mode for tool calling -- standard chat may not invoke MCP tools
• Too many servers increases token overhead. See how to cut MCP token costs.

Migrating configs from Cursor

1. Copy the mcpServers object from .cursor/mcp.json
2. Paste into ~/.codeium/windsurf/mcp_config.json
3. Replace any "url" fields with "serverUrl" for remote servers
4. Local stdio servers work identically with no changes

For more solutions, see the MCP troubleshooting guide.

Best Servers to Start With

• Context7 MCP -- live documentation, no API key, two tools, minimal overhead
• GitHub MCP -- PR management, issue tracking, code search
• Supabase MCP (or your database server) -- eliminates the most common context switch in fullstack development

Add more as you identify gaps. Keep your active server count manageable so each one earns its token cost.

Managing Secrets

• Do not add ~/.codeium/windsurf/ to any version-controlled directory
• Replace real tokens with placeholders before sharing configs
• Rotate tokens periodically

The same servers work across Cursor, Claude Code, and Continue.dev -- only the config format and file path change. Browse pre-built stacks to find the right server combination for your workflow.