Connect Nucleus to Windsurf

Windsurf (by Codeium) supports MCP servers via Cascade. Config lives at ~/.codeium/windsurf/mcp_config.json — global only, no per-project files.

Option 1: Settings UI

1. Open Windsurf → Plugins icon in sidebar
2. Click "Manage plugins" → "View raw config"
3. Paste the config below and save
4. Reload window: Cmd+Shift+P → "Reload Window"

Option 2: Remote server (Streamable HTTP)

Edit ~/.codeium/windsurf/mcp_config.json:

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

Option 3: Local stdio server

{
  "mcpServers": {
    "nucleus": {
      "command": "python3",
      "args": ["-m", "mcp_server_nucleus"],
      "env": {
        "NUCLEAR_BRAIN_PATH": "/path/to/.brain"
      }
    }
  }
}

With OAuth (full server)

{
  "mcpServers": {
    "nucleus": {
      "serverUrl": "https://relay.nucleusos.dev/mcp",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}

Variable interpolation

Windsurf supports ${env:VAR_NAME} and ${file:/path} interpolation in config fields. Use this to avoid hardcoding tokens:

{
  "mcpServers": {
    "nucleus": {
      "serverUrl": "https://relay.nucleusos.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:NUCLEUS_TOKEN}"
      }
    }
  }
}

Install

Windsurf's MCP Marketplace is a curated list and does not currently include Nucleus. Install manually by editing your config file — this is the documented, supported path for any server not in their marketplace.

Open ~/.codeium/windsurf/mcp_config.json (Windsurf → Settings → Cascade → MCP Servers → Configure) and paste the config above into the mcpServers object.

Verify

Reload Windsurf (Cmd+Shift+P → "Reload Window"). Open Cascade and ask: Search my engrams for "architecture". If connected, you'll get results from your Nucleus brain.

Support: hello@nucleusos.dev · GitHub