在 CLI Agent 里挂 MCP server

在 CLI Agent 里挂 MCP server

基础概念

在终端里跑 AI Agent，绕不开一个高频问题：怎么让它访问外部工具？ 你想让 Claude Code 查 Sentry 错误、读 PostgreSQL 表、提 GitHub PR——这些事要么靠 shell 命令现凑（脆弱、上下文乱），要么走 MCP（Model Context Protocol） 把外部能力以"标准协议"的方式注册进来。后者就是这张卡要讲的事。

CLI Agent 接 MCP 和 Claude Desktop 接 MCP 的本质一致——都是 Host 启一个 Client、Client 连一个 Server——但 CLI 端的配置入口完全不同：

CLI 端的两种挂载方式不是对立的——claude mcp add 在底层就是写文件，写到哪个文件由 --scope 决定。命令式适合个人快速试，配置式（特别是 project 作用域的 .mcp.json）适合团队共享和版本管理。

核心要素

从添加到调用的完整链路

注意中间那段循环——Server 进程是在 CLI 启动时一次性拉起的。如果是 stdio Server，它就跟着 claude 进程的生命周期走，CLI 退出 Server 也跟着死；如果是 HTTP Server，断线时 Claude Code 会用指数退避重连最多 5 次，5 次失败后在 /mcp 里标 failed，需要手动 retry。stdio 进程崩了不会自动重启，要重新进会话。

基础用法

入口一：claude mcp add 命令式

最常用、最快的方式。一条命令搞定，比手动编辑 JSON 省心。语法：

# 基本形式（注意所有 flag 必须在 name 之前，stdio 启动命令在 -- 之后）
claude mcp add [options] <name> [-- <command> [args...]]

挂一个 stdio Server（本地 PostgreSQL）

# 拉起一个本地 dbhub 进程，连只读 Postgres
claude mcp add db --transport stdio \
  --env LOG_LEVEL=info \
  -- npx -y @bytebase/dbhub --dsn "postgresql://readonly:pass@localhost:5432/analytics"

# 验证
claude mcp list
# 应该输出：db: npx -y @bytebase/dbhub --dsn ...

几个关键点：

• --transport stdio 是默认值，可省略，但显式写出来更清楚。
• --env KEY=VAL 把环境变量塞给子进程，可重复多次。
• -- 是分隔符，左边是 Claude Code 自己的 flag，右边是要 spawn 的命令本体。漏掉它，Claude 会把 npx 当成 claude mcp add 的参数，报奇怪的错。
• Server 名字（这里是 db）是你自己起的别名，后面 claude mcp get db / claude mcp remove db 都用这个名字。

挂一个远程 HTTP Server（Sentry，带 OAuth）

# 远程 server 一行命令，不需要写 token
claude mcp add sentry --transport http https://mcp.sentry.dev/mcp

# 进对话授权
claude
# 在对话里输入：
# /mcp
# 选 sentry → Authenticate → 浏览器弹 OAuth 页 → 授权完成

--transport http 是当前推荐的远程协议；--transport sse 还能用但官方已标 deprecated，新接入直接选 http。

如果远程 Server 不走 OAuth，要手填 header：

claude mcp add my-internal-api --transport http https://api.internal.com/mcp \
  --header "Authorization: Bearer $INTERNAL_TOKEN" \
  --header "X-Tenant: acme"

三种作用域怎么选

# 默认：local（只在当前项目可见，写到 ~/.claude.json 的 projects.<当前路径>.mcpServers）
claude mcp add stripe --transport http https://mcp.stripe.com

# project：写到项目根目录的 .mcp.json，进 Git，团队共享
claude mcp add paypal --scope project --transport http https://mcp.paypal.com/mcp

# user：写到 ~/.claude.json 的 user 段，自己所有项目都生效
claude mcp add github --scope user --transport http https://api.githubcopilot.com/mcp/

优先级 local > project > user，同名 Server 高优先级覆盖低优先级。

管理命令一览

claude mcp list             # 列所有 Server
claude mcp get sentry       # 看某个 Server 详情（含 OAuth 状态）
claude mcp remove sentry    # 删除
claude mcp reset-project-choices  # 重置 .mcp.json 的批准状态
claude mcp serve            # 把 Claude Code 自己当 Server，供别的 Host 调
claude mcp add-from-claude-desktop  # 从 Desktop 一键导入（仅 macOS / WSL）

入口二：直接编辑配置文件

当你需要团队共享、或者要写复杂的 env 变量展开时，编辑文件比命令式更直观。

团队共享的 .mcp.json（项目根目录）

{
  "mcpServers": {
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    },
    "internal-api": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    },
    "db-readonly": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@bytebase/dbhub",
        "--dsn",
        "${DATABASE_URL}"
      ],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

这个文件可以、也应该提交到 Git，团队成员 clone 仓库后第一次启 Claude Code 会弹确认框（防止恶意仓库塞 Server 进来），同意后就跟自己配的没区别。

环境变量展开规则：

