Header setup on mcp install trough cli --header

[Soxomer]

Why we can only set headers by going in the .toml itself and cant simply pass --header X-My-Header=XXXX like in claude cli ? It seems like a deliberate choice but really complicating our users onboarding.

[paulodearaujo]

I checked the current CLI and source: you're not missing a flag. Arbitrary headers are supported by the MCP client and config, but codex mcp add currently only exposes --url, --bearer-token-env-var, and the OAuth options. The add path creates the HTTP transport with both custom-header maps unset (CLI args, transport construction). I didn't find anything suggesting this is an intentional security restriction; it looks like a missing CLI convenience.

Bearer auth can be configured entirely from the CLI:

codex mcp add my-server \
  --url https://example.com/mcp \
  --bearer-token-env-var MY_MCP_TOKEN

For a custom header name, add the server and then put this in ~/.codex/config.toml:

[mcp_servers.my-server]
url = "https://example.com/mcp"

[mcp_servers.my-server.env_http_headers]
X-My-Header = "MY_MCP_HEADER"

MY_MCP_HEADER is the name of the environment variable containing the secret. That's safer than http_headers, which stores the literal value in the TOML file. Both options are in the current Codex config reference.

One gotcha: -c doesn't solve the onboarding problem here. mcp add validates those overrides, but it doesn't persist them into the new server entry. So for non-Bearer headers, editing TOML is still required until the command gets something like repeatable --header / --header-env options.