第 6 章 · 02 配置管理:CLI、作用域与 JSON

第 6 章 · 02 配置管理:CLI、作用域与 JSON

本节摘要:接入 MCP 有三条路:CLI 命令、项目级 .mcp.json、claude mcp add-json 脚本化导入。配置按作用域存放——local(仅你,默认)、project(随仓库共享,首次使用需审批)、user(跨项目)。.mcp.json 支持 ${VAR} / ${VAR:-default} 环境变量展开,凭据永远走环境变量而非写死。OAuth 服务器走 claude mcp login 交互认证;claude mcp serve 还能把 Claude Code 自己变成 MCP 服务器。

学习目标

阅读完本节,你应当能够:

1. 说出三种配置作用域、各自存放位置与共享对象。
2. 用 CLI 完成 MCP 服务器的添加、列出、查看、移除、登录/登出。
3. 手写一份 .mcp.json(含 type/url 或 command/args/env),并正确使用 ${VAR} 与 ${VAR:-default}。
4. 说出团队共享 MCP 时 project 作用域的审批机制,以及 claude mcp serve 的用途。

一、三种作用域:配置放哪里

MCP 配置按作用域存放,决定了谁看得见、要不要审批:

命名注记:旧版里 local 叫 project、user 叫 global,看到老文档别晕。--scope 可简写 -s,省略时默认 local:

# project 作用域——写入 .mcp.json,团队共享
claude mcp add --scope project --transport http github https://api.github.com/mcp

# user 作用域——每个项目都能用
claude mcp add --scope user --transport stdio memory -- npx @modelcontextprotocol/server-memory
​

project 作用域的审批机制:团队成员第一次使用项目 MCP 时会看到审批弹窗;在不信任的工作区,仓库通过已提交的 .claude/settings.json 自我批准的服务器不会被自动拉起——claude mcp list/get 显示 ⏸ Pending approval,直到你接受信任对话框;且 enableAllProjectMcpServers 在不信任目录下被忽略(v2.1.196+)。

去重规则:同一服务器在多个作用域重复定义时,local 优先——你可以用本地配置覆盖项目/用户级配置,而不用改共享文件。

二、CLI 命令族:管理 MCP 的主入口

# 添加 HTTP 服务器
claude mcp add --transport http github https://api.github.com/mcp

# 添加本地 stdio 服务器
claude mcp add --transport stdio database -- npx @company/db-server

# 列出所有服务器(失败项会显示 HTTP 状态码与错误文本,v2.1.219+)
claude mcp list

# 查看单个服务器详情
claude mcp get github

# 移除服务器
claude mcp remove github

# 重置项目相关的审批选择
claude mcp reset-project-choices

# 认证/登出 MCP 服务器(非交互式 OAuth,v2.1.186+)
claude mcp login github
claude mcp logout github

# 从 Claude Desktop 导入配置
claude mcp add-from-claude-desktop

# 从 JSON 片段添加(适合脚本化部署)
claude mcp add-json events-server '{"type":"stdio","command":"npx","args":["@modelcontextprotocol/server-events"]}'
​

claude mcp login/logout 是 /mcp 菜单里 OAuth 流程的非交互等价物;SSH 或无头会话中加 --no-browser 可把 OAuth 流程改走 stdin 完成。

命名别名:JSON 配置(.mcp.json、~/.claude.json、add-json)里,type 字段接受 streamable-http 作为 http 的别名——MCP 规范本身就叫 streamable-http,所以从服务器官方文档复制配置时不用改。

三、JSON 语法与环境变量展开

项目共享推荐直接写 .mcp.json:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.github.com/mcp"
    }
  }
}
​

配置支持环境变量展开,且带默认值回退,可用字段:command、args、env、url、headers:

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}",
        "X-Custom-Header": "${CUSTOM_HEADER:-default-value}"
      }
    },
    "local-server": {
      "command": "${MCP_BIN_PATH:-npx}",
      "args": ["${MCP_PACKAGE:-@company/mcp-server}"],
      "env": {
        "DB_URL": "${DATABASE_URL:-postgresql://localhost/dev}"
      }
    }
  }
}
​

两种写法(运行时展开):

• ${VAR}:读环境变量,未设置则报错。
• ${VAR:-default}:未设置时用默认值。

安全规则:凭据永远不进配置文件。把 token 放环境变量(如 export GITHUB_TOKEN="..."),配置里只写 ${GITHUB_TOKEN}。.mcp.json 可以进 git,但秘密必须留在环境里。

四、OAuth 2.0 认证

对需要 OAuth 的服务器,Claude Code 处理完整认证流程:

# 交互式流程:连上后触发浏览器 OAuth
claude mcp add --transport http my-service https://my-service.example.com/mcp

# 非交互式:预置凭据
claude mcp add --transport http my-service https://my-service.example.com/mcp \
  --client-id "your-client-id" \
  --client-secret "your-client-secret" \
  --callback-port 8080
​

特性速记:交互式 OAuth 用 /mcp 触发;Notion/Stripe 等常见服务有内置 OAuth 客户端(v2.1.30+);token 存入系统钥匙串;支持特权操作的阶梯认证(step-up auth);oauth.authServerMetadataUrl 可覆盖 OAuth 元数据发现(要求 https,v2.1.64+)。若服务器的标准元数据端点不可用但有正常 OIDC 端点,可以指向它:

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration"
      }
    }
  }
}
​

两个易踩点(v2.1.193+):启动时 Claude Code 会列出仍需认证的服务器——某个服务器静默不工作,先查这个清单;自定义 headersHelper 会在收到 401/403 时自动重新调用,动态刷新凭据,无需手动重连。

五、claude mcp serve:反向接线

Claude Code 自己也能当 MCP 服务器,让外部工具、编辑器、自动化系统通过标准 MCP 协议调用它:

# 以 stdio 启动 Claude Code 作为 MCP 服务器
claude mcp serve
​

另一个 Claude Code 实例可以把前一个接进来——构建"一个 Claude 编排另一个 Claude"的多智能体工作流:

claude mcp add --transport stdio claude-agent -- claude mcp serve
​

小结

配置 MCP 记住"三条路、三种作用域、一个原则":CLI 适合单机管理,.mcp.json 适合团队共享(首次使用需审批,local 覆盖 project),add-json 适合脚本部署。作用域决定共享面,环境变量展开让配置无秘密,claude mcp login 处理 OAuth,serve 反向接线。接进来之后,下一节处理"权限怎么给、提示词怎么用、出问题怎么排查"。

下一节预告:第 3 节讲工具权限三档、MCP Prompts 变斜杠命令、资源引用与故障排查。