Gemini CLI

Google's Gemini CLI reads MCP servers from ~/.gemini/settings.json under the mcpServers key. The shape is identical to Claude Code's JSON config — one entry per server.

v4.0.0 — zero-config install handles this automatically
In v4.0.0, npm install --save-dev @codeatlas/mcp inside your repo auto-detects Gemini CLI and writes the entry into ~/.gemini/settings.json for you. See the MCP overview for the zero-config flow. The manual JSON below is the reference if you need a per-project override.

Configure

~/.gemini/settings.jsonjson
{
  "mcpServers": {
    "codeatlas": {
      "command": "npx",
      "args": ["-y", "@codeatlas/mcp", "/absolute/path/to/your/workspace"]
    }
  }
}
Antigravity uses the same shape
Google Antigravity (agent IDE) reads MCP servers from the same JSON shape under ~/Library/Application Support/Antigravity/mcp.json — see the Antigravity guide for the editor-side flow.

Verify

  1. Start the CLI: gemini.
  2. Run /mcp to list connected servers.
  3. Ask: "Use the codeatlas tools to summarise this repo's architecture in 5 bullets." The model will call list_entrypoints +get_health_report.

Tool-use limits

Gemini caps the number of tools it loads in a single context. CodeAtlas registers 54 tools — if you also have other MCP servers attached and you hit the cap, the most useful subset is:

  • list_entrypoints + get_entrypoint_pack — discovery
  • query_snapshot + describe_snapshot_schema — SQL inspection
  • get_impact_of_change + pre_edit_brief — safe edits
  • get_diff_summary + get_api_surface_diff — diff review
  • search_workspace — fallback semantic search

If Gemini complains about tool cardinality, mention the names you actually need in your prompt — recent versions filter the registered set against the prompt.

Recipes

Architecture summary in one turn

text
Use codeatlas:list_entrypoints to enumerate routes, codeatlas:query_snapshot
to count functions per service, and codeatlas:get_health_report to surface
issues. Produce: 1) one-line elevator pitch, 2) services × responsibilities
table, 3) 3 health risks ranked by severity.

Cross-workspace comparison

Run two MCP servers — one per workspace — under different names:

~/.gemini/settings.json — dual workspacejson
{
  "mcpServers": {
    "atlas_main": {
      "command": "npx",
      "args": ["-y", "@codeatlas/mcp", "/Users/you/repos/api-v1"]
    },
    "atlas_next": {
      "command": "npx",
      "args": ["-y", "@codeatlas/mcp", "/Users/you/repos/api-v2"]
    }
  }
}

Then ask Gemini to "call atlas_main:list_entrypoints and atlas_next:list_entrypoints, produce the diff of route signatures." Or use the built-in compare_workspaces tool on either server pointed at the other.

Workspace lock

Same as every other client: when both the MCP server and the CodeAtlas VS Code extension point at the same workspace, the MCP server takes priority and the extension drops to read-only with a toast. Nothing to configure.

Troubleshooting

"Tool execution timed out"

The first call after a cold start triggers self-init: scan + parse + write .codeatlas/state.db. On a large monorepo this can take 30+ seconds. Subsequent calls are cached. If Gemini's default timeout is too tight, raise it via geminiClient.requestTimeout in the settings, or warm the snapshot once outside Gemini:

bash
# Run once to populate .codeatlas/state.db before launching gemini
node -e "process.exit(0)" | npx -y @codeatlas/mcp /path/to/repo &
sleep 30 && kill %1

Gemini ignores the workspace path

Confirm the path is absolute and exists. If the path is fine but CodeAtlas reports that it can't find source files, check that they aren't all under node_modules/, .git/, or a build output directory — those are skipped during indexing.

→ All 54 tools with examples