Codex CLI

OpenAI's Codex CLI reads MCP servers from ~/.codex/config.toml or, on recent versions, ~/.codex/config.json.

v4.0.0 — Codex auto-wire is best-effort
The v4.0.0 zero-config install (npm install --save-dev @codeatlas/mcp) writes the CodeAtlas entry into ~/.codex/config.json for you. If your Codex version reads config.toml instead, copy the same entry there manually — codeatlas-mcp doctor flags which one is expected. The manual stanzas below are the canonical reference for either format.

Configure

~/.codex/config.tomltoml
[mcp_servers.codeatlas]
command = "npx"
args = ["-y", "@codeatlas/mcp", "/absolute/path/to/your/workspace"]
Absolute paths
Codex spawns MCP processes from its home directory, not your shell's cwd. Pass an absolute path as the workspace argument. $(pwd) doesn't expand inside TOML.

Run

  1. Start a Codex session: codex.
  2. Type /mcp to list configured servers — you should see codeatlas connected with 54 tools.
  3. Ask a question that benefits from architecture: "What HTTP routes touch the User table? Use codeatlas tools."

Wrapper for per-project workspaces

One TOML config can serve every repo if you indirect through a wrapper that resolves the workspace at spawn time:

~/.local/bin/codeatlas-mcp.shbash
#!/usr/bin/env bash
# Codex starts MCP children from its own cwd; resolve the workspace from
# the CODEATLAS_WORKSPACE env var the parent shell set before launching codex.
exec npx -y @codeatlas/mcp "${CODEATLAS_WORKSPACE:-$PWD}"
~/.codex/config.toml — wrapper varianttoml
[mcp_servers.codeatlas]
command = "/Users/you/.local/bin/codeatlas-mcp.sh"
args = []
Launch with the workspace env varbash
CODEATLAS_WORKSPACE=$(pwd) codex

Useful recipes

Map an unfamiliar repo on day one

Prompt for Codextext
Using the codeatlas MCP tools, give me a one-page brief on this repo:
- top-level features (call list_entrypoints, then group by service)
- the 5 most-called functions (call query_snapshot)
- any obvious health issues (call get_health_report)
Cite the tool you used for each datum.

Pre-edit safety net

Prompt for Codextext
Before you propose any edit, call codeatlas:pre_edit_brief on the target file.
Read the callers and callees. If the impact spans >= 3 files, ask me first.

Diff-aware code review

text
Call codeatlas:get_diff_summary to see what changed vs baseline,
then for each modified file call get_impact_of_change.
Produce a review checklist grouped by blast radius (direct / transitive / review-required).

Workspace lock

If you run Codex with this MCP and the VS Code extension on the same checkout, the MCP server takes priority — the extension automatically drops to read-only and shows a toast. Nothing to configure.

Troubleshooting

Codex shows codeatlas as disconnected

Tail ~/.codex/logs/mcp.log. Common causes:

  • PATH doesn't resolve npx. Use absolute paths.
  • Workspace argument missing — Codex's TOML parser is strict, the array must be plain string elements, no trailing commas.
  • CodeAtlas couldn't find source files in the workspace path you passed. Check that the path points at a directory with code, not a docs-only folder.

Tools list is empty

Some Codex versions cache the tool list across sessions. Clear with codex mcp refresh codeatlas (newer builds) or remove and re-add the entry.

→ All 54 tools with examples