Codex CLI

OpenAI’s Codex CLI supports espctl through a TOML config file. The format looks slightly different from the JSON tools but it does the same thing.

Configuration

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.
• args is a TOML array of strings, exactly as shown.
• The path/value rules are the same as in Claude Code.

Check it’s working

Restart Codex CLI (or re-open the shell that was running it). Then in a Codex chat:

What espctl tools do I have?

You should see the standard ~40-tool list. If something’s wrong, check Codex’s debug log (usually ~/.codex/logs/, or run with codex --debug to print to your terminal).

Codex-specific notes

• TOML cares about table headers. The two-section pattern ([mcp_servers.espctl] then [mcp_servers.espctl.env]) is the reliable shape — putting env inline as env = { ... } works in some TOML versions but not all.
• Codex CLI honors per-project .codex/config.toml, which is the natural place to put espctl when you only want it on a specific firmware project.

Tip

Ask Codex:

Read install://codex and show me the snippet.

…and espctl will hand you a freshly-generated TOML block.