Back

How to Add a Remote MCP Server to Windsurf

A practical guide to adding a remote MCP server to Windsurf: mcp_config.json location, serverUrl entries, bearer token, API key header, and OAuth authentication, disabledTools, team allowlists, and troubleshooting.

Kelis Shekhaliya

Existing SaaS API connected to AI agents through an MCP layer with documented tools, authentication, testing, and monitoring

TL;DR

To add a remote MCP server to Windsurf, open Cascade's <strong>Open MCP config file</strong> and add an entry under <code>mcpServers</code> with a <code>serverUrl</code>. Keep tokens in <code>headers</code> using <code>${env:NAME}</code>, sign in to OAuth servers when prompted, hide risky tools with <code>disabledTools</code>, then refresh and confirm with a read-only tool call.

To add a remote MCP server to Windsurf, open Cascade's MCP menu, choose Open MCP config file, and add an entry under mcpServers with a serverUrl (or url) that points at the server's MCP endpoint. If the server takes an API key or bearer token, put it in a headers object and read the value from an environment variable with ${env:NAME} instead of pasting the secret into the file. If the server uses OAuth, leave the headers out and complete the sign-in when Windsurf starts it. Save the file, press refresh in the MCP panel, and ask Cascade for a small read-only task that needs one of the server's tools.

This guide is for SaaS founders, CTOs, and API teams who run an MCP server, or are about to, and want developers to use it from Windsurf. It covers where Windsurf keeps its MCP configuration, the JSON for a remote server, each authentication option, how to hide tools Cascade should not call, team controls, and what to check when a server will not connect.


Why Windsurf matters for a SaaS MCP server

Windsurf's agent, Cascade, is an MCP client. Once your API is available as an MCP server, a developer working in Windsurf can ask Cascade to look up records, create test data, or check the state of an integration in your product without leaving the editor. Cascade supports an MCP server's tools, resources, and prompts, so the same server you built for other clients works here too.

Developers rarely use only one tool, so it helps to document every client your users ask about. If you also support other editors, see how to add a remote MCP server to Cursor.


Before you start

  • The server has a reachable URL. A remote server is added by its MCP endpoint, such as https://mcp.example.com/mcp, not by the product's homepage.

  • It speaks Streamable HTTP or SSE. Cascade supports three transports: stdio for servers that run as a local process, and Streamable HTTP and SSE for servers you reach at an address. A hosted server uses one of the last two, and Streamable HTTP is the current standard.

  • You know the authentication method. No authentication, a bearer token, another header such as an API key header, or OAuth. Each one changes the configuration.

  • MCP is allowed for your account. On Enterprise plans MCP has to be turned on in settings first, and team admins can restrict which servers members may use. More on that below.


Where Windsurf reads MCP configuration

Cascade reads its servers from a file called mcp_config.json. The safest way to find the right copy is to let Windsurf open it for you: in Cascade's MCP menu, choose Open MCP config file. Windsurf's current documentation lists these default locations for that 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.

Many older guides point to ~/.codeium/windsurf/mcp_config.json. According to Windsurf's documentation, that path is now a separate, build-specific file used by the editor's MCP discovery (~/.codeium/windsurf-next/mcp_config.json for the Next build), not the file Cascade's Open MCP config file action edits. If you edit a file and nothing changes in Cascade, check that you edited the one the action opens.

You can also add servers from the settings screen. Windsurf's documentation places this under Settings > Tools > Windsurf Settings > Add Server. Editing the JSON directly gives you full control over headers and environment variables, so the rest of this guide uses the file.


Add the server

The basic entry

Every server is a named entry inside mcpServers. A local server uses command and args. A remote server uses serverUrl or url instead:

{
  "mcpServers": {
    "acme": {
      "serverUrl": "https://mcp.example.com/mcp"
    }
  }
}

The key, acme here, is the name Cascade shows in its MCP list. Use something short and recognisable. If the file already has servers, add the new entry next to them inside the same mcpServers object rather than creating a second one.

Save and refresh

Windsurf does not always pick up a new entry on its own. After saving the file, press the refresh button in Cascade's MCP panel. The server should appear in the list with its tools. If it shows an error instead, jump to the troubleshooting section.


Set up authentication

Windsurf interpolates environment variables in the command, args, env, serverUrl, url, and headers fields using the ${env:NAME} syntax. Use that for every secret. A literal key in mcp_config.json is easy to leak through a screenshot, a synced dotfiles repository, or a shared project config.

Bearer token in the Authorization header

If the server expects Authorization: Bearer <token>, set the header and read the token from the environment:

{
  "mcpServers": {
    "acme": {
      "serverUrl": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:ACME_MCP_TOKEN}"
      }
    }
  }
}

Set ACME_MCP_TOKEN in the environment Windsurf runs in, then restart Windsurf so it sees the variable.

An API key in another header

Some APIs take a key in a custom header instead. Use the header name the server documents:

{
  "mcpServers": {
    "acme": {
      "serverUrl": "https://mcp.example.com/mcp",
      "headers": {
        "X-API-Key": "${env:ACME_API_KEY}"
      }
    }
  }
}

The header name must match exactly what the server checks. A request with the right key in the wrong header usually fails the same way as a request with no key at all.

OAuth

Cascade supports OAuth for remote servers that use Streamable HTTP or SSE. For an OAuth server, add the entry with only the serverUrl and no auth headers, refresh, and complete the sign-in flow in your browser when Windsurf starts it. OAuth is not available for stdio servers; those take credentials through env or args.

Which method to offer is a decision for the server owner, not the client. If you are still choosing, API keys, bearer tokens, and OAuth for MCP compares the trade-offs.


