MCP 令牌别写进命令行:Claude Code 三种安全配法

给 Claude Code 接 GitHub、数据库这类要鉴权的 MCP 服务器时,官方文档里最常见的写法是把令牌直接拼进 claude mcp add --header "Authorization: Bearer …"。这样写省事,可令牌会留在 shell 历史里,命令运行期间别人用 ps 也看得到。北京时间 11 月 18 日发布的 v2.1.327 加了 claude mcp add-json <name> -,可以从标准输入读配置。这篇按官方文档,把个人用、团队共享、短期令牌三种场景的配法和检查办法讲清楚。
前置条件
- Claude Code v2.1.327 或更新版本。先跑
claude --version看版本,旧了就claude update。 - 一个需要令牌的远程 MCP 服务器。下文用官方文档里的 GitHub 示例:地址
https://api.githubcopilot.com/mcp/,鉴权用 GitHub 细粒度个人访问令牌(PAT),只勾你要让 Claude 访问的仓库。 - 能用 bash 或 zsh 的普通终端。
add-json -在 Claude Code 会话内部用不了,要在会话外执行。
令牌会落在四个地方,每种配法管的范围不同
几种写法分别会把令牌留在哪里:
| 配法 | 命令参数 / shell 历史 | ~/.claude.json | 仓库里的 .mcp.json |
|---|---|---|---|
add --header 直接写令牌 | 有 | 有(明文) | 加 --scope project 时有 |
add-json - 从标准输入传令牌 | 没有 | 有(明文) | 没有(默认 local 作用域) |
add-json - 传 ${VAR} 引用 | 没有 | 只有变量名 | 没有 |
.mcp.json 写 ${VAR} | 没有 | 没有 | 只有变量名 |
headersHelper 运行时生成 | 没有 | 只有脚本路径 | 只有脚本路径 |
local 和 user 作用域都存在 ~/.claude.json,project 作用域存在项目根目录的 .mcp.json,后者一般会提交进 git。这三处配置文件都支持 ${VAR} 和 ${VAR:-默认值} 展开,可展开的字段有 command、args、env、url、headers。
用标准输入传明文令牌,命令行和历史记录里看不到了,本机的 Claude 配置文件里存的仍是明文。
第一步:个人用,从标准输入添加
在普通终端里先把令牌读进一个临时变量,输入时不回显:
read -rs MY_GH_MCP_PAT
printf '{"type":"http","url":"https://api.githubcopilot.com/mcp/","headers":{"Authorization":"Bearer %s"}}' "$MY_GH_MCP_PAT" \
| claude mcp add-json github -
unset MY_GH_MCP_PAT
bash 的 printf 是内建命令,不会起新进程,令牌也就不会出现在进程列表里;历史记录里只有 $MY_GH_MCP_PAT 这几个字。成功后会打印一行 Added ...。
这样做令牌还是会以明文存进 ~/.claude.json。想让它连这个文件都不进,把 JSON 里的令牌换成变量引用,用单引号防止 shell 提前展开:
echo '{"type":"http","url":"https://api.githubcopilot.com/mcp/","headers":{"Authorization":"Bearer ${MY_GH_MCP_PAT}"}}' \
| claude mcp add-json github -
之后在 shell 配置或密钥管理工具里导出 MY_GH_MCP_PAT,再启动 Claude Code。
第二步:团队共享,.mcp.json 只写变量名
要让全组用同一份配置,把服务器写进项目根目录的 .mcp.json,令牌位置留成变量:
{
"mcpServers": {
"api-server": {
"type": "http",
"url": "${API_BASE_URL:-https://api.example.com}/mcp",
"headers": {
"Authorization": "Bearer ${API_KEY}"
}
}
}
}
每个人在自己机器上设 API_KEY,文件可以放心提交。交互会话里第一次加载项目级服务器时,Claude Code 会先弹窗请你批准;要重置这些选择,跑 claude mcp reset-project-choices。
远程服务器的 url 和 headers 里,Claude Code 会把一批凭据变量当成空值,ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN、AWS_BEARER_TOKEN_BEDROCK、NPM_TOKEN、HTTPS_PROXY 都在其中,写了 :-默认值 也没用。这是为了防止别人仓库里的 .mcp.json 或插件把你的 Claude 和云厂商凭据发给它指定的服务器。所以给 MCP 用的令牌要单独起名,比如 MY_GH_MCP_PAT。
第三步:短期令牌,交给 headersHelper
公司内网用 SSO、Kerberos 或者几小时就过期的令牌时,可以让 Claude Code 每次连接前跑一条命令拿请求头:
{
"mcpServers": {
"internal-api": {
"type": "http",
"url": "https://mcp.internal.example.com",
"headersHelper": "/opt/bin/get-mcp-auth-headers.sh"
}
}
}
脚本要往标准输出写一个键值都是字符串的 JSON 对象,比如 {"Authorization": "Bearer xxx"},10 秒内不返回就算失败。Claude Code 在会话开始和重连时都会重新运行它,不做缓存;工具调用遇到 401 或 403,会重跑一次脚本、重连后再试一次。脚本运行时能拿到 CLAUDE_CODE_MCP_SERVER_NAME 和 CLAUDE_CODE_MCP_SERVER_URL,一个脚本可以服务多个服务器。
写在项目 .mcp.json 或 local 作用域里的 helper,要等你在信任对话框里信任了该项目目录才会运行,信任上级目录不算。没信任之前,服务器只带静态 headers 去连。
第四步:检查配置里到底存了什么
claude mcp list
claude mcp get github
这两个命令和会话里的 /mcp 详情页显示 ${VAR} 时只显示变量名,不显示展开值。连接失败时,claude mcp get 的 Issue: 行会给出 HTTP 状态码和服务器返回的错误文字,像凭据的内容会被打码。配置有问题时还会给出警告:变量没设且没默认值,会点名是哪个变量;粘贴令牌带了换行,会提示 Leading or trailing whitespace in: headers.Authorization,但不会替你删掉。
最后用 grep 确认明文令牌已经不在配置文件里:
grep -c "github_pat_" ~/.claude.json .mcp.json 2>/dev/null
细粒度 PAT 以 github_pat_ 开头,两处都应该是 0。之前已经写进过 git 历史的,按站内 Claude Code 权限自查那篇的办法,先轮换令牌再清理。
常见坑
- 在 Claude 里让它替你执行
add-json -。发布说明写明这个用法在 Claude Code 会话内不可用,要退到普通终端里跑。 - 用双引号包 JSON。
"${MY_GH_MCP_PAT}"会被 shell 先展开,令牌照样进了~/.claude.json。要存变量引用,就用单引号。 - 直接复用
ANTHROPIC_API_KEY之类的变量名。远程服务器的url和headers会把它读成空值,服务器回 401,连接失败。要确认是不是这个原因,用claude --debug-file /tmp/claude-debug.log启动,在日志里搜never expanded toward a remote server。 - 把变量设成空字符串。空字符串也算已设置,
${VAR:-默认值}会展开成空,不会用默认值。想用默认值就unset。 - 从 Claude Desktop 抄来的配置只有
url没有type。Claude Code 会把它当成 stdio 服务器并跳过,要补"type": "http"。另外别把外层的mcpServers包一起传给add-json。
完成标准
claude --version不低于 2.1.327,history | grep -i bearer找不到带令牌的命令。claude mcp get github显示已连接,请求头里是${MY_GH_MCP_PAT}这样的变量名。- 提交进仓库的
.mcp.json只有变量名或 helper 路径,grep不到明文令牌。 claude mcp list没有缺失变量或多余空白的警告。
v2.1.327 的其他改动(/status 列出坏掉的 skill 和永远不会命中的 hook 等)见站内快讯 Claude Code 2.1.327。
最后
打开 ~/.claude.json 搜一下 Bearer,每找到一个明文令牌,就按第一步换成变量引用,再按第四步检查。