09 · 怎么连外部服务

翔宇见过很多人把 Claude Code 的局限归因于“模型不够强”。但有一类问题，模型再强也没用：Jira ticket、GitHub PR、Sentry 报错、PostgreSQL 数据都不在它手里。MCP（Model Context Protocol，模型上下文协议）解决的不是“想不到”，而是“够不到”。——翔宇

1. 住在电脑里，不等于够到全世界

第 1 篇说过，Claude Code 和普通聊天框最大的区别，是它住在你的开发环境里。它能读文件、改代码、跑命令。

但这不代表它天然能访问所有东西。

你可以这样问：

看看 GitHub 上 PR #142 的 review comments。
把对应 Jira ticket 标成 done。
再查一下 Sentry 过去 24 小时有没有相关报错。

Claude Code 能理解这句话。

但 GitHub 评论在 GitHub，Jira 状态在 Jira，Sentry 报错在 Sentry。它们不是你项目里的文件，也不是 Claude Code 默认拥有的工具。

没有连接时，你只能手动搬运：

你打开 GitHub -> 复制评论 -> 粘给 Claude
你打开 Jira -> 复制 ticket -> 粘给 Claude
你打开 Sentry -> 截图或复制报错 -> 粘给 Claude
Claude 根据你粘贴的内容工作

这和第 1 篇讲 ChatGPT 时代的“复制粘贴代码”本质一样，只是从代码搬运变成外部系统搬运。

官方 Claude Code MCP 文档 的建议很直接：当你发现自己总是在把 issue tracker 或 monitoring dashboard 里的数据复制进对话时，就该考虑连接 MCP server。连接后，Claude 可以直接读和操作那些系统，而不是只依赖你粘贴的内容。

2. 如果每个服务都手写接口，会发生什么

不用 MCP 也不是完全不能做。

你可以让 Claude 写脚本：

gh pr view 142 --comments

你也可以自己写 Jira API 调用、Sentry API 调用、数据库查询脚本。能跑。

但很快会遇到三个问题。

第一，接口太多

GitHub 有 GitHub 的 API，Jira 有 Jira 的 API，Slack 有 Slack 的 API，PostgreSQL 又是数据库连接。

每接一个服务，都要重新理解认证、请求格式、分页、错误处理和权限边界。

第二，每个 AI 工具都要重写

Claude Code 接一次，Cursor 接一次，别的 Agent 再接一次。工具越多、服务越多，对接成本越爆炸。

这个结构可以写成：

没有 MCP：
AI 工具数量 x 外部服务数量 = 对接数量

10 个 AI 工具 x 100 个外部服务 = 1000 套连接

有协议后变成：

有 MCP：
AI 工具实现 MCP client
外部服务实现 MCP server

10 个 AI 工具 + 100 个外部服务 = 110 个组件

这就是协议的价值：把 M x N 的适配，变成 M + N 的适配。

第三，权限和安全会散掉

手写脚本很容易把 token、账号、路径写死。脚本复制给同事后，谁有权限、权限多大、数据会不会进版本库，都变得模糊。

3. MCP 的三层：Host、Client、Server

MCP 的架构有三个角色。先看图。

flowchart LR
    User["用户<br/>提出任务"]
    Host["MCP Host<br/>Claude Code"]
    ClientA["MCP Client<br/>GitHub 连接"]
    ClientB["MCP Client<br/>Sentry 连接"]
    ServerA["MCP Server<br/>GitHub"]
    ServerB["MCP Server<br/>Sentry"]

    User --> Host
    Host --> ClientA --> ServerA
    Host --> ClientB --> ServerB
    ServerA --> ClientA --> Host
    ServerB --> ClientB --> Host

    style Host fill:#dbeafe,stroke:#3b82f6,stroke-width:2px
    style ClientA fill:#dcfce7,stroke:#22c55e
    style ClientB fill:#dcfce7,stroke:#22c55e
    style ServerA fill:#fef3c7,stroke:#f59e0b
    style ServerB fill:#fef3c7,stroke:#f59e0b

官方 MCP 架构说明 里，MCP host 是 AI 应用，比如 Claude Code 或 Claude Desktop；host 会为每个 MCP server 创建一个 MCP client；每个 client 和对应 server 保持专用连接。

