Skip to main content

How to Connect MCP Servers to Windsurf

Short answer

Windsurf's Cascade agent reads its MCP servers from mcp_config.json. On macOS and Linux that file is ~/.config/devin/mcp_config.json, and on Windows it's %APPDATA%\devin\mcp_config.json. Add each server under mcpServers: use command and args for a server that runs on your computer, or serverUrl for a remote one. Then refresh the MCP list in the Cascade panel.

Tested withDevin Desktop (Windsurf) 3.10.67Checked 20 Oct 2026

By Tony LewisHow we test these guides

Windsurf is now Devin Desktop

Windsurf was renamed Devin Desktop in June 2026, and the editor's settings carried over. The vendor's current docs use the paths in this guide. If your install still uses the older ~/.codeium/windsurf/ folder, open the file from the Cascade menu in step 1 to find the one Cascade reads.

What you'll have at the end​

A bookmarks server in mcp_config.json that Cascade starts for you. Its tools appear in the MCPs list in the Cascade panel, so you can ask Cascade to save or search bookmarks.

mcp_config.json
{
  "mcpServers": {
    "bookmarks": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/bookmarks",
        "run",
        "bookmarks.py"
      ],
      "env": {
        "BOOKMARKS_FILE": "/ABSOLUTE/PATH/TO/bookmarks-data.json"
      }
    }
  }
}

The bookmarks server is the one from How to Build an MCP Server. Any local server works the same way.

Before you start

  • Windsurf installed. It's now called Devin Desktop, but the steps below use the Windsurf names.
  • An MCP server to connect. Either a server that runs on your computer, such as the one from How to Build an MCP Server, or the URL of a remote server.
  • For a local server, whatever runtime it needs on your machine, such as uv for Python or Node.js for TypeScript.

1. Find your config file​

Open the file from inside Windsurf rather than typing the path. Click the ... (Actions) menu in the top right of the Cascade panel, then click the Open MCP config file icon in the MCPs section. Windsurf opens mcp_config.json in the editor.

If you prefer to find it yourself, these are the paths:

OSConfig file
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

If the file doesn't exist yet, create it with {} as the content and add your servers inside it. New Devin Local tabs read different files, from the Devin CLI settings. This guide covers the Cascade agent.

2. Add a local (stdio) server​

A local server is a program that Windsurf starts on your computer. Windsurf talks to it over standard input and output, so you give it a command to run and any args to pass.

Replace the placeholder paths with absolute paths on your machine. command and args are the same command you'd type in a terminal, split into parts. env sets environment variables for the process only.

mcp_config.json
{
  "mcpServers": {
    "bookmarks": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/bookmarks",
        "run",
        "bookmarks.py"
      ],
      "env": {
        "BOOKMARKS_FILE": "/ABSOLUTE/PATH/TO/bookmarks-data.json"
      }
    }
  }
}

Use the full path to the command, such as the output of which uv on macOS or Linux, if the server starts in your terminal but not in Windsurf.

3. Add a remote server​

A remote server runs somewhere else and has a URL. Windsurf supports Streamable HTTP and SSE transports. Use the endpoint URL from the server's docs, which usually ends in /mcp, and put it in serverUrl.

mcp_config.json
{
  "mcpServers": {
    "example-remote": {
      "serverUrl": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:EXAMPLE_MCP_TOKEN}"
      }
    }
  }
}

This example sends a bearer token in a header. Keep the token out of the file with ${env:NAME}, which Windsurf replaces with the value of that environment variable when it starts the server. Windsurf also replaces variables in command, args, env, serverUrl, url and headers. You can also read a value from a file with ${file:~/path/to/file}.

If a variable isn't set, Windsurf replaces it with an empty string, and the header becomes just Bearer . The server then rejects the request, so check the variable name if you get a sign-in error.

Windsurf also accepts url in place of serverUrl, according to the current docs. This guide uses serverUrl throughout.

4. Sign in with OAuth​

