DEV Community

Nucleus OS
Nucleus OS

Posted on • Originally published at eidetic.works

How to connect an MCP server to Cursor, Windsurf, and Gemini

#mcp #cursor #windsurf #ai

Every AI coding editor now supports MCP (Model Context Protocol). But they all have different config file locations, different field names, and different gotchas. Here's the cheat sheet for connecting a remote MCP server to five major editors/clients.

Cursor

Config location: ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project)

Remote server (Streamable HTTP):

{
  "mcpServers": {
    "nucleus": {
      "url": "https://relay.nucleusos.dev/mcp-readonly",
      "type": "streamableHttp"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Gotcha: You must completely quit and restart Cursor after editing the config. MCP servers only load at startup.

UI path: Settings → Tools & MCP → Add new MCP server

Windsurf

Config location: ~/.codeium/windsurf/mcp_config.json (global only — no per-project)

Remote server (Streamable HTTP):

{
  "mcpServers": {
    "nucleus": {
      "serverUrl": "https://relay.nucleusos.dev/mcp-readonly"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Gotcha #1: Windsurf uses serverUrl instead of url. If you copy a Cursor config, it silently fails — no error, no connection.

Gotcha #2: The path is .codeium/windsurf/, not .windsurf/.

Gotcha #3: Windsurf supports variable interpolation: ${env:VAR_NAME} and ${file:/path} in config fields.

Google Gemini / Antigravity

Config location: ~/.gemini/config/mcp_config.json

Remote server (Streamable HTTP):

{
  "mcpServers": {
    "nucleus": {
      "serverUrl": "https://relay.nucleusos.dev/mcp-readonly"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Gotcha: Gemini Enterprise only accepts Streamable HTTP (not deprecated SSE).

OpenClaw

Config location: ~/.openclaw/openclaw.json under mcp.servers

OpenClaw is both an MCP client and server. You register external servers with openclaw mcp set:

openclaw mcp set nucleus '{
  "transport": "http",
  "url": "https://relay.nucleusos.dev/mcp-readonly"
}'
Enter fullscreen mode Exit fullscreen mode

Gotcha: Registered servers are only consumed by OpenClaw-managed runtimes that read mcp.servers at startup. Not every runtime picks them up automatically.

OpenCode

Config location: Managed via opencode mcp commands

opencode mcp add nucleus --url https://relay.nucleusos.dev/mcp-readonly
Enter fullscreen mode Exit fullscreen mode

For OAuth-protected servers:

opencode mcp add nucleus --url https://relay.nucleusos.dev/mcp
opencode mcp auth nucleus
Enter fullscreen mode Exit fullscreen mode

Comparison table

Editor Config path Remote field Per-project?
Cursor ~/.cursor/mcp.json url Yes (.cursor/mcp.json)
Windsurf ~/.codeium/windsurf/mcp_config.json serverUrl No (global only)
Antigravity ~/.gemini/config/mcp_config.json serverUrl No (global only)
OpenClaw ~/.openclaw/openclaw.json url (in JSON) No (global only)
OpenCode CLI-managed --url flag No (global only)

The one that catches everyone

If your MCP server works in Cursor but not in Windsurf, check the field name. Cursor uses url, Windsurf uses serverUrl. Same JSON structure, different key. Silent failure, no error message.

If it works in Windsurf but not in Antigravity, check the transport. Antigravity rejects deprecated SSE — it only accepts Streamable HTTP.

Full guides

Building Nucleus — persistent memory for AI coding agents. Open source on GitHub. Install: pip install nucleus-mcp && nucleus-init --scan.

Top comments (0)