MCP 接入外部工具

什么时候该接 MCP

判断标准只有一句:你是不是在反复把另一个工具里的内容复制粘贴进对话框?

issue 描述、Sentry 报错、数据库查询结果、Figma 设计稿——只要你在"从某个系统里抄数据喂给 Claude",那个系统就值得接成 MCP server。接上之后 Claude 能直接读写它,不必你当中间人。

典型场景:

• issue tracker:"实现 JIRA issue ENG-4521 描述的功能,然后在 GitHub 开 PR。"
• 监控数据:"查 Sentry 看 ENG-4521 这个功能的报错情况。"
• 数据库:"从 PostgreSQL 里找出最近用过该功能的 10 个用户邮箱。"

反过来,如果某个工具你一个月才用一次,接它只是白占上下文(每个连上的 server 都会把工具名和说明塞进每次会话)——这种就别接,用完即走。

加第一个 server(stdio / http / sse)

claude mcp add 在终端里运行(不是会话内),它把 server 定义写到磁盘配置。三种 transport:

# http —— 远程托管服务,推荐
claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp
 
# stdio —— 本地进程(默认 transport,可省略 --transport)。
# 注意 -- 之后才是启动 server 的命令
claude mcp add playwright -- npx -y @playwright/mcp@latest
 
# sse —— 旧版 Server-Sent Events,已废弃,有 http 就别用
claude mcp add --transport sse asana https://mcp.asana.com/sse

几个容易踩的点:

• flag 必须在 server 名之前。--transport、--scope、--header、--env 都得写在名字前面,否则会被当成 server 命令的参数传错地方。
• stdio 用 -- 分隔。-- 之后的所有内容原样交给 server 启动,Claude 不再解析。
• add 命令只是写配置,打印 Added ... 不代表连上了——连接状态要下一步单独验。

带认证头的远程 server(静态 token,非 OAuth)在 add 时就把 token 给进去:

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

用 /mcp 看连接与授权

加完先验。终端里:

claude mcp list

claude-code-docs   ✓ Connected
github             ! Needs authentication
playwright         ✗ Failed to connect
new-tool           ⏸ Pending approval

官方定义的状态就这几种:✓ Connected(可用)、! Needs authentication(要浏览器登录或 token)、✗ Failed to connect / ✗ Connection error(没响应)、⏸ Pending approval(project scope server 还没批准)。

/mcp 是会话内的 slash 命令,跟 claude mcp 是两套东西:claude mcp 改磁盘配置,/mcp 只看/操作当前 session 的实时状态(查连接、触发 OAuth、手动重连)。

需要 OAuth 的 server(Sentry、Linear、Notion 这类),add 之后状态会是 ! Needs authentication,进会话用 /mcp 完成登录:

> /mcp

在面板里选中 sentry → 回车 → 选 Authenticate,浏览器打开授权页,批准后回到 Claude Code,状态变 connected。token 存在本地,后续自动刷新。

提示:自 v2.1.193 起,如果有 server 需要认证,Claude Code 会在会话启动时直接提示你去 /mcp 授权,不用等第一次工具调用失败才发现没连上。

scope 与 .mcp.json(本地 vs 入库共享)

--scope 决定配置写到哪、谁能用。add 时就定死,改 scope 得 remove 再重新 add。

| scope | 写入文件 | 谁能用 | | --- | --- | --- | | local(默认) | ~/.claude.json(按本项目路径分区) | 只有你,只这个项目 | | project | .mcp.json(项目根目录) | 所有 clone 仓库的人 | | user | ~/.claude.json(全局键) | 只有你,所有项目 |

# 团队共享:写进 .mcp.json,提交 git
claude mcp add --scope project --transport http sentry https://mcp.sentry.dev/mcp
 
# 个人跨项目:写全局,所有项目都能用
claude mcp add --scope user --transport http hubspot https://mcp.hubspot.com/anthropic