If the remote server supports OAuth, leave out headers and let Windsurf handle sign-in. Windsurf supports OAuth for remote servers that use Streamable HTTP or SSE. It doesn't support OAuth for local (stdio) servers. Pass a local server's credentials through env or args instead.

Follow the sign-in prompt Windsurf shows you, then check the server in the next step.

5. Turn off tools you don't need​

Cascade can use up to 100 tools at a time across all its MCP servers. If your servers add up to more, the extra tools aren't loaded. To keep a tool out of Cascade, list its name under disabledTools in that server's entry.

mcp_config.json
{
  "mcpServers": {
    "bookmarks": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/bookmarks",
        "run",
        "bookmarks.py"
      ],
      "disabledTools": ["save_bookmark"]
    }
  }
}

You can also switch a whole server on or off with the toggle next to it in the MCPs section of the Cascade panel's ... menu. That list shows how many tools each server has enabled, which is the quickest way to see whether you're near the limit.

6. Reload and check the connection​

Save mcp_config.json. Then open the MCPs section of the Cascade panel's ... menu and press the refresh button. If your server doesn't appear, quit Windsurf completely and reopen it. Closing the window doesn't reload MCP servers.

To check it worked, look for your server in the MCPs list with its tool count. Then ask Cascade something that needs one of its tools, such as "Save https://modelcontextprotocol.io as MCP docs in my bookmarks." If Cascade says it has no such tool, the server didn't start. Go to Common problems below.

Common problems​

The server doesn't appear in the MCPs list. The most common cause is invalid JSON, such as a trailing comma or a missing brace. Check the file before you restart:

python3 -m json.tool ~/.config/devin/mcp_config.json

On Windows, run the same check on %APPDATA%\devin\mcp_config.json. A file that parses without an error is valid JSON, even if the server still fails to start.

A local server starts in your terminal but not in Windsurf. Windsurf may not have the same PATH as your terminal. Put the full path to uv, node or python in command, as described in step 2.

The remote server returns 401 or asks you to sign in again. Either the token is wrong, or the ${env:NAME} variable isn't set in the environment Windsurf starts from. An unset variable becomes an empty string. Set the variable and quit Windsurf completely before you reopen it.

Only some of your tools appear. You've passed the 100-tool limit. Turn off tools you don't use with disabledTools in step 5, or turn off whole servers.

Cascade stops partway through a task and asks you to continue. Cascade stops after a set number of tool calls per prompt. The current Devin Desktop docs give the default as 40, and older Windsurf pages say 20. Press Continue to resume. To stop seeing this, turn on Auto-Continue in Cascade's settings. In settings.json, the same setting is devin.autoContinue, and a value of 0 or below means it keeps going.

The server works for you but not for your team. On a Teams plan, an admin can allowlist approved servers. Once even one server is on the allowlist, every server that isn't on it is blocked for the team. Ask your admin to add the server.

To see a local server's own log output, open the Output panel and choose the MCP: channel for that server. Each server has its own channel, named MCP: followed by the server's name in your config.

FAQ​

Does Windsurf support MCP?

Yes. The Cascade agent connects to MCP servers over stdio, Streamable HTTP and SSE, and it supports OAuth for remote servers. Local servers are configured with a command and remote servers with a URL, both in mcp_config.json.

Is Windsurf now called something else?

Yes. Windsurf was renamed Devin Desktop in June 2026. The MCP settings and config paths in this guide come from the current Devin Desktop docs.

Why are some of my MCP tools missing in Windsurf?

Cascade can use up to 100 tools at a time across all its MCP servers. Tools past that limit aren't loaded. Turn off the tools you don't use with disabledTools in mcp_config.json.

Do I need to restart Windsurf after I change mcp_config.json?

Usually, press the refresh button in the MCPs section of the Cascade panel. If the server still doesn't appear, quit Windsurf completely and reopen it, because closing the window doesn't reload MCP servers.

Can Windsurf use a server that needs OAuth sign-in?

Yes, for remote servers that use Streamable HTTP or SSE. Leave out the headers block and follow the sign-in prompt. OAuth isn't available for local stdio servers, so pass their credentials through env instead.