Codex

Codex reads its configuration from TOML rather than JSON, which is the only thing that makes this setup look different from the others. The server, the environment variables, and everything the agent can do are identical.

Add it from the terminal

codex mcp add helmdesk --env HELMDESK_API_KEY=sk_live_your_key_here -- npx -y @helmdesk/mcp

Note the argument order

The server name comes before the --envflags here, which is the opposite of Claude Code's CLI. Everything after -- is the command Codex runs.

Repeat the flag for more variables:

codex mcp add helmdesk \
  --env HELMDESK_API_KEY=sk_live_your_key_here \
  --env HELMDESK_PROJECT=ledgerly \
  --env HELMDESK_ENVIRONMENT=sandbox \
  -- npx -y @helmdesk/mcp

Or edit the config directly

The file is ~/.codex/config.toml. Note the table name is mcp_servers with an underscore — not mcpServers as in every JSON-based client. It is an easy thing to copy across from another setup and then spend twenty minutes debugging.

~/.codex/config.toml

[mcp_servers.helmdesk]
command = "npx"
args = ["-y", "@helmdesk/mcp"]

[mcp_servers.helmdesk.env]
HELMDESK_API_KEY = "sk_live_your_key_here"
HELMDESK_PROJECT = "ledgerly"
HELMDESK_ENVIRONMENT = "sandbox"

The inline form works too, if you prefer one line: env = { HELMDESK_API_KEY = "sk_live_…" }. Only HELMDESK_API_KEY is required; HELMDESK_ENVIRONMENT accepts live or sandbox and nothing else.

Per-project configuration

Codex also reads .codex/config.toml from a trusted project directory. That is a good place to pin the project slug so the agent works on the right app in each repository, while the key stays in your global config:

.codex/config.toml

[mcp_servers.helmdesk.env]
HELMDESK_PROJECT = "ledgerly"

A plain .env in the repository works for this too — the server reads HELMDESK_PROJECT from the environment however it gets there. Keep the API key out of anything committed either way.

Check it worked

codex mcp list

Helmdesk should appear with 73 tools. If it does not, the server exits immediately when HELMDESK_API_KEY is missing or empty, printing a usage message to stderr — that is the first thing to check, followed by whether npx resolves in the environment Codex launches.

Try it

Summarise my Helmdesk queue: what is open, what is stale, what needs a reply.

Look at the errors from the last day and tell me whether any of them
match a ticket a customer has already written in about.

That second one is the sort of question that is genuinely awkward to answer by hand and trivial to ask for — it crosses the log plane and the ticket queue in one sentence. The prompt cookbook has more, and Safety & approvals covers what to bound before pointing this at live data.