教程2026-11-19 · 智涌AI

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

Claude Code MCP 令牌安全配置教程头图:左侧 MCP 令牌安全配法大字和 v2.1.327、headersHelper 10 秒时限、3 种场景配法数据卡,右侧终端演示用 read 读入令牌、printf 管道给 claude mcp add-json github -,claude mcp get 只显示变量名,grep 明文令牌结果为 0

给 Claude Code 接 GitHub、数据库这类要鉴权的 MCP 服务器时,官方文档里最常见的写法是把令牌直接拼进 claude mcp add --header "Authorization: Bearer …"。这样写省事,可令牌会留在 shell 历史里,命令运行期间别人用 ps 也看得到。北京时间 11 月 18 日发布的 v2.1.327 加了 claude mcp add-json <name> -,可以从标准输入读配置。这篇按官方文档,把个人用、团队共享、短期令牌三种场景的配法和检查办法讲清楚。

前置条件

令牌会落在四个地方,每种配法管的范围不同

几种写法分别会把令牌留在哪里:

配法命令参数 / 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 权限自查那篇的办法,先轮换令牌再清理。

常见坑

完成标准

v2.1.327 的其他改动(/status 列出坏掉的 skill 和永远不会命中的 hook 等)见站内快讯 Claude Code 2.1.327。

最后

打开 ~/.claude.json 搜一下 Bearer,每找到一个明文令牌,就按第一步换成变量引用,再按第四步检查。

关注公众号「智涌AI速递」

每天的 AI 快讯、实用教程和 AI项目实测,也会同步发到微信公众号。在微信里搜索「智涌AI速递」就能关注;不用微信的话,可以用 RSS 订阅本站。