Cascade MCP Integration

MCP (Model Context Protocol) is a protocol that enables LLMs to access custom tools and services. An MCP client (Cascade, in this case) can make requests to MCP servers to access tools that they provide. Cascade now natively integrates with MCP, allowing you to bring your own selection of MCP servers for Cascade to use. See the official MCP docs for more information.

Enterprise users must manually turn this on via settings

Adding a new MCP plugin

New MCP plugins can be added by going to the Settings > Tools > Windsurf Settings > Add Server section. To configure an MCP server manually, use Open MCP config file in Cascade’s MCP menu and edit the raw mcp_config.json file it opens. When you click on an MCP server, simply click + Add Server to expose the server and its tools to Cascade.

Cascade supports three transport types for MCP servers: stdio, Streamable HTTP, and SSE. Cascade also supports OAuth for remote servers that use the Streamable HTTP or SSE transport. OAuth is not available for stdio servers; pass their credentials through env or args instead. For http servers, the URL should reflect that of the endpoint and resemble https://<your-server-url>/mcp.

Make sure to press the refresh button after you add a new MCP plugin.

mcp_config.json

The mcp_config.json file contains a list of servers that Cascade can connect to. Cascade’s Open MCP config file action opens the Cortex-managed file in the Devin configuration directory:

macOS and Linux: ~/.config/devin/mcp_config.json, or $XDG_CONFIG_HOME/devin/mcp_config.json when XDG_CONFIG_HOME is set.
Windows: %AppData%/devin/mcp_config.json by default.

Use the file opened by the action for your installation, including builds with an isolated configuration directory.

The editor’s MCP discovery uses a separate, build-specific file: ~/.codeium/windsurf/mcp_config.json for stable or ~/.codeium/windsurf-next/mcp_config.json for Next. In editor Settings, search for chat.mcp.discovery.enabled and enable the windsurf source, labeled Devin configurations, to discover servers from that file.To open a discovered server’s file, run MCP: List Servers from the Command Palette, select the server, then choose Show Configuration. This discovery setting does not change the Cortex-managed file opened by Cascade’s Open MCP config file action.

Here’s an example configuration, which sets up a single server for GitHub:

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

Be sure to provide the required arguments and environment variables for the servers that you want to use. See the official MCP server reference repository or OpenTools for some example servers.

Remote HTTP MCPs

It’s important to note that for remote HTTP MCPs, the configuration is slightly different and requires a serverUrl or url field. Here’s an example configuration for an HTTP server:

{
  "mcpServers": {
    "remote-http-mcp": {
      "serverUrl": "<your-server-url>/mcp",
      "headers": {
        "API_KEY": "value"
      }
    }
  }
}

Config Interpolation

Cascade’s Cortex-managed mcp_config.json file (by default ~/.config/devin/mcp_config.json on macOS and Linux) handles interpolation of environment variables in these fields: command, args, env, serverUrl, url, and headers. Here’s an example configuration, which uses an AUTH_TOKEN environment variable in headers.

{
  "mcpServers": {
    "remote-http-mcp": {
      "serverUrl": "<your-server-url>/mcp",
      "headers": {
        "API_KEY": "Bearer ${env:AUTH_TOKEN}"
      }
    }
  }
}

Admin Controls (Teams & Enterprises)

Team admins can toggle MCP access for their team, as well as allowlist approved MCP servers for their team to use:

MCP Team Settings

Configurable MCP settings for your team.

The above link will only work if you have admin privileges for your team.

By default, users within a team will be able to configure their own MCP servers. However, once you allowlist even a single MCP server, all non-allowlisted servers will be blocked for your team.

How Server Matching Works

When you allowlist an MCP server, the system uses regex pattern matching with the following rules:

Full String Matching: All patterns are automatically anchored (wrapped with ^(?:pattern)$) to prevent partial matches
Command Field: Must match exactly or according to your regex pattern
Arguments Array: Each argument is matched individually against its corresponding pattern
Array Length: The number of arguments must match exactly between allowlist and user config
Special Characters: Characters like $, ., [, ], (, ) have special regex meaning and should be escaped with \ if you want literal matching

Configuration Options

Option 1: Plugin Store Default (Recommended)

Leave the Server Config (JSON) field empty to allow the default configuration from the Windsurf MCP Plugin Store.

Admin Allowlist Configuration:

