Add a remote MCP server to Windsurf
Windsurf became Devin Desktop on June 2, 2026, and the Cascade agent reads MCP servers from mcp_config.json under an mcpServers key. A remote server takes serverUrl (or url) and an optional headers object. The newer Devin Local agent and Devin CLI use their own commands: see the Devin page.
By Jake Marsh. Checked against Windsurf's own docs on 2026-10-31; each section links its source.
The Windsurf config
For a server named my-server at https://example.com/mcp that takes an Authorization header. Where it goes: ~/.config/devin/mcp_config.json (older Windsurf: ~/.codeium/windsurf/mcp_config.json).
{
"mcpServers": {
"my-server": {
"serverUrl": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Swap in your own server below and the Windsurf version updates first, with every other client after it.
Where Windsurf reads it
~/.config/devin/mcp_config.json ($XDG_CONFIG_HOME/devin/mcp_config.json when set; %AppData%/devin/mcp_config.json on Windows)your user: the file Cascade's Open MCP config file action opens~/.codeium/windsurf/mcp_config.json (Next builds: ~/.codeium/windsurf-next/mcp_config.json)your user: the separate file the editor's own MCP discovery reads
Keys, headers and sign-in
Put a static key in headers. Cascade expands ${env:NAME} in command, args, env, serverUrl, url and headers, so the file can name an environment variable instead of holding the key.
OAuth works for remote servers that use Streamable HTTP or SSE. It isn't available for stdio servers, which take their credentials through env or args.
{
"mcpServers": {
"my-server": {
"serverUrl": "https://example.com/mcp",
"headers": { "Authorization": "Bearer ${env:MY_SERVER_KEY}" }
}
}
}Check that it connected
Open the MCP menu in the Cascade panel to open the config file or manage servers, and press the refresh button after you add one so Cascade loads it. In the JetBrains plugin, servers are added from Settings > Tools > Windsurf Settings > Add Server.
Windsurf gotchas
Cascade accepts serverUrl or url for a remote server. Devin CLI, which reads the same ~/.config/devin/mcp_config.json, documents only url, so use url in a file both of them read.
On Teams and Enterprise plans, admins can turn MCP off or keep an allowlist. Once one server is allowlisted, every server that isn't on the list is blocked for the team. Enterprise users have to turn MCP on in settings first.
Your Windsurf settings carry over to Devin Desktop, and Devin Local inherits them, so an existing server list doesn't need to be re-entered after the rename.
Still not connecting? Windsurf MCP server not connecting walks through the fixes in order.
Generate the config for your server
Runs in your browser. Nothing you type is sent anywhere. Still, don't paste real keys on shared screens.
Windsurf / Devin Desktop
~/.config/devin/mcp_config.json (older Windsurf: ~/.codeium/windsurf/mcp_config.json)
{
"mcpServers": {
"my-server": {
"serverUrl": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Claude Code
Run in a terminal (--scope user makes it available in every project)
claude mcp add --transport http --scope user my-server "https://example.com/mcp" --header "Authorization: Bearer YOUR_KEY"Source: code.claude.com/docs/en/mcp
Cursor
~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project)
{
"mcpServers": {
"my-server": {
"url": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Source: cursor.com/docs/context/mcp
Codex CLI
~/.codex/config.toml
[mcp_servers.my_server]
url = "https://example.com/mcp"
http_headers = { "Authorization" = "Bearer YOUR_KEY" }Source: developers.openai.com/codex/mcp
Devin CLI / Devin Local
Run in a terminal (-s user saves it to ~/.config/devin/mcp_config.json for every project)
devin mcp add -s user -H "Authorization: Bearer YOUR_KEY" my-server "https://example.com/mcp"VS Code (Copilot agent mode)
.vscode/mcp.json in the workspace, or your user mcp.json (MCP: Open User Configuration)
{
"servers": {
"my-server": {
"type": "http",
"url": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Source: code.visualstudio.com/docs/agents/reference/mcp-configuration
Gemini CLI
~/.gemini/settings.json (or .gemini/settings.json in the project)
{
"mcpServers": {
"my-server": {
"httpUrl": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Antigravity CLI (agy)
~/.gemini/config/mcp_config.json (or .agents/mcp_config.json in the workspace)
{
"mcpServers": {
"my-server": {
"serverUrl": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Source: antigravity.google/docs/mcp
Cline
cline_mcp_settings.json (in the Cline panel, MCP Servers > Configure > Configure MCP Servers; Cline CLI: ~/.cline/data/settings/cline_mcp_settings.json)
{
"mcpServers": {
"my-server": {
"type": "streamableHttp",
"url": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Source: docs.cline.bot/mcp/mcp-overview
OpenCode
opencode.json in the project root, or ~/.config/opencode/opencode.json for every project
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"my-server": {
"type": "remote",
"url": "https://example.com/mcp",
"oauth": false,
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Source: opencode.ai/docs/mcp-servers/
Need a task list for those agents?
Taskhold is a remote MCP server that gives Windsurf and your other agents a task list you share, with their progress on a live board. Its setup link writes this config for the agent, so you don't have to. $12 a month or $120 a year, 7-day trial.