How to Set Up MCP Servers in Windsurf

Model Context Protocol (MCP) is an open standard that lets AI agents connect to external tools, data sources, and services through a unified interface. Instead of building custom integrations for every tool, MCP gives AI assistants like Windsurf's Cascade agent a single protocol for talking to databases, file storage, APIs, and more. Windsurf added MCP support to its Cascade agent in 2025, making it one of the first AI-native code editors to adopt the protocol alongside Cursor and VS Code with GitHub Copilot. The integration means Cascade can read from your database, manage files in cloud storage, pull GitHub issues, or interact with any MCP-compatible service, all without leaving your editor. For developers, this changes how you work with AI in your IDE. Instead of copying data between tools and pasting context into chat windows, you connect your tools once and let Cascade pull the context it needs on its own.

Windsurf stores its MCP configuration in a single JSON file. The location depends on your operating system:

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

This is different from Cursor (which uses ~/.cursor/mcp.json) and VS Code (which uses workspace-level .vscode/mcp.json files). If you're switching between editors, make sure you're editing the right config. The file might not exist yet if you haven't configured any MCP servers. You can create it manually or let Windsurf generate it when you add your first server through the settings UI. To open the config file from within Windsurf, click the MCPs icon in the top-right corner of the Cascade panel, then select Configure. This opens mcp_config.json directly in your editor.

Before adding servers, make sure MCP is enabled in your Windsurf installation:

1. Open Windsurf Settings by pressing Cmd + , (macOS) or Ctrl + , (Windows/Linux)
2. Go to Advanced Settings and find the Cascade section
3. Enable Model Context Protocol (MCP) by toggling it on
4. Restart Windsurf. Quit the application and reopen it so the MCP subsystem loads properly

On Windsurf Teams and Enterprise plans, your organization admin may need to whitelist specific MCP servers before you can use them. If MCP is enabled but servers aren't connecting, check with your admin. Getting started should be straightforward. A good platform lets you create an account, invite your team, and start uploading files within minutes, not days. Avoid tools that require complex server configuration or IT department involvement just to get running.

Give Your AI Agents Persistent Storage

Fast.io's MCP server gives Cascade access to cloud storage, document search, and branded sharing. Free for AI agents.

Try the Free Agent Tier

There are two ways to add MCP servers: through the built-in marketplace or by editing the config file directly.

Using the MCP Marketplace

1. Click the MCPs icon in the Cascade panel (top-right corner)
2. Browse available servers or search for a specific one
3. Click Install on the server you want
4. Fill in any required credentials or environment variables
5. Restart Windsurf to activate the server

Official servers show a blue checkmark, meaning they're built by the parent service company.

Editing mcp_config.json Directly

For servers not in the marketplace, or if you prefer manual control, edit the config file. Here's the basic structure:

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-name"],
      "env": {
        "API_KEY": "your-key-here"
      }
    }
  }
}

Each server gets a unique key (like "server-name") inside the mcpServers object. The command field specifies how to launch the server process, args passes arguments, and env sets environment variables. After saving the file, restart Windsurf for changes to take effect.

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

The [Fast.io MCP server](/storage-for-agents/) provides 14 tools covering file uploads, downloads, workspace management, AI-powered document queries, and branded sharing, with a free agent tier that includes 5,000 monthly credits.

Windsurf supports three ways to connect to MCP servers. Picking the right transport type depends on whether the server runs locally or on a remote host.

stdio (Standard I/O) is the most common option. Windsurf launches the server as a local process and communicates through standard input/output. Use this for servers installed via npm, Python packages, or local binaries. ```json { "mcpServers": { "local-server": { "command": "node", "args": ["./path/to/server.js"] } } }

**Streamable HTTP** connects to remote servers over HTTP. Use the `serverUrl` field instead of `command`:

```json
{
  "mcpServers": {
    "remote-server": {
      "serverUrl": "https://your-server.com/mcp",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}

SSE (Server-Sent Events) uses an event streaming connection. This works well for servers that push real-time updates. The config format is identical to HTTP but uses an SSE endpoint URL. All three transport types support OAuth authentication. For environment-specific values, use the interpolation syntax ${env:VARIABLE_NAME} in your config fields. This keeps secrets out of your config file:

{
  "env": {
    "API_KEY": "${env:MY_API_KEY}"
  }
}

Each MCP server exposes a set of tools that Cascade can use. A file storage server might expose tools for uploading, downloading, searching, and managing permissions. A database server might expose query, schema inspection, and table management tools. Cascade has a hard limit of 100 total tools across all connected MCP servers. If you connect several servers that each expose 20-30 tools, you can hit this ceiling quickly. To manage your tool budget:

1. Click the MCPs icon in the Cascade panel
2. Select a connected server
3. Toggle individual tools on or off

Disable tools you don't actively need. For example, if you're using a database server primarily for read queries, you can disable write-related tools to free up slots for other servers. If you're at the limit and need to add another server, audit your existing connections. Remove servers you haven't used recently, or disable their less-used tools.

When MCP servers don't connect or act up in Windsurf, start with these checks:

Server won't start:

• Verify that Node.js 18 or later is installed (node --version)
• Check that npx is available in your PATH
• Look at Windsurf logs for error messages from the server process
• Make sure you've restarted Windsurf after editing mcp_config.json

Tools not appearing in Cascade:

• Confirm MCP is enabled in Windsurf Settings (Cascade section)
• Check the MCPs icon for server status. A red indicator means the server failed to connect
• Verify your total tool count hasn't exceeded 100
• For enterprise users, confirm the server is on your organization's whitelist

Authentication failures:

• Double-check API keys and tokens in your config
• Use ${env:VARIABLE_NAME} syntax and verify the environment variable is set in your shell
• For OAuth servers, make sure the token hasn't expired

Windsurf vs. Cursor config confusion:

• Windsurf config: ~/.codeium/windsurf/mcp_config.json
• Cursor config: ~/.cursor/mcp.json
• VS Code config: .vscode/mcp.json (workspace-level)

These are completely separate files. Editing one won't affect the others.

If you've used MCP with Cursor or another editor, Windsurf has a few differences worth knowing:

Windsurf's per-tool toggling is useful here. Instead of enabling or disabling an entire server, you can pick exactly which tools Cascade has access to. This gives you more control over your 100-tool budget. The admin whitelist feature on Windsurf Teams and Enterprise plans lets organizations restrict which MCP servers their developers can install, using regex pattern matching against server IDs.