Windsurf MCP server: how to add servers to Cascade

windsurf.com now redirects to devin.ai/desktop. Cascade is an MCP client, so the practical questions are where its config file lives and which limits apply.

Checked 3 October 2026 · from Devin Desktop's Cascade MCP page, the Devin CLI and Devin MCP docs, the Analytics API spec and requests to docs.windsurf.com/mcp

One of 91 guides to monitoring and developer tools. Each covers what an AI coding agent can get out of the tool through MCP, the protocol that lets the agent query the tool directly.

How Windsurf works with MCP

Windsurf is an AI code editor owned by Cognition, the company behind Devin. It now ships as Devin Desktop with two agents: the legacy Cascade agent and Devin Local, the default for new tabs.

The two agents configure MCP differently. Cascade has no marketplace or one-click install, so servers go into mcp_config.json by hand. Devin Local uses the Devin CLI config files and has the MCP Marketplace.

Cognition does publish MCP servers for other products. Devin MCP at mcp.devin.ai manages Devin sessions, playbooks, knowledge and schedules, and DeepWiki MCP serves repository documentation.

https://docs.windsurf.com/mcp is a documentation search server named "Windsurf Docs". It exposes search_windsurf_docs and a read-only docs filesystem tool, and it answered without credentials on 3 October 2026.

Every vendor here gets the same four checks: official, maintained, distributed and usable. Windsurf passes 0 of them.

Windsurf matters to an agent stack as the place servers are configured. Usage and credit questions go to the Analytics API, which only Enterprise plans can call.

What can an AI agent do with Windsurf?

How to configure Windsurf MCP for agents

1. 1

   Enterprise teams start with MCP off

   Windsurf's docs say Enterprise users must turn it on manually in settings.

2. 2

   The first allowlist entry blocks every other server

   Once an admin allowlists one server, all servers outside the allowlist are blocked for the team.

3. 3

   Allowlist IDs must equal config keys

   The Server ID is case-sensitive and has to match the key in each user's mcp_config.json.

4. 4

   Registries leave Cascade unchanged

   Custom MCP registries replace the Devin Local marketplace, so restrict Cascade with the allowlist instead.

Paste this into your agent’s instructions

When you answer inside Cascade, state:
- Which MCP server and tool produced the answer.
- That Cascade enables at most 100 tools at once, so a
  server may have tools switched off in this session.
If no enabled tool covers the question, say so.
Do not conclude that the data does not exist.

Do you need the MCP server at all?

To ask how Windsurf works, add the Windsurf Docs server at https://docs.windsurf.com/mcp. It answers from public documentation.

For usage and credits, call the Analytics API. GET /api/v2alpha/analytics/consumption returns credit or ACU consumption to a service key with Analytics Read permission.

For your code, pipelines and production systems, add each vendor's own server to Cascade. Windsurf's docs use GitHub's server as the worked example.

Configure Windsurf as the client. Pull Windsurf's own usage data from the Analytics API.

Windsurf integration setup

Cascade servers are added by editing mcp_config.json. Open it from the ... Actions menu in the Cascade panel, then the Open MCP config file icon in the MCPs section.

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

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

{"mcpServers":{"windsurf-docs":{
  "serverUrl":"https://docs.windsurf.com/mcp"}}}

Every other client

Each block below is the configuration for one client, with the file path and the key that client expects.

"env":{"API_KEY":"${file:~/.secrets/api_key.txt}"}

devin mcp add -s user github -- npx -y @modelcontextprotocol/server-github
devin mcp list

{"mcpServers":{"devin":{
  "serverUrl":"https://mcp.devin.ai/mcp",
  "headers":{"Authorization":"Bearer <API_KEY>",
             "X-Org-Id":"<YOUR_ORG_ID>"}}}}

Read-only access, permissions and security

• Cognition disclaims tool-call failures

  Its docs say MCP tool calls can run code from arbitrary server authors, so it does not assume liability for their failures.

• Cascade exposes more than tools

  It supports a server's tools, resources and prompts, so review all three before approving a server.

• The env block is never allowlist-matched

  Admin patterns cover the command and arguments, and users can set env values freely.

Troubleshooting

An allowlisted server is still blocked

Check the argument count. Patterns are anchored, each argument is matched on its own, and the number of arguments must match exactly.

An allowlist pattern blocks everyone

Invalid regex patterns are logged and result in access denial. Escape $, ., [, ], ( and ) when you mean them literally.

What the vendor documents

Cognition's documentation covers Cascade's MCP support from the client side. It also states plainly that "Cascade does not have an MCP Marketplace or one-click install. Those are only available for the Devin Local agent."

Should you connect an agent to Windsurf?

Only as a client. Windsurf's own data is not available over MCP as of 3 October 2026, so use the Analytics API for usage. Best for devin Desktop users who want Cascade to call their GitHub, database or observability servers.

Strongest fit

Only as a client. Windsurf's own data is not available over MCP as of 3 October 2026, so use the Analytics API for usage.

Main advantage

Cascade handles stdio, Streamable HTTP and SSE servers, with OAuth and secret interpolation.

Main weakness

Cascade has no marketplace, and its 100-tool ceiling limits how many servers stay useful together.

Operational risk

The first admin allowlist entry automatically blocks every other server for the team.

Frequently asked questions