Codex CLI MCP Servers: The Full mcp_servers Config Field Guide

Codex CLI declares MCP servers in the [mcp_servers] table of ~/.codex/config.toml — each sub-table is a named server, and both stdio (local process) and remote (HTTP) shapes share one field set. This guide walks the fields as defined by RawMcpServerConfig in the codex-rs source, not from memory.

1. Stdio: local processes

[mcp_servers.wave]
command = "python"
args = ["-m", "wave_mcp.server", "--session", "/abs/path/to/session"]
env = { "API_KEY" = "..." }
cwd = "/path/to/workdir"

Five stdio fields:

• command — the process to launch
• args — argument array
• env — literal key/value pairs injected into the process environment
• env_vars — a list of host environment variable names to pull values from (keeps secrets out of the file)
• cwd — working directory for the server process

The difference between env and env_vars is whether a secret lands on disk — prefer env_vars for tokens.

2. Remote: HTTP servers

[mcp_servers.linear]
url = "https://mcp.linear.app/mcp"
bearer_token_env_var = "LINEAR_TOKEN"

Remote fields:

• url — the server endpoint
• bearer_token / bearer_token_env_var — a literal token or one read from the environment
• http_headers / env_http_headers — custom request headers (the latter resolving values from env vars)
• http_headers_helper — a helper-command form that produces header values

3. Shared controls

Fields applying to both shapes:

required = true deserves a second look: it does not mean "try harder" — it means "fail the session if this server is missing". Right for hard dependencies, wrong for nice-to-haves.

4. OAuth and auth

The auth field's enum is oauth / chatgpt / ema_auth. Servers needing a full OAuth flow use the [mcp_servers.<name>.oauth] block with client_id, callback_url, callback_port and authorization_server_issuer.

5. Common errors and debugging

• Server fails to start: check whether command resolves — npx/uvx may not be on PATH when Codex launches from a GUI context; then raise startup_timeout_sec
• Tools not visible: check disabled_tools and the requirements layer — Codex has plugin/requirements-level MCP filtering, and admin-side required constraints can work in reverse
• Secrets in the repo: bearer_token and env are plaintext; project-level .codex/config.toml is committed to git — always use the *_env_var forms for secrets

6. Next steps

• Codex CLI Sandbox Modes: sandbox_mode and approval_policy Explained — the security boundary around MCP
• Getting started with OpenAI Codex CLI: from install to daily use — install and sign-in basics