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。