{"record":{"id":"4c9c69ca3be04605","repo":"openai/codex","slug":"environment-variable-env-var-for-mcp-server-se-4c9c69","errorCode":null,"errorMessage":"Environment variable {env_var} for MCP server '{server_name}' is not set","messagePattern":"Environment variable (.+?) for MCP server '(.+?)' is not set","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"codex-rs/codex-mcp/src/rmcp_client.rs","lineNumber":849,"sourceCode":"fn resolve_bearer_token(\n    server_name: &str,\n    bearer_token_env_var: Option<&str>,\n) -> Result<Option<String>> {\n    let Some(env_var) = bearer_token_env_var else {\n        return Ok(None);\n    };\n\n    match env::var(env_var) {\n        Ok(value) => {\n            if value.is_empty() {\n                Err(anyhow!(\n                    \"Environment variable {env_var} for MCP server '{server_name}' is empty\"\n                ))\n            } else {\n                Ok(Some(value))\n            }\n        }\n        Err(env::VarError::NotPresent) => Err(anyhow!(\n            \"Environment variable {env_var} for MCP server '{server_name}' is not set\"\n        )),\n        Err(env::VarError::NotUnicode(_)) => Err(anyhow!(\n            \"Environment variable {env_var} for MCP server '{server_name}' contains invalid Unicode\"\n        )),\n    }\n}\n\nfn validate_mcp_server_name(server_name: &str) -> Result<()> {\n    let re = regex_lite::Regex::new(r\"^[a-zA-Z0-9_-]+$\")?;\n    if !re.is_match(server_name) {\n        return Err(anyhow!(\n            \"Invalid MCP server name '{server_name}': must match pattern {pattern}\",\n            pattern = re.as_str()\n        ));\n    }\n    Ok(())\n}","sourceCodeStart":831,"sourceCodeEnd":867,"githubUrl":"https://github.com/openai/codex/blob/339751715c64496cb86246bfb3935f40e309dd3d/codex-rs/codex-mcp/src/rmcp_client.rs#L831-L867","documentation":"Starting an MCP server configured with bearer_token_env_var, but std::env::var returned VarError::NotPresent: the named variable does not exist in the Codex process environment at all. The bearer token cannot be constructed, so that server's startup aborts with an error naming both the variable and the server.","triggerScenarios":"config.toml [mcp_servers.NAME] with bearer_token_env_var = \"FOO_TOKEN\" where FOO_TOKEN was never exported in the environment of the Codex process: launched from a GUI/desktop app that skips shell profiles, from a different shell/session than where the token was set, via env -i codex, or under sudo which strips the environment.","commonSituations":"Token set in an interactive shell but Codex launched by systemd/launchd/Docker; .env file not loaded by the launcher; secret kept in a password manager but never exported; variable renamed in config (FOO_TOKEN vs FOO_MCP_TOKEN).","solutions":["Export the variable in the environment that actually launches Codex: export FOO_TOKEN=<value>, then restart Codex","Verify presence in the exact execution context with printenv FOO_TOKEN (CI step, container exec, service unit)","If Codex is started by a desktop app or service, set the variable where that launcher reads it (launchd plist, systemd Environment=, docker -e)","If the token should be resolved on the remote executor, configure it there instead of locally"],"exampleFix":"# before: token lives only in an interactive shell\ncodex   # FOO_TOKEN unset here\n\n# after\nexport FOO_TOKEN=\"$(pass show mcp/foo-token)\"\ncodex","handlingStrategy":"validation","validationCode":"# Preflight: every bearer_token_env_var in config must exist\nfor var in $(grep -oP 'bearer_token_env_var\\s*=\\s*\"\\K[^\"]+' ~/.codex/config.toml); do\n  if [ -z \"${!var:-}\" ]; then echo \"missing env: $var\" >&2; exit 1; fi\ndone","typeGuard":null,"tryCatchPattern":"match env::var(env_var) {\n    Err(env::VarError::NotPresent) => { /* prompt/login flow or a clear setup message */ }\n    other => other,\n}","preventionTips":["Centralize MCP secrets in one sourced env file referenced by every launcher (shell, service, container)","Debug with printenv VAR inside the same execution context Codex runs in","Keep the variable name identical in config and your secret store","Run a config preflight in CI that fails when a declared token env is absent"],"tags":["mcp","codex","environment-variable","bearer-token","authentication","missing-secret"],"backgroundTag":"missing-environment-variable","analyzedSha":"339751715c64496cb86246bfb3935f40e309dd3d","analyzedAt":"2026-08-25T05:35:09.876Z","schemaVersion":2},"datasetVersion":"2026-08-25T06:17:31.827Z"}