---
title: "HTTP MCP 自定义头用 env_http_headers，缺变量会静默不带头"
summary: "左边是头名，右边是环境变量名。http_headers 是字面量，不要把密钥写进仓库。变量缺失或为空时这颗头直接丢掉，请求照样发出去。"
category: mcp
level: intermediate
surfaces: [cli, app, ide]
tags: ["MCP", "env_http_headers", "HTTP", "密钥"]
canonical: /tips/mcp-http-env-headers/
---

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

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

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

```toml
[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：

```toml
[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 占位符不会展开，下面右边是字符串本身，不是密钥：

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

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

## 来源

- [OpenAI · Model Context Protocol](https://learn.chatgpt.com/docs/extend/mcp)
- [openai/codex#5180](https://github.com/openai/codex/issues/5180)
- [openai/codex#5241](https://github.com/openai/codex/issues/5241)