Windsurf (Cascade) MCP server not connecting, or its tools missing: the fixes

Start with Customize > MCPs

Devin Desktop lists what the agent loaded on its Customize page. Click Customize in the agent sidebar, choose MCPs, and set Install MCPs for to This computer. Each server has a toggle, a link to its config file and a refresh button. A server whose stored sign-in expired shows Needs auth: click Authenticate to clear the old credentials and sign in again.

For a support ticket, run Download Devin Logs File from the Command Palette, or choose Download Diagnostics from the three-dot menu in the Cascade panel. Devin CLI's own troubleshooting notes suggest asking the agent to list its MCP servers and tools, because a server can take a moment to start.

Which file the agent reads

• Devin Local uses the Devin CLI files. Since Devin CLI v3000.3 (the Local 3.6 release) your own servers live in ~/.config/devin/mcp_config.json (%APPDATA%\devin\mcp_config.json on Windows), project servers in .devin/mcp_config.json, and personal overrides in the gitignored .devin/mcp_config.local.json. Older versions kept them under mcpServers in config.json in the same folders, and newer versions move them over on startup.
• Cascade's Open MCP config file action opens the same ~/.config/devin/mcp_config.json, or $XDG_CONFIG_HOME/devin/mcp_config.json when that variable is set. The Windsurf plugin for JetBrains still runs Cascade and adds servers from Settings > Tools > Windsurf Settings > Add Server.
• Older Windsurf installs used ~/.codeium/windsurf/mcp_config.json (windsurf-next for Next builds). Devin CLI imports MCP servers from that file by default. If old servers vanished, check for "windsurf": false under read_config_from in ~/.config/devin/config.json, which turns the import off.
• Every one of these files uses an mcpServers key. A file copied from VS Code, whose mcp.json uses servers, won't load as written.

{
  "mcpServers": {
    "my-remote": {
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer ${env:MY_SERVICE_TOKEN}" }
    },
    "my-local": {
      "command": "npx",
      "args": ["-y", "some-mcp-server"],
      "env": { "API_KEY": "${env:API_KEY}" }
    }
  }
}

The server fails to start

• Run the server's command yourself in a terminal and check that every environment variable it needs is set. That is the first step in Devin CLI's own troubleshooting list.
• Pass credentials for stdio servers through env or args. In Cascade, OAuth works only for remote servers that use Streamable HTTP or SSE.
• For a remote server, Devin CLI tries Streamable HTTP first and falls back to SSE on the same URL after a 404 or 405. If the server's SSE endpoint is on another path, such as /sse, set "transport": "sse" with that URL.
• Devin Local and other ACP agents are unavailable while a workspace is open in Restricted Mode, so trust the workspace first.
• A server with "disabled": true is skipped and its tools never appear. devin mcp enable <name> turns it back on, and devin mcp list shows every configured server.

Connected, but no tools or a sign-in error

• Auth required or AuthRequired means the server wants OAuth. Click Authenticate on the server in Customize > MCPs, or run devin mcp login <name> in the CLI. Each client keeps its own sign-in, so signing in from Claude Code or an old Windsurf install doesn't carry over.
• If sign-in fails against a provider that rejects the RFC 8707 resource parameter, add "oauthResource": "" to the entry, then run devin mcp logout <name> and devin mcp login <name>.
• Devin Local asks before it calls any MCP tool. Allow the tool or the whole server, for the session or permanently, or add a rule such as mcp__github__* to permissions.allow.
• On a team plan, an admin can turn MCP off or keep an allowlist. Once a single server is allowlisted, every other server is blocked, and a configured server that isn't on the list won't connect.

Taskhold-specific checks

Taskhold is a remote server at https://taskhold.com/api/mcp. When the taskhold tools don't show up in Devin Desktop, check these in order:

1. The entry sits under mcpServers in ~/.config/devin/mcp_config.json with url set to https://taskhold.com/api/mcp. Use that exact address: the www one answers with a redirect. A fresh setup URL from Settings, pasted into the agent with "set this up", writes the entry for you.
2. The header is Authorization: Bearer followed by a key that starts with atd_sk_. Taskhold's 401 names the cause: missing_key, bad_header, not_a_taskhold_key or unknown_key. With ${env:TASKHOLD_API_KEY}, the variable has to be set where Devin Desktop starts.
3. Sign-in without a key (OAuth) is set up for Claude Code, Cursor, Codex, claude.ai and ChatGPT. In Devin Desktop, send the key in the header. With no header, the taskhold tools can still load, but every call comes back 401 missing_key.
4. A 402 means the key works but the trial ended or the plan was canceled. Restart the plan and the same config works again.
5. Settings in Taskhold shows Connected once the first call arrives. Ask the agent to call taskhold_list, and allow the taskhold server when Devin Local asks.

With the tools loaded and the workflow snippet from the Windsurf page in AGENTS.md, every task the agent starts, its steps and its questions show on the live board. The same checks for other clients: Cursor, VS Code Copilot and Gemini CLI.