Windsurf

Windsurf is a Code-OSS fork by Codeium with the Cascade agent built in. CodeAtlas installs as a standard VSIX; Cascade can then talk to the bundled MCP server via Windsurf's MCP config.

Install

Windsurf's extension index is backed by Open VSX, where CodeAtlas is published as codeatlaslive.codeatlas-live.

Option A — search from inside Windsurf

  1. Open the Extensions view (⌘ ⇧ X).
  2. Search for CodeAtlas-Live and hit Install.
  3. Open a workspace; visit http://localhost:7742.

Option B — sideload the VSIX

  1. Download the VSIX from open-vsx.org/extension/codeatlaslive/codeatlas-live — click the Download button.
  2. In Windsurf: ⌘ ⇧ P → Extensions: Install from VSIX….
  3. Quit and reopen Windsurf.

Wire CodeAtlas into Cascade (MCP)

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json.

~/.codeium/windsurf/mcp_config.jsonjson
{
  "mcpServers": {
    "codeatlas": {
      "command": "node",
      "args": [
        "/Users/you/.windsurf/extensions/codeatlaslive.codeatlas-live-5.0.0/dist/mcp-server.js",
        "/absolute/path/to/your/workspace"
      ]
    }
  }
}

Reload Windsurf (⌘ ⇧ P → Developer: Reload Window), then open Cascade. The status panel should list codeatlas with 25 tools.

What Cascade gets

  • Structured architecture instead of grep. Cascade can calllist_entrypoints, get_entrypoint_pack,get_impact_of_change rather than reading files page by page.
  • SQL access to the snapshot. Read-only SELECT over the indexed graphs via query_snapshot — group routes by method, find all handlers that touch a given table, etc.
  • Pre-edit briefs. pre_edit_brief(file) returns a short summary of the file's role, callers, callees, and tests — ~800 tokens vs ~10k of file content.
Token economics
File-walking a medium repo costs ~14k tokens; the same architectural question answered via list_entrypoints + one pack returns in ~2.5k. See the tools reference for per-tool measurements.

Or skip the VSIX, just run the MCP

If you only want Cascade integration and don't need the browser diagrams, use the published npm package instead — no VSIX path to maintain:

~/.codeium/windsurf/mcp_config.json — npm variantjson
{
  "mcpServers": {
    "codeatlas": {
      "command": "npx",
      "args": ["-y", "@codeatlas/mcp", "/absolute/path/to/your/workspace"]
    }
  }
}

Troubleshooting

Cascade shows codeatlas as "0 tools"

Almost always a path issue. Tail Windsurf's MCP log:

Inspect MCP stderrbash
tail -f ~/.codeium/windsurf/logs/mcp.log

Workspace not indexing

Make sure the path in args[1] is the same workspace you opened in Windsurf. The MCP server bootstraps its own .codeatlas/state.db if missing.