Codex CLI
Why this agent
OpenAI’s Codex CLI is a terminal AI coding assistant. It supports MCP via TOML config; espctl plugs in the same way as for JSON-based agents, just with TOML syntax.
Prerequisites
- Codex CLI installed and on
$PATH(codex --versionworks). espctlinstalled somewhere stable on disk (full path needed below).- (Optional, for remote builds) An Aegis build server URL +
MCP_AUTH_SECRET.
Install snippet (or alternative)
Add to ~/.codex/config.toml (or .codex/config.toml in your project
folder for per-project use):
[mcp_servers.espctl]
command = "/path/to/espctl"
args = ["mcp", "serve"]
cwd = "/path/to/your/esp-idf/project"
[mcp_servers.espctl.env]
CONTROL_BASE_URL = "https://esphome.cloud"
MCP_AUTH_SECRET = "your-access-key"
Notes:
- The
[mcp_servers.espctl.env]section is its own TOML table — each variable on its own line. Don’t try to use a JSON-style nested map. argsis a TOML array of strings, exactly as shown.- The path/value rules are the same as in Claude Code.
Alternative — fetch a pre-filled TOML snippet:
Read
install://codexand show me the snippet.
First-run verification
Restart Codex CLI (or re-open the shell that was running it). Then in a Codex chat:
What espctl tools do I have?
Expected: ~40 tools listed.
Troubleshooting
- “unknown table” or TOML parse error on startup → check that
[mcp_servers.espctl]and[mcp_servers.espctl.env]are two separate tables on their own lines. Inlineenv = { ... }works in some TOML versions but not all; the two-section pattern is reliable. - Tool list empty → run with
codex --debug(prints MCP errors to the terminal) or check~/.codex/logs/. - Per-project config not picked up → Codex CLI reads
.codex/config.tomlfrom the current working directory; cd into the project before runningcodex.