Connect Codex
How do I connect Codex?
Codex connects to the ZopNight MCP server via Settings → MCP Servers with Streamable HTTP transport, or through `~/.codex/config.toml`. Codex reads the token from an environment variable rather than inline, so `bearer_token_env_var` points at the variable name, not the token itself.
| Setting | Value |
|---|---|
| Config location | ~/.codex/config.toml |
| Auth | Personal Access Token (Bearer) |
Settings, MCP Servers, or config.toml
Add the server under Settings → MCP Servers with transport Streamable HTTP (not STDIO), or use ~/.codex/config.toml below. That is the documented route for the token, which Codex reads from an environment variable rather than taking it inline.
The config.toml entry for Codex
[mcp_servers.zopnight]url = "MCP_SERVER_URL"bearer_token_env_var = "ZOP_MCP_TOKEN"Export the token before starting Codex with export ZOP_MCP_TOKEN=zn_pat_…, and Codex sends it as a Bearer Authorization header.
The token indirection
Codex is the one client that does not take the token inline. bearer_token_env_var names an
environment variable, and Codex reads the value from your shell at call time. Put
ZOP_MCP_TOKEN in your environment, not the zn_pat_… value in the TOML. Pasting the token
directly is the usual reason authentication fails here.
Choose Streamable HTTP, not STDIO, when adding through the Settings UI.
What Codex can read without a write tier
At the default org setting, read-only, 85 of the 119 tools work immediately. That covers cost totals by team or tag, spend trends, budget health, detected anomalies, the full resource inventory, recommendations with their savings, Kubernetes logs and events, and deploy history.
Ask for a cost overview first; it is the entry point the tool set is designed around.
Write tiers an admin must raise for Codex
Mutating tools sit behind an org-level dial with four positions, each cumulative:
| Tier | What it unlocks |
|---|---|
| Read-only | nothing mutating (the default) |
| Metadata | budgets, recommendation status, smart-tag decisions |
| Reversible | schedules, overrides, tagging policies, deploys and rollbacks |
| Irreversible | start/stop, provisioning, Kubernetes writes, deletes |
Your own RBAC still applies on top: the tier is a ceiling, not a bypass. Roles, user management, credentials and cloud-account deletion are never reachable at any tier.
Codex starts but exposes no tools
Two causes account for almost every case. Either MCP is not enabled for the organisation, or the transport is wrong. MCP is off by default, and an admin turns it on in Organisation Settings. Every mutating call is audit-logged with its source, so MCP activity stays distinguishable from UI and API activity afterwards.
Codex: troubleshooting
Where does Codex keep its MCP configuration?
In ~/.codex/config.toml. You can also add the server under Settings, MCP Servers, choosing transport Streamable HTTP rather than STDIO.
Why is Codex rejecting my token?
Because bearer_token_env_var names an environment variable, not the token itself. Put ZOP_MCP_TOKEN in the TOML and export the zn_pat_ value in your shell before starting Codex. Pasting the token straight into the TOML is the usual cause.