---
title: "09 · 怎么连外部服务"
description: "MCP 不是给 Claude Code 加脑子，而是让它够到 GitHub、Sentry、数据库这些外部系统的标准接口。"
canonical: "https://xiangyugongzuoliu.com/tag/claude-code"
verifiedAt: "2026-05-08"
---

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

> [!NOTE]
> **这一篇用 15 分钟换什么**：前 8 篇讲的是 Claude Code 在你本机、上下文和多代理里的工作方式。现在开始讲“外部世界”：Claude Code 怎么接 GitHub、Jira、Sentry、数据库、Slack 这类系统。读完你会知道 MCP 该怎么理解、怎么配置、什么范围合适、为什么不能见一个 server 就装一个。

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

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

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

你可以这样问：

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

Claude Code 能理解这句话。

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

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

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

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

> [!IMPORTANT]
> **第一性原理**：MCP 解决的是外部系统连接问题。Claude Code 只有连上对应系统，才能从“根据你粘贴的信息工作”变成“直接读取和操作那个系统”。

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

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

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

你可以让 Claude 写脚本：

```bash
gh pr view 142 --comments
```

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

但很快会遇到三个问题。

### 第一，接口太多

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

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

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

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

这个结构可以写成：

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

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

有协议后变成：

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

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

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

### 第三，权限和安全会散掉

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

> [!TIP]
> **一句话理解**：MCP 像软件世界的“统一插口”。Claude Code 不需要为每个服务单独学一套连接方式，服务也不需要为每个 AI 工具写一套适配。

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

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

```mermaid
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 架构说明](https://modelcontextprotocol.io/docs/learn/architecture) 里，MCP host 是 AI 应用，比如 Claude Code 或 Claude Desktop；host 会为每个 MCP server 创建一个 MCP client；每个 client 和对应 server 保持专用连接。

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

| 角色 | 中文理解 | 在 Claude Code 里是谁 |
|------|------|------|
| Host | 总协调者 | Claude Code |
| Client | 每个服务的连接员 | Claude Code 内部为每个 server 建的连接 |
| Server | 提供外部能力的一端 | GitHub、Sentry、数据库、本地脚本等 |

最容易搞反的是 Client 和 Server。

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

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

> [!WARNING]
> **新手坑**：不要把“server”理解成一定是一台云服务器。MCP server 可以是远程 HTTP 服务，也可以是你本机通过 stdio 启动的一个进程。

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

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

| 能力 | 中文理解 | 谁控制 | 例子 |
|------|------|------|------|
| Tools | 工具，能执行动作 | 模型决定何时调用，用户仍受权限控制 | 创建 issue、查数据库、发 Slack |
| Resources | 资源，只读上下文 | 用户或模型引用读取 | `@github:issue://123`、数据库 schema |
| Prompts | 提示模板，复用交互流程 | 用户主动调用或工具提供 | 代码审查模板、排障模板 |

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

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

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

> [!IMPORTANT]
> **边界**：Tools 有副作用风险，Resources 通常是只读上下文，Prompts 是流程复用。不要把三者混成"都是插件"。

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

## 5. 一个 GitHub PR 例子怎么跑

回到开头的 PR 场景。

你问：

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

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

```mermaid
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（提示注入）风险。

> [!CAUTION]
> **不要乱装**：MCP server 不是浏览器插件市场里的小挂件。它可能读你的代码、连你的数据库、访问你的 SaaS 账号。先看来源、权限和认证方式。

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

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

| 方式 | 适合什么 | 官方状态 | 例子 |
|------|------|------|------|
| HTTP | 远程云服务 | 推荐用于 remote server | Notion、Sentry、GitHub |
| stdio | 本地进程 | 适合本地脚本和直接系统访问 | 本地数据库工具、npx server |
| SSE | 老式远程连接 | deprecated，能不用就不用 | 旧服务兼容 |

远程 HTTP server 示例：

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

本地 stdio server 示例：

```bash
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 的命令和参数。

常用管理命令：

```bash
claude mcp list
claude mcp get github
claude mcp remove github
```

在 Claude Code 会话里，可以用：

```text
/mcp
```

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

> [!TIP]
> **实操顺序**：远程 SaaS 优先 HTTP，本地工具用 stdio，看到 SSE 先确认有没有 HTTP 版本。

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

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

