---
title: "动态 MCP 头用 http_headers_helper，不要把令牌写进仓库"
summary: "本机 HTTP MCP 才支持。命令每条连接跑一次，stdout 必须是 JSON 头。显式 bearer / OAuth 压过 helper 的 Authorization。"
category: mcp
level: advanced
surfaces: [cli, app, ide]
tags: ["MCP", "http_headers_helper", "鉴权"]
canonical: /tips/http-headers-helper/
---

# 动态 MCP 头用 http_headers_helper，不要把令牌写进仓库

本机 HTTP MCP 才支持。命令每条连接跑一次，stdout 必须是 JSON 头。显式 bearer / OAuth 压过 helper 的 Authorization。

短期令牌、公司网关票据不要写进 `http_headers`。给本机 Streamable HTTP 配一条命令：

```toml
[mcp_servers.docs]
url = "https://mcp.example.com/mcp"
http_headers_helper = "python3 /home/you/.codex/mcp-headers.py"
```

脚本往 stdout 打一行 JSON 对象，例如 `{"X-Auth": "temporary-token"}`。Codex 在这条连接上缓存结果。同源 POST 返回 `401` / `403` 时会再跑一次；只有头真的变了才重试。OAuth 报权限不够的 `403` **不会**刷新 helper。

约束：

- 只给本机环境的 HTTP MCP。stdio 不行，远端执行器上的连接也不行
- 显式 `bearer_token_env_var` 和已登录 OAuth 优先于 helper 给出的 `Authorization`
- 保留头、重复头会被拒；输出和执行有上限
- `codex mcp list` / `codex mcp get` 会把命令打码，不要靠这两条命令排错脚本路径

没有凭据来源时仍可能匿名连上。要走 OAuth 另跑 `codex mcp login docs`。改完用真实工具调用验证，不要只看 list。

## 来源

- [OpenAI · Model Context Protocol](https://learn.chatgpt.com/docs/extend/mcp)