MCP 协议怎么"说话"：底层是 JSON-RPC 2.0（一种简单的远程调用协议）—— client 发请求 JSON 给 server，server 回响应 JSON。三种 transport 区别只在"消息怎么传"：HTTP 走 HTTPS 请求 / stdio 走标准输入输出 / SSE 走服务器推送事件。所以"换 transport"不影响协议本身——同一个 server 理论上能同时支持多种 transport。这种协议层 vs 传输层分离的设计是为什么 MCP 能在不同环境下跑：本地工具走 stdio（最低延迟），远程 SaaS 走 HTTPS（穿透防火墙），实时数据走 SSE（双向推送）。

最容易搞反的是 Client 和 Server。

记一个简单规则：Claude Code 这边是 Client，外部能力那边是 Server。

就像你去餐厅点菜：你是 client，厨房是 server。厨房可以在本地，也可以在远处；只要它按协议响应，就是 server。

4. 它到底给 Claude Code 接了什么

MCP server 能暴露几类能力。最常见的三类是 Tools、Resources、Prompts。

可以用“手、眼睛、流程手册”记：

• Tools 是手：能改变外部世界，或者执行查询。
• Resources 是眼睛：拿上下文给 Claude 看。
• Prompts 是流程手册：把一套交互步骤做成可复用模板。

MCP 官方架构文档还提到 client-side primitives（客户端侧原语），包括 Sampling、Elicitation 和 Logging。这些是 server 反过来请求 host 做事的能力。对新手来说，先抓住一个重点：MCP 不是单向“Claude 调工具”，它可以支持更动态的交互。

新手最常见的混淆：把所有外部能力都当 Tools 用——结果两个问题：① 每次 Claude 想读 GitHub issue 都触发一次"Tools 调用确认"弹窗（对只读数据是过度审批）；② 工具描述常驻 system prompt，装 5 个 SaaS server 全当 Tools，启动时光工具 schema 就占几千 token。修复方式：把"读取数据"换成 Resources（用 @github:issue://123 引用，不弹工具确认），把"执行动作"留给 Tools。Prompts 留给"反复用的多步骤交互"——比如一个调试模板。

5. 一个 GitHub PR 例子怎么跑

回到开头的 PR 场景。

你问：

审阅 PR #142，汇总尚未解决的 review 评论。

如果 GitHub MCP server 已连接，大致会发生这些事：

flowchart TB
    Ask["你提出任务<br/>Review PR #142"]
    Registry["Claude Code 可见工具列表<br/>GitHub MCP tools"]
    Choose["模型判断需要 GitHub 工具"]
    Call["调用 MCP tool<br/>读取 PR 和 comments"]
    Result["GitHub server 返回结构化结果"]
    Answer["Claude 汇总评论和建议"]

    Ask --> Registry --> Choose --> Call --> Result --> Answer

    style Registry fill:#dbeafe,stroke:#3b82f6
    style Call fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
    style Answer fill:#dcfce7,stroke:#22c55e,stroke-width:2px

这里的关键不是“Claude 知道 GitHub 是什么”，而是 GitHub MCP server 把可用工具暴露出来。MCP 的工具发现机制会让 client 知道有哪些 tool、每个 tool 的描述、输入参数 schema。模型再根据你的任务选择合适工具。

这也是为什么工具描述很重要。一个坏描述会让 Claude 不知道何时该用；一个太宽的工具会让权限边界模糊。

Claude Code 文档还提醒：第三方 MCP server 要自己承担信任风险。尤其是能抓取不可信内容的 server，可能带来 prompt injection（提示注入）风险。

6. 怎么安装：HTTP、stdio、SSE

Claude Code 里常见三种 transport（传输方式）。

远程 HTTP server 示例：

claude mcp add --transport http notion https://mcp.notion.com/mcp

本地 stdio server 示例：

claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

注意 --。Claude Code 官方文档特别强调：--transport、--env、--scope、--header 这类 Claude 的选项要放在 server name 前面；-- 后面才是传给 MCP server 的命令和参数。

常用管理命令：

claude mcp list
claude mcp get github
claude mcp remove github

在 Claude Code 会话里，可以用：

/mcp

查看状态、做远程 server 的 OAuth 认证。

7. 装到哪里：local、project、user

MCP server 不是只有“装了”和“没装”两种状态。你还要决定作用范围。

local 是默认范围。它只在当前项目生效，而且不会进版本库，适合个人试用、带私密凭据的服务、临时开发 server。

project 会写进 .mcp.json，适合团队共享同一套工具配置。但要注意：.mcp.json 可以进仓库，凭据不能直接写进去。

user 适合你所有项目都会用的个人工具，比如常用搜索、个人知识库、通用文档 server。