• ${VAR} —— 取环境变量 VAR 的值，未设置则解析失败，整个 .mcp.json 都加载不了。
• ${VAR:-default} —— VAR 没设置时回退到 default。
• 可以出现的字段：command、args 中的每一项、env 的 value、url、headers 的 value。

写完团队 Wiki 里告诉每个人：export API_KEY=xxx、export DATABASE_URL=xxx，剩下的事 Claude Code 替大家管。绝对不要把 token 直接写进 .mcp.json，否则进 Git 历史就洗不掉。

个人作用域的 ~/.claude.json

local 和 user 作用域都落在 ~/.claude.json，结构大致是：

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  },
  "projects": {
    "/Users/me/work/project-a": {
      "mcpServers": {
        "stripe": {
          "type": "http",
          "url": "https://mcp.stripe.com"
        }
      }
    }
  }
}

顶层 mcpServers 是 user 作用域（所有项目可见）；projects.<绝对路径>.mcpServers 是 local 作用域（仅那个目录可见）。一般不建议手改这个文件——用 claude mcp add --scope user/local 让 Claude Code 自己写更稳。

进阶：claude mcp add-json 一次塞一坨配置

复杂 server 可以直接传 JSON：

claude mcp add-json weather '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer abc"}}'

适合脚本批量初始化场景。

验证：进对话敲 /mcp

$ claude
> /mcp

✔ sentry        connected   2 tools, OAuth authorized
✔ db-readonly   connected   8 tools
○ internal-api  pending     reconnecting (attempt 2/5)
✗ legacy-sse    failed      Connection refused. [r]etry [d]isable

> 看看 Sentry 最近 24h 错误最多的 endpoint
[调用工具：sentry.list_errors，参数：{ "lookback": "24h" }]
最近 24 小时报错最多的是 /api/checkout，共 1287 次……

绿色勾 = 已连上、工具就绪；圆圈 = 重连中；红叉 = 5 次都失败、需手动 retry。

同类工具对比

核心区别一句话：

• Claude Code：命令式入口最完善，三级作用域 + 团队共享 .mcp.json 是它的招牌，纯命令行重度用户首选。
• Cursor / VS Code：作为 IDE 的 MCP 接入，UI 配置友好，但只有"项目 + 全局"两级，且 VS Code 用 servers 字段跟其他三家不一致，迁移配置时容易踩坑。
• Claude Desktop：MCP 支持最全（含 Sampling、Elicitation），但配置必须手动改 JSON、改完必须重启，团队共享几乎没法做。

常见误区

优劣势分析

命令式 claude mcp add

配置式（直接编辑 .mcp.json / ~/.claude.json）

实战配比：个人快速试用走命令式（local 作用域），团队稳定用的工具走 .mcp.json（project 作用域 + 占位符），自己跨项目通用的工具走命令式（--scope user）。

思考题

{
  "mcpServers": {
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${SENTRY_TOKEN}"
      }
    }
  }
}

{
  "mcpServers": {
    "my-python-server": {
      "type": "stdio",
      "command": "python",
      "args": [
        "${PROJECT_ROOT:-.}/scripts/server.py",
        "--mode",
        "production"
      ],
      "env": {
        "OPENAI_API_KEY": "${OPENAI_API_KEY}",
        "LOG_LEVEL": "${LOG_LEVEL:-info}"
      }
    }
  }
}

claude mcp add my-server --transport stdio -- npx -y @some/package
# Claude Code 内部会执行 spawn("npx", ["-y", "@some/package"])
# Windows: ENOENT，没法直接 spawn .cmd 文件

claude mcp add my-server --transport stdio -- cmd /c npx -y @some/package
# 内部变成 spawn("cmd", ["/c", "npx", "-y", "@some/package"])
# 由 cmd.exe 解释 npx.cmd，工作正常

{
  "mcpServers": {
    "my-server": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@some/package"]
    }
  }
}

参考资料

1. Claude Code 官方 MCP 接入文档：https://code.claude.com/docs/en/mcp（查询日期 2026-04-22）
2. MCP 官方 - 连接本地 Server：https://modelcontextprotocol.io/docs/develop/connect-local-servers（查询日期 2026-04-22）
3. MCP 官方 - 连接远程 Server：https://modelcontextprotocol.io/docs/develop/connect-remote-servers（查询日期 2026-04-22）
4. MCP 协议规范最新版（2025-06-18）：https://modelcontextprotocol.io/specification/latest
5. Claude Code GitHub 仓库（issues / release notes）：https://github.com/anthropics/claude-code
6. VS Code MCP 配置参考（注意根字段是 servers）：https://code.visualstudio.com/docs/copilot/reference/mcp-configuration（查询日期 2026-04-22）
7. Cursor MCP 配置说明：https://docs.cursor.com/context/model-context-protocol（查询日期 2026-04-22）
8. 站内互链 - MCP 是什么：/mcp/cards/what-is-mcp
9. 站内互链 - MCP 架构：/mcp/cards/mcp-architecture
10. 站内互链 - 在 Claude Code 中配置 MCP（聚焦 Claude Code 单工具）：/mcp/cards/claude-code-setup