| Scope | 加载范围 | 是否团队共享 | 存在哪里 |
|------|------|------|------|
| `local` | 当前项目 | 否 | `~/.claude.json` 的当前项目条目 |
| `project` | 当前项目 | 是 | 项目根目录 `.mcp.json` |
| `user` | 所有项目 | 否 | `~/.claude.json` |

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

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

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

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

> [!WARNING]
> **常见误解**：local scope 的 MCP server 存在 `~/.claude.json`，不是 `.claude/settings.local.json`。它是“当前项目私有”，不是“写在项目 local settings 文件里”。

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

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

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

```json
{
  "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`。

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

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

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

> [!CAUTION]
> **安全底线**：`.mcp.json` 可以共享连接方式，不应该共享真实 token、账号密码、私有 DSN。项目 scope 不等于凭据 scope。

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

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

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

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

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

也可以一次引用多个：

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

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

| 需求 | 更像 Tools | 更像 Resources |
|------|------|------|
| 创建 GitHub issue | 是 | 否 |
| 读取 issue 内容 | 可能 | 是 |
| 查询订单表 schema | 可能 | 是 |
| 向 Slack 发消息 | 是 | 否 |
| 读取 API 文档 | 否 | 是 |

> [!IMPORTANT]
> **选择标准**：需要改变外部系统，用 Tools；只是把外部信息拿来当上下文，用 Resources。

## 10. Elicitation：server 也能反问

传统工具调用像这样：

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

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

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

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

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

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

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

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

<details>
<summary><b>🔍 深一层：没有 Elicitation 时怎么绕</b></summary>

没有 Elicitation，你通常只能用三种绕法：

1. 让 Claude 先停下来问你，再重新调用工具。
2. 在工具外面包一层脚本，脚本自己处理交互。
3. 用 Hooks 拦截危险动作，强制人工确认。

这些都能做，但流程会碎。Elicitation 的价值在于：server 自己知道缺什么信息，并按协议向用户要回来。

</details>

## 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 的理由。

实操上可以按三层筛：

| 层级 | 建议 | 例子 |
|------|------|------|
| 必装 | 每天都用，且复制粘贴频繁 | GitHub、Sentry、数据库只读 |
| 可试 | 某个项目阶段用 | Figma、Jira、Notion |
| 不装 | 偶尔用、权限大、来源不明 | 随机第三方 server |

> [!WARNING]
> **新手坑**：不要把 MCP 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。

> [!TIP]
> **过关标准**：能用一句话说清：MCP 是 Claude Code 连接外部工具、数据源和 API 的标准协议；它解决的是够不到外部系统的问题，不是模型聪不聪明的问题。

<details id="glossary">
<summary><b>本篇术语速查表</b></summary>

- **MCP**：模型上下文协议，AI 工具连接外部工具和数据源的开放标准。
- **Host**：主机，管理 MCP 连接的 AI 应用，例如 Claude Code。
- **Client**：客户端，Host 内部负责连接某个 server 的组件。
- **Server**：服务器，暴露工具、资源或提示的外部能力端。
- **Tools**：工具，可被调用来执行动作或查询的能力。
- **Resources**：资源，可作为上下文读取的数据。
- **Prompts**：提示模板，可复用的交互或任务模板。
- **Transport**：传输方式，client 和 server 通信的方式，如 HTTP 或 stdio。
- **stdio**：标准输入输出，本地 MCP server 常用通信方式。
- **Elicitation**：信息征询，MCP server 在任务中向用户请求补充输入。

</details>

## 官方资料

- [Connect Claude Code to tools via MCP](https://code.claude.com/docs/en/mcp)
- [Model Context Protocol](https://modelcontextprotocol.io/)

## 接下来去哪

<Cards>
  <Card href="/docs/claude-code/understanding/10-operation-control" title="10 · 怎么控制它动手" description="MCP 让 Claude Code 够到更多系统。下一篇讲操作控制：够得到以后，怎么避免它乱动。" />
  <Card href="/docs/claude-code/understanding/11-permissions" title="11 · 权限怎么管" description="MCP server 可能连数据库、GitHub 和 SaaS 账号。权限篇会继续讲审批、allowlist 和风险边界。" />
  <Card href="/docs/claude-code/understanding/07-subagents" title="07 · 派助手去干活" description="SubAgents 隔离上下文，MCP 扩展外部工具。两者经常一起出现：子代理可以用受限 MCP 工具做专门任务。" />
</Cards>

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