# 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.

Source: https://zop.dev/integrations/mcp-server/clients/codex
Updated: 2026-08-20

---

## Common questions

### 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.

## 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

```toml
[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.