Control which tools Cascade can call

A server that exposes every endpoint of a large API can give Cascade more tools than it needs, including ones that change or delete data. Windsurf lets you switch individual tools off with a disabledTools array on the server entry:

{
  "mcpServers": {
    "acme": {
      "serverUrl": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:ACME_MCP_TOKEN}"
      },
      "disabledTools": ["delete_customer", "refund_payment"]
    }
  }
}

Disabled tools stay on the server but Cascade will not call them from this machine. This is a per-user safety net, not a security boundary: anything sensitive should also be protected by the permissions of the credential the server uses. The cleaner fix, if you own the server, is to expose a smaller, focused set of tools in the first place.


Team and Enterprise controls

On Teams and Enterprise plans, admins can turn MCP access on or off for the team and keep an allowlist of approved servers. By default, team members can configure their own servers. Once an admin allowlists even one server, every server that is not on the allowlist is blocked for the team. Matching is case-sensitive and uses anchored regular expressions, so a small difference between the allowlist entry and a user's config is enough to block a server.

If you sell to companies that use Windsurf, tell their admins exactly how your server should be configured so they can add an allowlist entry that matches what your setup docs tell users to paste.


Test the connection

  1. Confirm the server appears in Cascade's MCP list after a refresh, with no error and the tools you expect.

  2. Ask Cascade for a small, read-only task that clearly needs one tool, for example "list the five most recent projects in Acme". Check that it calls your tool and that the result matches what the API returns.

  3. Only then try a write action, on test data, and check what changed in the product.

If you are debugging the server itself rather than the client, test it outside Windsurf first. Testing an MCP server with MCP Inspector shows how to check the tool list, auth, and responses directly.


Troubleshooting

The server is not listed

Check that you edited the file opened by Open MCP config file, that the JSON is valid (a missing comma or brace stops the whole file from loading), and that you pressed refresh. If you are on an Enterprise plan, check that MCP is turned on for your account.

The server is blocked

If your team has an MCP allowlist, any server that does not match an allowlisted entry is blocked. Ask your admin to add it, or to correct an entry that almost matches.

Authentication fails

Check the header name and the token format, including the Bearer prefix if the server expects it. If you use ${env:NAME}, make sure the variable is set in the environment Windsurf was started from. An app launched from the dock or start menu may not see variables you only export in a shell profile, so restart Windsurf after setting them. For OAuth servers, sign in again. Also check the URL path: many servers serve MCP at /mcp, not at the root.

A remote URL in the wrong field

A remote server goes in serverUrl or url. Putting a URL in command makes Windsurf try to run it as a local program, which fails.

The server connects but its tools are not used

Cascade chooses tools from their names and descriptions. Check that the tools are not in disabledTools, then look at the tools themselves: clear names, precise descriptions, and a focused set make the right choice easier.


Adding a 0mcp server to Windsurf

If your MCP server is hosted on 0mcp, publish a server version and open its Setup page. 0mcp does not currently generate a Windsurf-specific block, but the Setup page shows the endpoint and the authentication headers and environment variables the server needs. Put the endpoint in serverUrl, add the headers using ${env:NAME} for each secret, set those variables, then restart Windsurf and confirm the server appears in the MCP list. The 0mcp Windsurf setup guide has the details.


Final checklist

  • The server URL is public and serves Streamable HTTP or SSE.

  • The server is an entry under mcpServers in the mcp_config.json that Open MCP config file opens, with serverUrl or url.

  • Secrets come from ${env:NAME} in headers, or from OAuth, never from literal values in the file.

  • Risky or unneeded tools are listed in disabledTools, and the credential itself has only the permissions it needs.

  • Team allowlists, if any, include the server.

  • After a refresh, the server shows in the MCP list and a read-only tool call returns real data.

FAQ

01How do I add a remote MCP server to Windsurf?+

In Cascade's MCP menu, choose <strong>Open MCP config file</strong> and add an entry under <code>mcpServers</code> with a <code>serverUrl</code> or <code>url</code> pointing at the server's MCP endpoint. Save the file, press refresh in the MCP panel, and test a read-only tool call.

02Where is the Windsurf MCP config file?+

Use the file that Cascade's <strong>Open MCP config file</strong> action opens. Windsurf's current documentation lists <code>~/.config/devin/mcp_config.json</code> on macOS and Linux and <code>%AppData%/devin/mcp_config.json</code> on Windows. The older <code>~/.codeium/windsurf/mcp_config.json</code> path is now used by the editor's MCP discovery.

03How do I pass an API key to an MCP server in Windsurf?+

Add a <code>headers</code> object to the server entry, such as <code>"Authorization": "Bearer ${env:ACME_MCP_TOKEN}"</code> or the custom header the server expects. Windsurf replaces <code>${env:NAME}</code> with the environment variable, so the secret never sits in the file.

04Does Windsurf support OAuth for remote MCP servers?+

Yes. Cascade supports OAuth for remote servers that use Streamable HTTP or SSE. Add the server with only its URL and complete the sign-in when Windsurf starts it. OAuth is not available for <code>stdio</code> servers.

05Should I use serverUrl or url in Windsurf's mcp_config.json?+

Windsurf's documentation accepts either field for a remote HTTP server. Use one of them for the endpoint, and never put a remote URL in the <code>command</code> field, which is only for local servers.

06Why is my MCP server blocked in Windsurf?+

On Teams and Enterprise plans, once an admin allowlists any MCP server, every server not on the allowlist is blocked. Enterprise accounts also need MCP turned on in settings. Ask your admin to enable MCP or add a matching allowlist entry.