Cursor (as an MCP host)

Cursor has a first-class MCP panel — Settings → MCP. Adding CodeAtlas through it gives Composer and chat 25 architectural tools without any extension install.

Two ways into Cursor
If you also want the diagrams in your browser, install the CodeAtlas VSIX in Cursor — the VSIX already bundles the MCP binary, so you don't even need the npm install in that case.

Configure via the UI

  1. Open Cursor → Settings → MCP.
  2. Click + Add new MCP server.
  3. Set Type to stdio, Name to codeatlas.
  4. Command: npx — or the absolute Node path if Cursor can't find it.
  5. Args: -y @codeatlas/mcp /absolute/path/to/your/workspace
  6. Save. The panel should show 25 tools after a few seconds.

Or edit the JSON directly

~/.cursor/mcp.jsonjson
{
  "mcpServers": {
    "codeatlas": {
      "command": "npx",
      "args": ["-y", "@codeatlas/mcp", "/absolute/path/to/your/workspace"]
    }
  }
}

Per-project config

Cursor also reads .cursor/mcp.json at the repo root. Use this form to ship MCP wiring alongside the codebase (so teammates get the same tools after checkout):

./.cursor/mcp.json — project-scopedjson
{
  "mcpServers": {
    "codeatlas": {
      "command": "npx",
      "args": ["-y", "@codeatlas/mcp", "."]
    }
  }
}
The dot path
A relative "." works in Cursor's project-scoped config because Cursor spawns the MCP child with the project root as cwd. Other clients (Claude Code, Codex, Gemini) need absolute paths.

Composer recipes

Architecture-first refactor

Composer prompttext
@codeatlas Before suggesting any rename or move:
1. call pre_edit_brief on the target file
2. call get_impact_of_change with the proposed renames
3. only then write the diff

Find the right test to extend

text
@codeatlas For the function I'm editing, call query_snapshot to find the
nearest existing test file that already covers a sibling function in the same
module. Suggest where the new test case should land.

Quick health audit

text
@codeatlas Run get_health_report and list the top-3 issues by severity,
with the affected file paths and a one-line fix suggestion each.

Workspace lock

If you also have the CodeAtlas extension installed inside Cursor pointed at the same workspace, the standalone MCP will take precedence and the extension will yield. To avoid the back-and-forth: pick one or the other for a given checkout.

Troubleshooting

"command not found: npx"

Cursor spawns MCP children with a minimal PATH on some systems. Replace the command with the absolute Node binary and let it run the package's main module directly:

json
{
  "command": "/usr/local/bin/node",
  "args": [
    "/usr/local/lib/node_modules/@codeatlas/mcp/dist/mcp-server.js",
    "/absolute/path/to/your/workspace"
  ]
}

Tools list refuses to refresh

Cursor caches MCP capabilities. Toggle the server off and back on in the MCP panel, or quit and relaunch Cursor.

Snapshot looks stale

The MCP server polls the workspace. If you edit outside the open Cursor window, allow a few seconds for the polling tick to catch up, or run codeatlas:get_workspace_status — it forces a re-scan of dirty files.

→ All 25 tools with examples