No way to pass environment variables to an MCP `http_headers_helper` (`env_clear` strips everything outside a fixed allowlist)

What version of Codex CLI is running?

0.154.0

What subscription do you have?

N/A

Which model were you using?

No response

What platform is your computer?

No response

What terminal emulator and version are you using (if applicable)?

No response

Codex doctor report

What issue are you seeing?

An HTTP (streamable-http) MCP server configured with http_headers_helper cannot authenticate when the helper needs any environment variable that Codex does not forward to it. Codex spawns the helper with a cleared environment and rebuilds it from two fixed lists, and there is no way (config file, environment variable, or CLI flag) to pass any additional variable to the helper.

// codex-rs/rmcp-client/src/http_headers.rs
.env_clear()
.envs(create_env_for_mcp_server(/*extra_env*/ None, &[])?)

The two forwarded lists are DEFAULT_ENV_VARS (a handful of shell basics) and CUSTOM_CA_ENV_KEYS (TLS CA-certificate paths). Anything else the helper relies on is dropped. Two common cases break as a result:

1. Behind an HTTP proxy: the standard proxy variables (HTTP_PROXY, HTTPS_PROXY, NO_PROXY, ALL_PROXY) are not forwarded, so a helper that makes an outbound request to mint or validate a token cannot route through the proxy.
2. Inside a sandbox or credential broker: tools such as a wrapped CLI are shims that require a non-standard environment marker to run. When that marker is stripped, the CLI refuses to run at all, so the helper fails before it can produce headers.

In every case the helper exits non-zero and MCP initialization fails with MCP HTTP headers helper exited with status exit status: 1 (full error under the reproduction steps below). Running the identical helper directly in the same shell, with the full environment, succeeds. The only difference is Codex's stripped environment.

Notably, Codex already forwards the CA-certificate family so a helper can trust an intercepting proxy's certificate. That establishes that helpers legitimately depend on ambient environment; the gap is that the set is fixed and cannot be extended for the variables a given helper actually needs. Stdio MCP servers already solve this with an env_vars passthrough, but HTTP header helpers have no equivalent.

What steps can reproduce the bug?

Case 1 (proxy):

1. Configure a streamable-http MCP server whose http_headers_helper makes an outbound HTTPS request to fetch or validate a token.
2. Run Codex where outbound traffic is routed through a proxy that the rest of the environment already uses (so HTTP_PROXY and its CA are set in Codex's own environment).
3. Start a session. The helper cannot reach the proxy, exits 1, and initialization fails.

Case 2 (sandbox / broker, no proxy required):

1. Configure a streamable-http MCP server whose http_headers_helper invokes a CLI that only runs inside a sandbox or credential broker and checks a non-standard environment marker to confirm it is inside.
2. Run Codex inside that sandbox, where the marker is present in Codex's own environment.
3. Start a session. Codex's env_clear() drops the marker, the CLI refuses to run, the helper exits 1, and initialization fails:

Error: Failed to start a fresh session through the app server: thread/start failed during TUI bootstrap: thread/start failed: error creating thread: Fatal error: Failed to initialize session: required MCP servers failed to initialize: example_http_server: handshaking with MCP server failed: Send message error Transport [codex_rmcp_client::event_notification_transport::EventNotificationTransport<rmcp::transport::worker::WorkerTransport<rmcp::transport::streamable_http_client::StreamableHttpClientWorker<codex_rmcp_client::http_client_adapter::StreamableHttpClientAdapter>>>] error: Client error: HTTP request failed: MCP HTTP headers helper exited with status exit status: 1, when send initialize request: Send message error Transport [codex_rmcp_client::event_notification_transport::EventNotificationTransport<rmcp::transport::worker::WorkerTransport<rmcp::transport::streamable_http_client::StreamableHttpClientWorker<codex_rmcp_client::http_client_adapter::StreamableHttpClientAdapter>>>] error: Client error: HTTP request failed: MCP HTTP headers helper exited with status exit status: 1, when send initialize request (code -32603)

What is the expected behavior?

A plugin or user can declare the environment variables an HTTP header helper needs, so the helper runs with the same access to the network and sandbox the rest of the session has. Codex already forwards the CA-certificate family for exactly this reason; it should also allow the remaining variables a helper depends on to be forwarded.

Additional information

Root cause

The helper is spawned with a cleared environment at codex-rs/rmcp-client/src/http_headers.rs#L458:

.env_clear()
.envs(create_env_for_mcp_server(/*extra_env*/ None, &[])?)

create_env_for_mcp_server forwards only two sets:

DEFAULT_ENV_VARS (Unix):  HOME, LOGNAME, PATH, SHELL, USER, __CF_USER_TEXT_ENCODING,
                          LANG, LC_ALL, TERM, TMPDIR, TZ
CUSTOM_CA_ENV_KEYS:       11 CA-certificate variables

DEFAULT_ENV_VARS is defined in utils.rs#L162-L175 (the Windows constant differs) and CUSTOM_CA_ENV_KEYS in network-proxy/src/certs.rs#L157-L169.

For the header helper both parameters are empty (None, &[]), so no other variable can be passed. DEFAULT_ENV_VARS contains no proxy variables and no way to add project-specific ones, so both the proxy variables and any sandbox or broker markers a helper needs are dropped even when they are set in Codex's own environment.

Proposed fix

1. Add a per-server env_vars passthrough for HTTP header helpers, mirroring the stdio env_vars field, so a plugin or user can forward exactly the variables their helper requires (proxy variables, sandbox or broker markers, and so on). This is the general fix and the only one that covers environment-specific variables that a built-in list cannot anticipate.
2. Additionally, forward the standard proxy variables (HTTP_PROXY, HTTPS_PROXY, NO_PROXY, ALL_PROXY) by default, alongside the CA-certificate family that already ships. This covers the common corporate-proxy case without configuration, but does not by itself cover non-standard sandbox or broker variables.

Related

#29124 reports the same env_clear() behavior for stdio MCP subprocesses, where the workaround is the stdio env_vars passthrough. This issue is the HTTP http_headers_helper variant, which has no equivalent passthrough.

Start with codex-rs/rmcp-client/src/http_headers.rs around the helper spawn and codex-rs/rmcp-client/src/utils.rs, then inspect the stdio MCP env_vars handling for comparison. Trace the server configuration path and existing tests, if present; done means an HTTP header helper can receive declared variables and the relevant initialization behavior is covered without breaking the existing restricted environment.