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 連線。