# Connect Codex to Axiom

**Transport:** stdio (Codex CLI MCP support, experimental as of 2026-Q2)
**Auth:** local-stdio (Phase 0)
**Status:** Untested — recipe inferred from upstream docs

Codex is OpenAI's terminal coding agent (the open-source CLI under
`openai/codex`). It ships MCP-client capability via its `mcp_servers`
config block. Configuration lives in `~/.codex/config.toml`.

## Install prerequisites

- Codex CLI: `npm install -g @openai/codex` (or build from source per
  the upstream README).
- Same Axiom prerequisites as the other recipes.

## Configure the connection

Edit `~/.codex/config.toml` and add an `mcp_servers` table:

```toml
[mcp_servers.axiom-root]
command = "/absolute/path/to/.venv/bin/axi"
args = ["mcp", "serve"]
```

Worktree variant — add an `env` table:

```toml
[mcp_servers.axiom-root]
command = "/absolute/path/to/.venv/bin/python3"
args = ["-m", "axiom.extensions.builtins.mcp.server"]

[mcp_servers.axiom-root.env]
PYTHONPATH = "/absolute/path/to/axiom-checkout/src"
```

## Verify

Start a Codex session:

```bash
$ codex
```

In the session, list tools:

```
> /tools
```

`axiom-root` should be present with its tool list. Then:

```
> Call axiom_node__hooks_list with no arguments and show the JSON.
```

Expected:

```json
{
  "node": "/Users/<you>/.axiom",
  "hooks_total": 0,
  "events_observed": [],
  "by_event": {}
}
```

## Notes

- Codex's MCP support is newer than the Anthropic-side harnesses; the
  exact config block path and command names may shift. The TOML key
  `mcp_servers` and the stdio sub-table shape are aligned with the
  community-standard pattern (Cline, Continue.dev, Claude Code).
- For HTTP/SSE servers, Codex accepts `url = "..."` and `auth = "..."`
  fields under the same table; needs Axiom Phase 5 auth.
- If Codex's bundled MCP client is partial / experimental on your
  version, fall back to the bridge pattern from
  [open-interpreter.md](open-interpreter.md) — `axi mcp call <tool>`
  + a shell wrapper.

## Troubleshooting

| Symptom | Likely cause | Fix |
|---|---|---|
| `unknown config section: mcp_servers` | Codex too old | Upgrade Codex CLI to latest |
| Server reported as "failed" | command path | Use absolute path; `which axi` |
| Tools listed but call errors | argument schema mismatch | `axi mcp inspect <tool>` to see canonical schema |

## References

- ADR-038 §D7
- Codex CLI: https://github.com/openai/codex

_Copyright (c) 2026 B-Tree Ventures, LLC. Apache-2.0 licensed._
