加个 MCP 服务器又去手改 JSON？Claude Code 自带的 mcp 命令早就够用了

给 Claude Code 加一个 MCP 服务器，很多人的第一反应还是打开 .mcp.json，照着别人的示例一段一段抄：command 写哪个、args 放几个、env 里的密钥怎么塞、type 到底填 stdio 还是 http——抄完还得记住一件事：你抄的这份，VS Code 那边根节点叫 servers 不叫 mcpServers，粘过去直接不生效。这个来回，其实 Claude Code 早就用一条 claude mcp 命令收掉了。

结论先放前面：MCP 服务器不用手写配置文件，claude mcp add 帮你把 transport、路径、环境变量、作用域一次性写对；团队共享用 --scope project，密钥用 ${VAR} 展开，本地实验用默认的 local scope。 下面把这套命令拆开讲。

一条命令加服务器，transport 决定写法

claude mcp add 是主入口，写法由 transport 决定。

最常见的远程 HTTP 服务器（云服务基本都走这个）：

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

需要带鉴权 header：

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ 
  --header "Authorization: Bearer $GITHUB_PAT"

本地进程类（需要访问文件系统、数据库的）用 stdio，注意那个 -- 分隔符是必须的——它后面的一切都是要执行的命令，原样传给服务器：

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub 
  --dsn "postgresql://readonly:***@localhost:5432/mydb"

传环境变量用 --env KEY=value。这里有个反直觉的坑：--env 和服务器名之间至少要隔一个别的参数，否则 CLI 会把服务器名当成另一组 env 键值对，直接报错。

如果你手里就是一段现成的 JSON 配置（很多 MCP 文档直接给 JSON），不用手动拆：

claude mcp add-json local-weather 
  '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"]}'

scope 三档，决定「谁能看到」

--scope 是这个命令最值钱的地方，它回答了「这份配置放哪、团队要不要共享、密钥会不会进 Git」：

• local（默认）：只在你当前这个项目里生效，存在 ~/.claude.json 里对应项目的路径下，别人看不到。适合个人实验、含敏感凭据的服务器。
• project：把配置写进项目根目录的 .mcp.json，这个文件是设计来提交到版本库的，团队每个人 clone 下来就自动拿到同一套 MCP 工具。加它只要：

claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

生成的 .mcp.json 长这样：

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://mcp.paypal.com/mcp"
    }
  }
}

出于安全，Claude Code 在第一次使用来自 .mcp.json 的 project 服务器时会弹窗要你批准。想重置这些批准选择，用 claude mcp reset-project-choices。

• user：存在 ~/.claude.json 里，对你机器上所有项目生效，但仍然是你私人的。适合跨项目都要用的开发工具。

同名服务器在多个 scope 都定义时，local > project > user，最具体的那一份赢，而且整个 server 条目取自优先级最高的来源，字段不会跨 scope 合并。

密钥不进 Git：靠 ${VAR} 展开

.mcp.json 是要提交的，所以绝对不能把 token 写死。Claude Code 支持在 command、args、url、headers 里做环境变量展开：

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

${VAR} 展开成变量的值，${VAR:-default} 在没设置时用默认值。必需变量缺失且没有默认值时会直接解析失败——这是好事，它响亮地报错，而不是悄悄连到错误的地址去。

日常管理：list / get / remove

配好之后不用记，三条命令管全场：

claude mcp list        # 列出所有已配置的服务器
claude mcp get sentry  # 看单个服务器的完整配置
claude mcp remove sentry  # 删掉它

在会话内部，用 /mcp 看的是实时连接状态和每个服务器暴露的工具数量——比 list 更接近「现在到底连上没有」。服务器状态分五种：connected（连上且工具可用）、pending（正在重连）、needs-auth（需要走 OAuth 登录）、failed（失败，有错误信息）、disabled（本次会话被手动关了）。OAuth 类的服务器加完先跑 /mcp 完成浏览器登录，token 会安全存储并自动刷新。

一个必须记住的跨工具坑

同一个 MCP 概念，各家客户端的配置根节点并不统一。VS Code（GitHub Copilot）用的是 servers，而不是 mcpServers——它是主流客户端里唯一这么干的。很多人从 Cursor 或 Claude Desktop 复制一段配置粘进 .vscode/mcp.json，发现工具不出现，就是卡在这里。环境变量语法也各写各的：Claude Code 是 ${VAR}，Cursor 是 ${env:VAR}，没有统一标准，换客户端时务必逐个核对。

下一步可以做的

1. 先跑 claude mcp list 看看你现在到底配了哪些，把重复的、废弃的（type: "sse" 已被弃用，能换 http 就换）清理掉。
2. 团队要共用的服务器，用 --scope project 重新加一遍，把生成的 .mcp.json 提交进仓库，密钥全部换成 ${VAR}。
3. Windows 原生环境（非 WSL）跑 stdio 服务器时，记得用 cmd /c 包一层 npx，否则进程经常起不来。

MCP 的复杂度不在协议本身，而在「怎么配、配给谁看、密钥怎么放」。这三件事，claude mcp 一条命令加一个 scope 参数，就把它从手抄 JSON 变成了工程化操作——该用起来就用起来。