Standalone MCP Server

@codeatlas/mcp is a 51-tool Model Context Protocol server that exposes a live architectural map of your codebase — and an AI code review built on the same six-layer model — as JSON-RPC over stdio. As of v4.0.0 it ships with zero-config install: one npm install inside your repo auto-wires every MCP client on the machine, starts a per-OS daemon, and opens a live browser surface at http://localhost:7842 — no JSON files to edit, no npx chaining.

What you get

  • Zero-config install (v4.0.0). npm install --save-dev @codeatlas/mcp inside your repo auto-detects 7 MCP clients on the host (Claude Desktop, Cursor, Claude Code CLI, Codex CLI, Gemini CLI, VS Code Copilot Chat, Continue), writes the CodeAtlas entry into each one's config (atomic + backed up + idempotent), starts a per-OS daemon (launchd / systemd / Task Scheduler), and serves a live diagram surface in your browser. Re-runnable any time via codeatlas-mcp setup.
  • 54 tools covering entrypoints, packs, diffs, impact, health, function source, call paths, API surface diffs, pre-edit briefs, pagination, architecture rules, coverage overlay, find-similar, saved views, search, SQL, snapshot schema, cross-workspace compare, deterministic summarise, OpenAPI / function-calling spec exporters, an API-testing toolkit (chain runner, SSE/WebSocket clients, OAuth2, OpenAPI / Postman / Insomnia importer), three evidence-gated LLM generators for request bodies / chains / test cases, and 15 AI code review tools grounded in source quotes.
  • 8 resources: codeatlas://workspace/microservices, /apis, /features, /entrypoints, /diff-summary, /ai-findings, /review-guidelines, /review-summary.
  • Push notifications. Stdio clients that subscribe get a findings_changed event whenever findings are added, updated, or removed — no polling needed.
  • Self-init. On first launch the server scans the workspace, builds the snapshot DB at .codeatlas/state.db, and starts a file watcher. No editor required.
  • Polyglot. Indexes Python, Java, Kotlin, Go, Rust, Ruby, PHP, Swift, Dart, C#, plus JS/TS — the host only needs Node.js ≥ 18.
  • Multi-provider AI. Bring your own LLM — OpenRouter, OpenAI, Anthropic, Ollama (local), or any OpenAI-compatible endpoint. Local Ollama doesn't need an API key.

Install

As of v4.0.0 the recommended path is one npm install inside your repo. The postinstall script auto-wires every detected MCP client on the host AND starts a per-OS daemon so the browser surface and index stay live as you edit:

Recommended — zero-config install (v4.0.0)bash
cd /path/to/your/repo
npm install --save-dev @codeatlas/mcp
# Daemon auto-starts. Configs auto-written. Browser at http://localhost:7842.
# 54 tools instantly available in every detected MCP client.

# If your shell piped the install through tee/tail/CI, recover the banner:
cat ~/.config/codeatlas/last-install.txt
Why this is better than npx
npx chains were the v2 path. v4.0.0+ picks an unused port (7842 → next free), writes idempotent configs into each client's settings file (atomic + backed up), and registers a background daemon. Next time you open Claude Desktop / Cursor / Codex the CodeAtlas tools are already there — and stay fresh as you edit, no re-spawn needed.

Want to use npx for a one-shot session instead? It still works exactly as before:

Alternative — one-shot npx (v2 flow)bash
npx -y @codeatlas/mcp /absolute/path/to/your/workspace

CLI subcommands

  • codeatlas-mcp setup [workspace] — rerun the zero-config auto-wire (after --ignore-scripts, or to add a newly installed client). Flags: --no-browser, --read-only, --dry-run, --only=<client,client>, --client-config <path>, --force.
  • codeatlas-mcp doctor — diagnostic dump: platform, Node version, telemetry state, each detected MCP client (with present/absent CodeAtlas entry), daemon status, browser URL.
  • codeatlas-mcp teardown — remove the per-workspace daemon (LaunchAgent / systemd unit / Scheduled Task). Configs stay so reinstall is one command.

Supported MCP clients (auto-wired)

  • Claude Desktop
  • Cursor
  • Claude Code CLI
  • Codex CLI — best-effort. Codex may use a TOML config format that differs from the others; codeatlas-mcp doctor will flag it if your setup needs a manual tweak.
  • Gemini CLI
  • VS Code Copilot Chat
  • Continue

Per-client guides:

Claude CodeCodex CLIGemini CLICursor
Want the full tool list?
Tools reference → — one-paragraph description plus a sample input/output for each of the 54 tools.

How self-init works

  1. On first launch the server scans your workspace, skipping node_modules/, .git/, and build directories. It detects which of the 11 supported languages are present.
  2. If the workspace is empty or doc-only, every tool returns a clean diagnostic explaining that there's nothing to index — no diagrams, no crash.
  3. Otherwise it builds the snapshot at .codeatlas/state.db and starts a file watcher. The snapshot stays in sync with your code as you edit. No editor required.

Running alongside the VS Code extension

The MCP server and the VS Code extension can both point at the same workspace without conflict. When the MCP server is running it takes priority — the extension automatically drops to read-only and shows a toast ("Yielded write-lock to MCP server"). When the MCP server stops, the extension resumes writing. Nothing to configure on either side.

SQL access (no LLM)

query_snapshot runs read-only SQL against the snapshot DB with strict guardrails: SELECT or WITH only, table allowlist, multi-statement blocked, CTE-aware, row cap. Pair it with describe_snapshot_schema so the model can introspect first.

Sample: group routes by HTTP methodsql
SELECT method, COUNT(*) AS n
FROM apis
GROUP BY method
ORDER BY n DESC
LIMIT 10;

Token economics (measured v4.0.0)

Validated live on a Node Express RealWorld backend (33 TypeScript files, 27 routes, ~14k tokens of source — the “full file-walk” baseline):

  • get_workspace_status — 68 tokens (~208× reduction)
  • search_workspace — 272 tokens (~52×)
  • get_impact_of_change — 367 tokens (~38×)
  • list_architecture_violations — 817 tokens (~17×)
  • get_entrypoint_pack w/ source — 1,181 tokens (~12×)
  • get_feature_pack — 1,690 tokens (~8×)
  • list_entrypoints (27 routes) — 2,759 tokens (~5×)

5–200× reductions in the measured range. Ratios grow with codebase size — a 100k-LOC monorepo dwarfs these absolute numbers.

Where to get it