MCP Servers for Windsurf — Complete Setup Guide (2026)

Last updated April 2026. Tested on Windsurf (latest) on macOS 15 and Windows 11.

---

What MCP servers do in Windsurf

MCP servers extend Windsurf's Cascade AI agent with external capabilities. Without them, Cascade can only work with your project files. With MCP servers, Cascade can search the web, read documentation, query databases, manage infrastructure, and interact with any service the server exposes.

Windsurf acts as the MCP host, and Cascade (the AI assistant) acts as the MCP client. When you configure servers, Cascade automatically discovers their tools and uses them based on your prompts.

---

Method 1: One-command install (recommended)

The fastest way to add an MCP server to Windsurf:

bashCOPY
# Install the AgenticMarket CLI (once)
npm install -g agenticmarket

# Authenticate (once)
agenticmarket auth am_live_your_key

# Install any server — Windsurf gets configured automatically
agenticmarket install agenticmarket/web-reader

The CLI detects Windsurf, writes the correct config to mcp_config.json, and the server becomes available to Cascade after a refresh.

---

Method 2: Managed plugins (GUI)

Windsurf provides a built-in plugin manager for popular MCP servers:

1. Click the Windsurf - Settings button (bottom right corner of the IDE)
2. Navigate to Cascade → Plugins (MCP servers)
3. Click Manage Plugins
4. Browse the available servers, select one, and click Install
5. If the server requires API keys, you'll be prompted to enter them

This method is the simplest for well-known servers. For custom or third-party servers not in the managed list, use the manual method below.

---

Method 3: Manual JSON setup

For custom servers, edit the mcp_config.json file directly:

Accessing the config

1. Go to Plugins (MCP servers) section in Windsurf Settings
2. Click Manage Plugins → View raw config
3. This opens mcp_config.json in the editor

Remote HTTP server

jsonCOPY
{
  "mcpServers": {
    "web-reader": {
      "url": "https://your-server-url/mcp"
    }
  }
}

Local stdio server

jsonCOPY
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./data"]
    }
  }
}

With environment variables

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

Note: Windsurf uses mcpServers as the root key — the same as Cursor and Claude Desktop. If you're coming from VS Code (which uses servers), make sure to change the key name.

After saving the config, click the Refresh button in the Manage Plugins tab, or use the Command Palette (Cmd/Ctrl+Shift+P) and select Reload Window.

---

Verifying the server is active

1. Open the Cascade AI chat panel
2. Look for the hammer icon (🔨) — this indicates MCP tools are available
3. Click the hammer icon to see a list of all available tools from your configured servers
4. Test with a prompt: "Use the [tool-name] tool to [specific action]"

If you don't see the hammer icon, the server didn't connect. Check the troubleshooting section below.

---

Recommended MCP servers for Windsurf

Browse all available servers at agenticmarket.dev/servers or explore community servers at agenticmarket.dev/explore.

---

Troubleshooting Windsurf MCP issues

Server doesn't appear after adding config

1. Click Refresh in the Manage Plugins panel
2. If that doesn't work, use Command Palette → Reload Window
3. Verify the root key is mcpServers (not servers)
4. Validate JSON syntax — paste into jsonlint.com

Tools are missing but server is connected

• Check the Cascade chat panel for the hammer icon (🔨)
• The server may be taking too long to respond to the tools/list request — see our guide on MCP servers not showing tools
• Try running the server command directly in your terminal to check for startup errors

Server fails to start (stdio)

• Use absolute paths for command — Windsurf may not inherit your shell's PATH
• Run which npx or which node in your terminal and use the full path
• Always include -y in npx args: ["-y", "package-name"]

Check logs for errors

• Open Help → Toggle Developer Tools → Console tab
• Look for MCP-related error messages

Still stuck? See our complete MCP troubleshooting guide for every error code and fix, or validate your endpoint in the MCP Playground.

---

Next steps

• MCP Servers for VS Code — Setup Guide — if you also use VS Code
• MCP Servers for Cursor — Setup Guide — for Cursor users
• MCP Servers for Claude Desktop — Setup Guide — for Claude Desktop users
• What is MCP? — understand the protocol from the ground up
• How to Install MCP Servers Without JSON — full multi-IDE guide
• MCP Server Not Working? — troubleshooting every error

---

This guide is updated when Windsurf changes its MCP handling. Last reviewed April 2026.