HTTP MCP 自定义头用 env_http_headers,缺变量会静默不带头

左边是头名,右边是环境变量名。http_headers 是字面量,不要把密钥写进仓库。变量缺失或为空时这颗头直接丢掉,请求照样发出去。

服务器要的是 X-Api-Key 这类自定义头,而不是 Authorization: Bearer 时,用 env_http_headers。左边是头名,右边是启动 Codex 的进程里的变量

[mcp_servers.docs]
url = "https://mcp.example.com/mcp"
enabled = true

[mcp_servers.docs.env_http_headers]
X-Api-Key = "DOCS_API_KEY"

http_headers 写入的是字面量。下面这样会把密钥提交进 config,项目层文件还可能进 Git:

[mcp_servers.docs.http_headers]
X-Api-Key = "sk-live-do-not-commit"

Bearer 继续用 bearer_token_env_var,不要拿这张表去填 Authorization。维护者说明可以省略 Bearer 键,只配自定义头。不要为了自定义头去跑 codex mcp login docs

变量缺失或值为空时,这颗头会被静默丢掉,请求照样发出去。codex mcp get docs 仍可能列出 env_http_headers,工具却 401 或直接消失。从已经 export DOCS_API_KEY 的终端启动;Dock / 开始菜单打开的桌面没有 zshrc。改完彻底退出再开新进程。

TOML 占位符不会展开,下面右边是字符串本身,不是密钥:

[mcp_servers.docs.env_http_headers]
X-Api-Key = "${DOCS_API_KEY}"

stdio 的 env_vars 对 HTTP 无效。会过期、要每条连接刷新的票用 http_headers_helper

来源