---
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="/zh-Hant/docs/claude-code/understanding/10-operation-control" title="10 · 怎麼控制它動手" description="MCP 讓 Claude Code 夠到更多系統。下一篇講操作控制：夠得到以後，怎麼避免它亂動。" />
  <Card href="/zh-Hant/docs/claude-code/understanding/11-permissions" title="11 · 許可權怎麼管" description="MCP server 可能連資料庫、GitHub 和 SaaS 賬號。許可權篇會繼續講審批、allowlist 和風險邊界。" />
  <Card href="/zh-Hant/docs/claude-code/understanding/07-subagents" title="07 · 派助手去幹活" description="SubAgents 隔離上下文，MCP 擴充套件外部工具。兩者經常一起出現：子代理可以用受限 MCP 工具做專門任務。" />
</Cards>

如果只記一個判斷：**當你總在把某個外部系統裡的內容複製給 Claude Code，那裡就可能需要一個 MCP 連線。**