Server ID: github-mcp-server
Server Config (JSON): (leave empty)

{}

Matching User Config (mcp_config.json):

{
  "mcpServers": {
    "github-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

This allows users to install the GitHub MCP server with any valid configuration, as long as the server ID matches the plugin store entry.

Option 2: Exact Match Configuration

Provide the exact configuration that users must use. Users must match this configuration exactly.

Admin Allowlist Configuration:

Server ID: github-mcp-server
Server Config (JSON):

{
  "command": "docker",
  "args": [
    "run",
    "-i",
    "--rm",
    "-e",
    "GITHUB_PERSONAL_ACCESS_TOKEN",
    "ghcr.io/github/github-mcp-server"
  ],
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": ""
  }
}

Matching User Config (mcp_config.json):

{
  "mcpServers": {
    "github-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Users must use this exact configuration - any deviation in command or args will be blocked. The env section can have different values.

Option 3: Flexible Regex Patterns

Use regex patterns to allow variations in user configurations while maintaining security controls.

Admin Allowlist Configuration:

Server ID: python-mcp-server
Server Config (JSON):

{
  "command": "python3",
  "args": ["/.*\\.py", "--port", "[0-9]+"]
}

Matching User Config (mcp_config.json):

{
  "mcpServers": {
    "python-mcp-server": {
      "command": "python3",
      "args": ["/home/user/my_server.py", "--port", "8080"],
      "env": {
        "PYTHONPATH": "/home/user/mcp"
      }
    }
  }
}

This example allows users flexibility while maintaining security:

The regex /.*\\.py matches any Python file path like /home/user/my_server.py
The regex [0-9]+ matches any numeric port like 8080 or 3000
Users can customize file paths and ports while admins ensure only Python scripts are executed

Common Regex Patterns

Pattern	Matches	Example
`.*`	Any string	`/home/user/script.py`
`[0-9]+`	Any number	`8080`, `3000`
`[a-zA-Z0-9_]+`	Alphanumeric + underscore	`api_key_123`
`\\$HOME`	Literal `$HOME`	`$HOME` (not expanded)
`\\.py`	Literal `.py`	`script.py`
`\\[cli\\]`	Literal `[cli]`	`mcp[cli]`

Notes

Admin Configuration Guidelines

Environment Variables: The env section is not regex-matched and can be configured freely by users
Disabled Tools: The disabledTools array is handled separately and not part of allowlist matching
Case Sensitivity: All matching is case-sensitive
Error Handling: Invalid regex patterns will be logged and result in access denial
Testing: Test your regex patterns carefully - overly restrictive patterns may block legitimate use cases

Troubleshooting

If users report that their MCP servers aren’t working after allowlisting:

Check Exact Matching: Ensure the allowlist pattern exactly matches the user’s configuration
Verify Regex Escaping: Special characters may need escaping (e.g., \. for literal dots)
Review Logs: Invalid regex patterns are logged with warnings
Test Patterns: Use a regex tester to verify your patterns work as expected

Remember: Once you allowlist any server, all other servers are automatically blocked for your team members.

General Information

Since MCP tool calls can invoke code written by arbitrary server implementers, we do not assume liability for MCP tool call failures. To reiterate:
We currently support an MCP server’s tools, resources, and prompts.

Devin Desktop

Agent Command Center

Releases

Windsurf Plugins

Accounts

Security

Windsurf Cascade MCP configuration

Adding a new MCP plugin

mcp_config.json

Remote HTTP MCPs

Config Interpolation

Admin Controls (Teams & Enterprises)

MCP Team Settings

How Server Matching Works

Configuration Options

Common Regex Patterns

Notes

Admin Configuration Guidelines

Troubleshooting

General Information

​Adding a new MCP plugin

​mcp_config.json

​Remote HTTP MCPs

​Config Interpolation

​Admin Controls (Teams & Enterprises)

MCP Team Settings

​How Server Matching Works

​Configuration Options

​Common Regex Patterns

​Notes

​Admin Configuration Guidelines

​Troubleshooting

​General Information

Adding a new MCP plugin

mcp_config.json

Remote HTTP MCPs

Config Interpolation

Admin Controls (Teams & Enterprises)

How Server Matching Works

Configuration Options

Common Regex Patterns

Notes

Admin Configuration Guidelines

Troubleshooting

General Information