优先级也要记住：同名 server 出现在多个地方时，Claude Code 按 local > project > user > plugin-provided servers > claude.ai connectors 选择。

8. 团队配置和凭据怎么处理

团队共享 MCP，最常见方式是 .mcp.json。

一个 HTTP server 配置可能长这样：

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

Claude Code 支持 .mcp.json 里的环境变量展开：

• ${VAR}：使用环境变量。
• ${VAR:-default}：没有环境变量时用默认值。

可以展开的位置包括 command、args、env、url、headers。

这意味着团队可以共享结构，不共享秘密：

.mcp.json 进仓库
API_KEY 留在每个人自己的环境变量或凭据系统里

远程 server 如果需要 OAuth 2.0，通常先添加 server，再在 Claude Code 里运行 /mcp，按浏览器流程登录。官方文档也说明，client secret 会存在系统 keychain 或凭据文件里，不应该直接写进配置。

9. Resources 怎么用：不是所有东西都要变成工具

很多人一上来只盯着 Tools，觉得 MCP 就是“让 AI 调函数”。

但 Resources 很重要，因为很多时候你只是想让 Claude 看资料，不想让它执行动作。

Claude Code 支持用 @ 引用 MCP resources，形式类似：

分析一下 @github:issue://123，给出修复建议。

也可以一次引用多个：

对比 @postgres:schema://users 和 @docs:file://database/user-model，看字段是否一致。

这类引用会把资源作为上下文带进来。它更像“把外部资料夹拿到桌面上”，不是让 Claude 去改外部系统。

10. Elicitation：server 也能反问

传统工具调用像这样：

Claude -> MCP server：帮我执行 X
MCP server -> Claude：结果是 Y

但真实流程经常需要补信息。

比如部署 server 发现你没说目标环境：

MCP server：你要部署 staging 还是 production？

或者数据库 server 发现操作有风险：

MCP server：这个操作会影响 1200 行数据，请输入确认原因。

这就是 Elicitation（信息征询）。官方 Claude Code 文档说，MCP servers 可以在任务中请求结构化输入；Claude Code 会显示交互式对话框，把你的响应传回 server。它可以是表单模式，也可以是 URL 模式，例如认证或审批。

这让 MCP 从“单向函数调用”更接近“可澄清的流程”。

11. 别把 MCP 当越多越好的插件

MCP server 越多，不一定越强。

每个 server 会带来工具描述、资源列表、认证状态和安全面。工具太多时，Claude Code 的上下文会被工具说明占掉一部分；模型也更难判断该用哪个。

Claude Code 有一些机制缓解这个问题，比如 tool list changed 动态刷新、MCP tool search、大输出警告。官方文档提到，MCP tool 输出超过 10,000 tokens 时会警告；需要时可以用 MAX_MCP_OUTPUT_TOKENS 提高限制。但这不是让你无限装 server 的理由。

实操上可以按三层筛：

新手最常见的失控路径：在 marketplace 看到 30 个 server 觉得"装上免得后悔"——结果启动时所有工具 schema 全部常驻 system prompt（每个 server 5-20 个 tool，每个 tool schema 50-100 token），50 个 tool 就占了 5000+ token；Claude 每轮决策时要在 50 个工具里挑 1 个，匹配命中率反而下降；遇到危险操作弹窗一次比一次频繁。修复方式：定期 /mcp 看当前装了多少，一个月没用过的拆掉；把"探索期试装"和"长期日用"分开 scope（试用走 local，稳定后升 user 或 project）。

12. 本章自检

试着用自己的话回答：

1. 有人说"Claude Code 已经能跑命令，所以不需要 MCP"。这个说法漏掉了什么？对应 §1-§2。
2. MCP 里 Host、Client、Server 分别是谁？为什么一个 Host 会有多个 Client？对应 §3。
3. 动手题 ⭐：列出你工作中最近一周反复复制粘贴给 Claude 的 3 个外部信息源（比如 Jira ticket / Sentry 报错 / GitHub PR / 数据库 schema）。每个判断：是该装 MCP server 走 Tools / Resources，还是用 Read/WebFetch 一次性读？判断标准：复制粘贴 ≥3 次 / 周 → 装 MCP；偶尔一次 → 直接读。这一题做完你应该能列出 1-2 个真正值得装的 MCP server。对应 §4 + §11。

官方资料

• Connect Claude Code to tools via MCP
• Model Context Protocol

接下来去哪

如果只记一个判断：当你总在把某个外部系统里的内容复制给 Claude Code，那里就可能需要一个 MCP 连接。