Codex CLI

Codex CLI is OpenAI's official local coding agent. It connects to Zephex using a Bearer token stored as an environment variable — never hardcoded in the config file.

OVERVIEW

Codex CLI (@openai/codex) is OpenAI's official terminal-based coding agent, built in Rust. It is distinct from the old OpenAI Codex model. It reads your codebase, suggests and implements changes, and runs commands locally with OS-level sandboxing. It connects to MCP servers via ~/.codex/config.toml (TOML format). Zephex connects using bearer_token_env_var — a field that tells Codex to read a named environment variable and send it as Authorization: Bearer <value>. Never paste the key directly into the TOML file — use the env var reference.

CONFIG FILE LOCATION

~/.codex/config.toml — TOML format, not JSON or YAML.

PREREQUISITES

Codex CLI installed: `npm i -g @openai/codex` or `brew install --cask codex`.
A Zephex account at zephex.dev/signup.
A Zephex API key from your dashboard.

CONFIG

Step 1: export the key in your terminal. Step 2: add the TOML block below to `~/.codex/config.toml`. The config references the environment variable name, not the secret value.

`bearer_token_env_var` points to the name of the environment variable — not the key itself. Add `export ZEPHEX_API_KEY="..."` to your shell profile (`~/.zshrc`, `~/.bashrc`) so it persists across sessions.

STEP 1 — EXPORT YOUR KEY

Export your Zephex API key in the terminal before you add the MCP server block.

terminal

export ZEPHEX_API_KEY="your_key_here"

~/.codex/config.toml

[mcp_servers.zephex]url = "https://zephex.dev/mcp"bearer_token_env_var = "ZEPHEX_API_KEY"enabled = truetool_timeout_sec = 60

OR ADD VIA CLI INSTEAD

If you prefer, let Codex add the MCP server entry without editing the TOML file manually.

terminal

codex mcp add zephex --url https://zephex.dev/mcp --bearer-token-env-var ZEPHEX_API_KEY

AUTH

Codex CLI reads the `ZEPHEX_API_KEY` env var and injects it as the `Authorization: Bearer` header on every request. No browser flow. No re-auth.

Add `export ZEPHEX_API_KEY="mcp_sk_..."` to your `~/.zshrc` or `~/.bashrc`.
Run `source ~/.zshrc` to apply immediately.
Add the TOML block to ~/.codex/config.toml.
Run `codex` — Zephex tools should be available immediately.
To verify the key is loaded: `echo $ZEPHEX_API_KEY`.

VERIFY

Verify both the MCP connection and the live tool list before using Zephex in normal Codex sessions.

Run `codex mcp list` — it should show "zephex" with status "connected".
Start a session: `codex`.
Ask: "what MCP tools are available?" — Codex should list all 10 Zephex tools.

COMMON ISSUES

"bearer token env var not set"

The `ZEPHEX_API_KEY` variable is not exported in your current shell. Run `export ZEPHEX_API_KEY="..."` or add it to your shell profile.

TOML format errors

The config uses TOML, not JSON. No quotes around `true`. The section header is `[mcp_servers.zephex]` with a dot, not nested braces.

Tools not loading

Try `codex mcp debug zephex` for detailed connection logs.

"unauthorized" on every call

Confirm the env var name in `bearer_token_env_var` exactly matches what you exported. It is case-sensitive.

If the editor still does not connect, return to Quickstart or check Connection Issues.