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.

Configure

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

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 25 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

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:

{
  "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 protocol as every other client: the MCP server takes the lock; a parallel VS Code extension drops to read-only with a toast. See the extension overview.

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:

# 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 Gemini still reports not_a_codebase, check that source files aren't all under node_modules/ / .git/ / build outputs — the classifier skips those.

→ All 25 tools with examples