Codex CLI

OpenAI's Codex CLI reads MCP servers from ~/.codex/config.toml under an [mcp_servers.<name>] table. Adding CodeAtlas is a 4-line TOML stanza.

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 25 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 wins — the extension drops to read-only. See the extension overview for the lock protocol.

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.
  • Self-init returned not_a_codebase. Look at the tool output, not the connection status.

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 25 tools with examples