Best MCP Servers for Windsurf (2026)

What is Windsurf?

Windsurf is Codeium's AI-native IDE designed from the ground up for AI-assisted development. It features deep code understanding, intelligent autocomplete, and a powerful AI assistant called Cascade that can perform complex multi-step coding tasks. Windsurf supports the Model Context Protocol (MCP), allowing you to extend Cascade's capabilities with external tools, file system access, database connections, GitHub integration, and custom tooling.

How MCP Works with Windsurf

Windsurf reads MCP server configurations from a global configuration file at ~/.windsurf/mcp.json. When Windsurf starts, it launches the configured servers and makes their tools available to Cascade, the AI assistant. Cascade can then use these tools to fetch data, interact with APIs, query databases, and perform file operations beyond what Windsurf provides natively.

The global configuration approach means your MCP servers are available across all projects - you configure them once and they work everywhere. This is different from project-level approaches used by Cursor or VS Code, but convenient if you use the same set of tools across projects.

Detailed Setup Process

1. Install Windsurf from codeium.com/windsurf. It is available on macOS, Windows, and Linux.
2. Create the config directory if it does not exist: mkdir -p ~/.windsurf
3. Create ~/.windsurf/mcp.json with your MCP server definitions. The file uses an mcpServers object where each key is a server name.
4. Restart Windsurf to pick up the new configuration. Windsurf reads the config file at startup.
5. Open the Cascade panel (the AI assistant) and check for MCP tool availability. Connected servers will show their tools in the tool selector.
6. Start using Cascade with your MCP servers - ask questions or give instructions that require external data, and Cascade will use the appropriate tools.

Advanced Configuration

Global Configuration Model

Windsurf uses a single global configuration at ~/.windsurf/mcp.json. All configured servers are available in every project you open. If you need project-specific setups, you can use wrapper scripts or conditionally configure servers based on environment variables. Check the latest Windsurf documentation for updates on project-level MCP configuration support, as this feature may be added in future releases.

Environment Variables

Pass API keys and tokens through the env field in each server configuration. For security, store secrets in your system environment or a secrets manager rather than hardcoding them in the config file. The env values are passed only to the specific server process.

Transport Options

Windsurf supports stdio transport (the default) using command and args. For remote servers, SSE transport may be available - check the current Windsurf documentation for the latest transport support. Stdio is recommended for local servers due to lower latency and simpler configuration.

Cascade Integration

Cascade is Windsurf's AI assistant that handles multi-step coding workflows. When MCP servers are configured, Cascade can use their tools as part of complex operations. For example, it might query a PostgreSQL database to understand your schema, then generate code that matches the database structure, then use the GitHub server to create a pull request with the changes - all in a single workflow.

Troubleshooting Common Issues

• "No MCP servers detected" - Verify that ~/.windsurf/mcp.json exists and contains valid JSON. Common mistake: placing the file in a project directory instead of the home directory. Use cat ~/.windsurf/mcp.json in a terminal to verify.
• "Server failed to start" - The command specified in your config is not found or not in PATH. Verify the command works by running it directly in a terminal. For npx-based servers, ensure Node.js and npm are installed and accessible.
• "Connection refused" or "Server disconnected" - The server process started but crashed. Run the server command directly in a terminal to see error output. Common causes: missing dependencies, incorrect package versions, or required environment variables not set.
• Config changes not taking effect - Windsurf reads the config at startup. After editing ~/.windsurf/mcp.json, you must fully restart Windsurf (quit and reopen, not just reload).
• Tools showing but not working - The server is connected but individual tool calls are failing. This often means the server needs additional setup, such as database credentials being incorrect or file paths not existing.

Recommended MCP Servers

These MCP servers work well with Windsurf's AI-assisted development workflow:

• Filesystem Server - Extended file operations, useful for working with files outside the currently opened workspace.
• GitHub Server - Browse repos, manage issues and pull requests, and perform code reviews from within Cascade.
• PostgreSQL Server - Query databases with natural language, explore schemas, and generate SQL directly from the AI assistant.
• Brave Search Server - Web search for documentation, examples, and research without leaving the IDE.
• Memory Server - Persistent memory that lets Cascade remember project context, coding decisions, and preferences across sessions.

Explore all available servers in our MCP server directory.

Related Guides

For a comparison of MCP setup across different editors, read our MCP Servers for Cursor, VS Code, and Claude guide. Our tutorials section has step-by-step walkthroughs for common setups.

Performance Tips

• Limit your server count. Since Windsurf loads all configured servers globally, every server runs in every project. Remove servers you rarely use to keep resource consumption low.
• Pre-install server packages globally with npm install -g to avoid the download step that npx -y triggers on each startup. This significantly speeds up Windsurf's startup time.
• Use lightweight servers. Some MCP servers are more resource-intensive than others. Database servers that maintain connections consume more memory than simple utility servers.
• Monitor Windsurf's process list. Use your system's task manager or ps aux | grep mcp to see running MCP server processes and their resource usage.
• Restart Windsurf periodically if you notice slowdowns. Long-running MCP server processes can sometimes accumulate memory usage over time.

Security Considerations

MCP servers in Windsurf run as local processes with your user permissions. Since the configuration is global, all servers have access regardless of which project you have open. Follow these best practices:

• Minimize server scope. Configure filesystem servers to access only specific directories. Avoid giving servers access to your entire home directory.
• Protect your config file. ~/.windsurf/mcp.json may contain API keys and tokens. Ensure appropriate file permissions (chmod 600 ~/.windsurf/mcp.json) and consider using environment variables instead of hardcoded secrets.
• Audit servers regularly. Since all configured servers run in every project, a compromised server has access whenever Windsurf is running. Only use servers from trusted sources and keep them updated.
• Review Cascade's tool usage. Windsurf shows which MCP tools Cascade wants to use. Review these requests, especially for tools that can modify data or make network requests.
• For comprehensive security guidance, read our MCP Server Security Guide.

Comparing Windsurf with Other Clients

Windsurf excels with its Cascade AI assistant that handles complex multi-step workflows. If you prefer a VS Code-based experience, try Cursor or VS Code with GitHub Copilot. For terminal-based development, Claude Code CLI offers a powerful command-line alternative. For a standalone AI chat, Claude Desktop provides a clean interface. All these clients support the same MCP server ecosystem.