mcp-proxy for Windsurf: Setup & Config

What you can do with mcp-proxy in Windsurf

Pick it to bridge existing MCP transports and route named local servers without replacing their tools.

• Expose a local stdio server for network clients.
• Pass authentication headers or OAuth2 credentials to an upstream service.

Before you start: mcp-proxy in Windsurf

• mcp-proxy installed using uv or pipx
• uvx and the mcp-server-fetch package for this documented example
• An MCP-compatible client

This README example exposes a local fetch stdio server through the proxy. Install mcp-proxy with uv tool install mcp-proxy or pipx install mcp-proxy first. The opposite mode takes an upstream URL; choose --transport=streamablehttp for a Streamable HTTP upstream.

mcp-proxy Windsurf configuration

1. Choose Windsurf configuration scope

   For mcp-proxy, open macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Merge into mcpServers; remote endpoints use serverUrl.

2. Add mcp-proxy to Windsurf

   Use the mcp-proxy entry below in mcpServers. Keep mcp-proxy's documented sse connection fields and your other Windsurf entries.

3. Check mcp-proxy in Windsurf

   mcp-proxy: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

{
  "mcpServers": {
    "mcp-proxy": {
      "serverUrl": "http://127.0.0.1:8080/sse"
    }
  }
}

Troubleshooting mcp-proxy in Windsurf

• For mcp-proxy, Windsurf reads serverUrl (127.0.0.1:8080), not url. Refresh the connection and check the tools exposed to Cascade.
• mcp-proxy: check sse connectivity to 127.0.0.1:8080 from Windsurf; a stdio command is not a replacement for this endpoint.
• Transport mismatch: mcp-proxy's catalog lists stdio; the displayed Windsurf configuration uses sse.
• Known limitation: Wrapped server executables and dependencies must be available separately.
• Known limitation: The default container image does not include uv.
• Known limitation: Named-server timeout and transportType fields are ignored.
• General Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions