Setting Up MCP in Windsurf: Complete Configuration Guide

What is Windsurf?

Windsurf is an AI-native IDE built by Codeium, featuring their Cascade agent for agentic coding workflows. Unlike traditional AI assistants that only respond to prompts, Cascade can autonomously plan and execute multi-step coding tasks.

With MCP integration, Cascade can access external tools, databases, APIs, and services—making it significantly more capable for real-world development tasks.

MCP in Windsurf Overview

Windsurf's MCP implementation uses the same configuration format as Claude Desktop, making it easy to migrate existing configurations. Key characteristics:

• ●Configuration file: ~/.codeium/windsurf/mcp_config.json
• ●Format: JSON (same schema as Claude Desktop)
• ●Tool limit: 100 tools maximum across all servers
• ●Agent: Cascade automatically uses relevant tools

Installing via Plugin Store

The easiest way to add MCP servers is through Windsurf's Plugin Store:

1. Open Windsurf and click the Cascade panel
2. Click the hammer icon (tools) at the top
3. Select “Configure MCP”
4. Browse the Plugin Store for available servers
5. Click “Install” on your desired server
6. Fill in any required configuration (API keys, paths)
7. Click “Save” and the server will start automatically

Popular Servers in Plugin Store

Manual Configuration

For custom servers or advanced configuration, edit the config file directly:

Configuration File Location

# macOS / Linux# Windows# Windows# Windows# Windows# Windowsws
%USERPROFILE%\.codeium\windsurf\mcp_config.json

Basic Configuration Structure

{
  "mcpServers": {
    "server-name": {
      "command": "executable",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR": "value"
      }
    }
  }
}

Transport Types

Windsurf supports two transport methods for MCP servers:

Configuration Fields

Configuration Examples

Filesystem Server

Allow Cascade to read and write files in specific directories:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/projects",
        "/Users/username/documents"
      ]
    }
  }
}

GitHub Integration

Enable Cascade to work with GitHub repositories:

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

PostgreSQL Database

Connect Cascade to your PostgreSQL database:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://user:pass@localhost:5432/mydb"
      }
    }
  }
}

Multiple Servers

Combine multiple MCP servers in a single configuration:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"
      }
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your_brave_api_key"
      }
    }
  }
}

Using MCP Tools in Cascade

Once configured, MCP tools become available to Cascade automatically:

Viewing Available Tools

1. Open the Cascade panel
2. Click the hammer icon (tools)
3. View all connected servers and their status
4. Expand each server to see available tools

Tool Approval

By default, Cascade asks for approval before executing MCP tools. You can:

• ●Approve once: Allow the tool for this specific call
• ●Approve for session: Allow all uses during current session
• ●Deny: Prevent the tool from running

Enterprise Configuration

For enterprise deployments, Windsurf provides admin controls for MCP server management:

Admin Whitelisting

Enterprise administrators can configure approved MCP servers centrally:

• ●Whitelist mode: Only allow approved MCP servers
• ●Pre-configured servers: Push server configurations to all team members
• ●Credential management: Inject API keys and tokens centrally

Limitations

Be aware of these current limitations when using MCP with Windsurf:

Troubleshooting

References & Further Reading