--scope project 生成的 .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 ${INTERNAL_API_TOKEN}"
      }
    },
    "local-tools": {
      "type": "stdio",
      "command": "node",
      "args": ["${CLAUDE_PROJECT_DIR:-.}/tools/mcp-server.js"]
    }
  }
}

command / args / env / url / headers 这些位置支持环境变量展开:

• ${VAR} —— 直接展开,未定义就报错(适合强制要求的 token)。
• ${VAR:-default} —— 未定义时回退到 default(适合可选的 base URL)。

这正是"配置进 git、密钥不进 git"的关键:仓库里提交 Bearer ${INTERNAL_API_TOKEN},每个人把真实 token 放各自 shell/.env 里,.mcp.json 永远不含明文。

批准与覆盖两个坑:① project scope 的 server 首次加载会弹信任确认,claude mcp list 显示 ⏸ Pending approval,必须用交互模式跑一次 claude 批准(headless 绕不过);用 claude mcp reset-project-choices 可重置。② 同名 server 跨 scope 不合并字段,按优先级 local > project > user 整条取最高那条——工具行为不对时先 claude mcp list 看实际加载的是哪条。

跨系统实战:读 issue → 查库 → 改代码 → 开 PR

把 GitHub 和数据库都接上,一句话串起一条平时要跨三个系统的活。先配两个 server:

# GitHub(静态 token)
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"
 
# 只读的生产库(本地 stdio,经 npx 拉起)
claude mcp add db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

claude mcp list 确认两个都 ✓ Connected 后,进会话直接下发整条任务:

> 用 github server 读 issue #312 的描述,
> 再用 db server 查一下受影响的表结构,
> 按 issue 要求改代码,跑通测试后开一个 PR,标题带上 issue 号

Claude 会依次调用 github 的 issue 读取工具、db 的 schema 查询工具,在本地改文件,最后调 github 工具开 PR。输出里每个工具调用都标着 server 名(如 github / db),这是确认数据确实走了 MCP、而不是 Claude 凭记忆瞎编的标志。

第一次调某个 MCP 工具时 Claude 会停下来征求授权。嫌反复确认烦,可以把工具加进 allowlist——MCP 工具的权限标识符是 mcp__<server>__<tool>:

> /permissions

在 Allow 规则里加 mcp__github(放行整个 github server)或 mcp__db__query(只放行 db 的 query 这一个工具)。也可以写进 .claude/settings.json 的 permissions.allow 数组提交给团队。

排错与变体(--mcp-config、Header、远程 vs 本地)

✗ Failed to connect / ✗ Connection error——server 没起来或 URL 没响应。

• 远程 server:先 curl -I <url> 看可达性。404/405 说明 server 在(很多 MCP endpoint 只收 POST,这俩码反而正常);401/403 说明要认证(走 OAuth 或补 --header);完全没响应就是 URL 或网络问题。
• 本地 stdio:把 add 时 -- 后面那条命令原样在终端跑一遍。能起来并等待输入,说明 server 没问题,多半是你 add 时漏了 -- 分隔符;报错则按提示补缺的依赖。

启动超时——stdio server 第一次 npx 下载包慢,默认 30 秒不够。用 MCP_TIMEOUT(毫秒)放宽:

MCP_TIMEOUT=60000 claude

改了 .mcp.json 不生效——Claude Code 只在会话启动时读它,改完要退出重进。之前拒绝过该 server 的话,用 claude mcp reset-project-choices 重置批准记录。

临时 / 一次性 server,不想写进任何持久配置——用 --mcp-config 直接在启动时喂一个 JSON 文件(或字符串,空格分隔多个):

claude --mcp-config ./mcp.json

想只用这个文件里的 server、屏蔽掉所有其他来源(local/project/user)的配置,加 --strict-mcp-config:

claude --strict-mcp-config --mcp-config ./mcp.json

适合 CI、临时调试、或想干净复现某套工具组合的场景。

回到 示例列表 →