Windsurf Integration Guide

Windsurf is an agentic AI coding IDE developed by Codeium. Like Cursor, it supports MCP configurations, letting you hook up Proxima's 41 local tools to the Windsurf Cascade panel and AI workflows.

1. Editor Configuration File Setup

To configure Proxima inside Windsurf, you must append it to Windsurf's global MCP settings file, mcp_config.json:

File Path Locations

# Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json # macOS: ~/.codeium/windsurf/mcp_config.json # Linux: ~/.codeium/windsurf/mcp_config.json

JSON Configuration Block

Open the file in a text editor (or inside Windsurf itself) and paste the following server declaration:

{ "mcpServers": { "proxima": { "command": "node", "args": [ "C:/path/to/proxima/src/mcp/index.js" ] } } }
Note: Make sure you replace C:/path/to/proxima with the exact absolute directory path where your local Proxima server resides.

2. Activating in Windsurf Cascade

After saving the mcp_config.json file, follow these steps to verify connection in the editor:

1 Restart Windsurf or reload the active window (Ctrl+R or Cmd+R).
2 Open the Cascade chat panel on the right side.
3 Check the Cascade settings or connection icon. If successful, you will see a badge showing the active proxima MCP server.
4 Cascade can now call any Proxima tool automatically to help you answer prompts or write files.

3. Check that it actually works

A green badge only tells you that Windsurf started the Node process. To confirm that tool calls reach your models, run a small request from Cascade that touches the full path from editor to provider.

Start the desktop app first

The file src/mcp/index.js is a thin bridge. It speaks MCP to Windsurf over standard input and output, then forwards each tool call to the Proxima desktop app on a local port (19222 by default, bound to 127.0.0.1; if it is taken, the bridge scans nearby ports). If the desktop app is closed, the badge can still appear but every tool call will fail. Open Proxima, and log in to ChatGPT, Claude, Gemini or Perplexity in its tabs (Session Mode), or add an API key or a local endpoint under Settings (BYOK Mode).

Three prompts to try, in order

  • Bridge and models: ask Cascade to call list_available_models. It needs the bridge and the desktop app, and it returns the models your logged-in accounts actually offer. If it lists nothing, no provider is logged in yet.
  • Connectivity: ask Cascade to call ask_model (or ask_claude, ask_chatgpt) with a one-line question, using a model slug from the previous step. If this works, the bridge and the provider session are both fine.
  • Search: ask it to use ddg_search. This tool needs no provider session, so it separates "the MCP bridge is broken" from "my provider login expired".
  • Multi-model: ask it to use smart_query in verify mode on a short technical claim. This is the quickest way to see two providers answer the same question through one tool.

If the second prompt works and the first does not, the problem is almost always an expired provider login rather than your Windsurf configuration.

4. Troubleshooting

The proxima server does not appear in Cascade

  • Open mcp_config.json and check that the JSON is valid. A trailing comma or a missing brace stops Windsurf from loading any server in the file, including ones that worked before.
  • Use forward slashes in the path on Windows (C:/Users/you/Proxima/src/mcp/index.js). Single backslashes are escape characters in JSON and corrupt the path.
  • Run node --version in a terminal. Proxima's MCP server needs Node.js 18 or newer. If node is not on your PATH, put the absolute path to the Node binary in the command field.
  • The top-level key must be mcpServers in this file. The VS Code format (servers) is different, see the VS Code guide.

The server appears but tool calls fail

  • Confirm the Proxima desktop app is running (see section 3).
  • Re-open the provider tab inside Proxima. Provider sessions expire the same way they do in a normal browser, and a logged-out tab produces failed or empty replies.
  • If you also use the REST API, note that it is a separate switch: it is off until you enable it in Settings, and then listens on 127.0.0.1:3210 by default (5.5.0 moves to the next free port if 3210 is busy; see the troubleshooting guide). The MCP bridge does not depend on it.

The Python agent shows an error in Diagnostics

This affects the optional Python agent, not the MCP bridge. See the troubleshooting guide for the Python 3.10+ and PATH cases.