mcp_servers.<id>.env
unsetPublished Jul 15, 2026 · Verified against the official config docs
Environment variables handed to a stdio MCP server, written as a TOML map under [mcp_servers.<id>.env]. Unset by default. Codex builds the server's environment from a short whitelist rather than passing your whole shell, so this key, plus the env_vars forwarding list, is how API keys actually reach the server. HTTP servers skip it and use bearer_token_env_var or env_http_headers instead.
Values
| Key | Type | Default |
|---|---|---|
mcp_servers.<id>.env |
map of string to string | unset |
mcp_servers.<id>.env_vars |
array of strings or { name, source } objects |
unset |
env sets variables to literal values. env_vars is a whitelist: you name a variable and Codex forwards its value from the environment Codex itself is running in. String entries default to source = "local"; source = "remote" only applies to executor-backed remote stdio, per the config reference.
The official example from the MCP docs:
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env_vars = ["LOCAL_TOKEN"]
[mcp_servers.context7.env]
MY_ENV_VAR = "MY_ENV_VALUE"codex mcp add <name> --env VAR=VALUE -- <command> writes the env entries for you.
When to change it
- The server needs an API key and you’re fine keeping it in
config.toml: put it under[mcp_servers.<id>.env]. - The key already lives in your shell (exported in
.zshrc, or dropped in by a secret manager): whitelist it withenv_vars = ["MY_TOKEN"]instead of copying the plaintext into a config file. - The server starts fine in your terminal but dies under Codex on Windows or behind a corporate proxy: you likely need to forward system variables yourself. See Gotchas.
Gotchas
Codex does not hand a stdio server your full environment. It builds the child’s env from a short built-in whitelist, which is why a server that runs clean from your terminal can fail inside Codex. Issue #4180 documented Windows startups where only PATH, PATHEXT, USERNAME, USERDOMAIN, USERPROFILE, TEMP, and TMP survived — that one is closed, and #29124 reports proxy and CA-cert variables getting stripped the same way.
The docs don’t say whether $VAR or ${VAR} expands inside env values; issue #7521 is an open ask to document exactly that. Until it’s answered, treat env values as literal strings and use env_vars when the value should come from your shell.
env is stdio-only. A url-based HTTP server takes bearer_token_env_var for the token and env_http_headers for headers filled from environment variables, per the config reference.
Related settings
mcp_serverscovers the parent table:command,args,url, timeouts,enabled.shell_environment_policycontrols the same problem for Codex’s own shell sessions, separate from MCP child processes.- Server failing at launch rather than missing a key? Check /errors/.