Claude Code

Claude Code (the official Anthropic CLI) reads MCP servers from its ~/.claude.json config and from per-project .mcp.json files. Adding CodeAtlas is one command.

One-line install

Add CodeAtlas to the current Claude Code projectbash
claude mcp add codeatlas -- npx -y @codeatlas/mcp $(pwd)

That writes an entry like this to your project's MCP config:

Equivalent JSONjson
{
  "mcpServers": {
    "codeatlas": {
      "command": "npx",
      "args": ["-y", "@codeatlas/mcp", "/absolute/path/to/your/repo"]
    }
  }
}
What the command does
  • claude mcp add codeatlas — register an MCP server named codeatlas.
  • -- — separator between Claude flags and the spawn command.
  • npx -y @codeatlas/mcp — fetch and run the latest package, auto-accepting any install prompt.
  • $(pwd) — absolute path of the current directory, passed as the workspace root.

Verify it's live

  1. Start (or restart) Claude Code in the same directory.
  2. Run /mcp. You should see codeatlas with 25 tools and 5 resources, status connected.
  3. Ask: "Use the codeatlas tools to list the HTTP routes in this repo." Claude will call list_entrypoints and return a structured list.

Recipe: pre-edit brief before any change

Put this in CLAUDE.md at the repo root so every session automatically asks for impact before touching code:

CLAUDE.md snippetmarkdown
## Before editing any handler or shared module
1. Call `codeatlas:pre_edit_brief` with the target file path.
2. Read the returned summary of callers, callees, tests, and routes.
3. Only then propose edits.
4. After applying edits, call `codeatlas:get_impact_of_change` to surface anything you may have missed.

Recipe: SQL-driven exploration

query_snapshot is the cheapest way to answer architecture questions — no file walking, no LLM gymnastics.

Top-25 most-called functionssql
SELECT callee AS function, COUNT(*) AS calls
FROM call_edges
GROUP BY callee
ORDER BY calls DESC
LIMIT 25;

Use describe_snapshot_schema first if Claude doesn't know the tables yet — it returns the column list for every allowlisted table.

Project-scoped vs user-scoped

  • Project-scoped (default for claude mcp addinside a repo): config lives at ./.mcp.json. Check it in if your teammates should get the same MCP wiring.
  • User-scoped: add -s user to apply it to every project for the current OS user. Config lands in ~/.claude.json.
User-scoped installbash
claude mcp add codeatlas -s user -- npx -y @codeatlas/mcp $(pwd)
User-scoped + $(pwd)
With -s user the path you pass becomes static — Claude won't substitute the new cwd when you cd to another repo. Use the project-scoped form per repo, or a small wrapper script that resolves the workspace from$PWD at spawn time.

Wrapper script for any-workspace use

~/.local/bin/codeatlas-mcpbash
#!/usr/bin/env bash
# Resolve the workspace at spawn time so one Claude config works for every repo.
exec npx -y @codeatlas/mcp "$PWD"

Make it executable, then:

bash
chmod +x ~/.local/bin/codeatlas-mcp
claude mcp add codeatlas -s user -- ~/.local/bin/codeatlas-mcp

Update & remove

bash
# Force a fresh version on next spawn (npx caches)
npx clear-npx-cache @codeatlas/mcp || true

# Remove the wiring
claude mcp remove codeatlas

Troubleshooting

Claude says "0 tools"

Check /mcp output for the error. The two most common: PATH doesn't resolve npx (use the absolute Node path), or the workspace argument is missing / wrong.

"workspace is not a codebase"

Self-init returned that status. Either the directory is empty / docs-only, or all source files are under skip-listed dirs. CodeAtlas indexes top-level src/, app/, lib/, etc. Pass a more specific workspace path if your code lives in a sibling directory.

Claude Code can't spawn npx

Replace npx with the absolute Node + module path:

json
{
  "command": "/usr/local/bin/node",
  "args": ["/Users/you/.npm-global/lib/node_modules/@codeatlas/mcp/dist/mcp-server.js", "$(pwd)"]
}

→ All 25 tools with examples