連接外部工具：MCP 伺服器

9.1　MCP 是什麼：幫 Claude 接上各種外接裝置

MCP 是一套「共通的接頭規格」。有了它，Claude Code 就能連到你電腦以外的資料和服務，能力一下子延伸出去。連上之後，你可以叫它做這些事：

• 讀 Google Drive 的設計文件
• 更新 Jira 的工單
• 抓 Slack 的訊息
• 查你自己的資料庫
• 甚至接上你自己寫的小工具

9.2　加入你的第一個外部工具：跟著做一次

加一個外部工具，靠的是同一個指令：claude mcp add。不管你用 Mac、Windows 還是 Linux，這個指令的打法都一樣。下面用兩個真實例子，帶你把第一個 MCP server 接起來。一個是「網路上的線上服務」，一個是「跑在你自己電腦上的工具」——這兩種就是你之後會遇到的兩大類。

1. 1
   ✋動手做

   先決定：這個工具在「網路上」還是「你電腦上」

   接一個工具前，先搞清楚它住在哪。住在網路上的線上服務（像金流服務 Stripe），用網址連，這種接法叫 http；跑在你自己電腦上的工具（像「讓 Claude 讀某個資料夾」），則是直接在本機把它叫起來，這種叫 local。這個「怎麼連」的方式，技術上叫 transport。決定好是哪一種，下一步的指令才知道要怎麼打。

2. 2
   ✋動手做

   打 claude mcp add 指令，把工具加進來

   照你上一步決定的類型，挑下面對應的官方或公司核准範例貼進終端機按 Enter。不要把陌生網站給的名稱、網址或指令直接換進來；接任何工具前，先確認它的來源與權限。

   範例一：連一個用網址的線上服務（以金流服務 Stripe 為例）

   # 線上服務用 --transport http，後面接「名字」和「網址」
   claude mcp add --transport http stripe https://mcp.stripe.com

   複製

   範例二：在你電腦上跑的本機工具（以「讀取檔案系統」為例）

   # 進階：把「/你的/信任資料夾完整路徑」替換成你自己確認過的資料夾
   # -- 後面是實際執行的程式；npx 會使用已安裝的 Node.js
   claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /你的/信任資料夾完整路徑

   ⚠️

   npx 與路徑不是可直接照抄的萬用字

   npx 是 Node.js 附帶的套件執行工具；先在終端機確認 node --version 和 npx --version 都有結果，再只使用該 MCP 官方文件指定、你信任的套件。/你的/信任資料夾完整路徑 是占位文字，必須換成你親自確認的完整路徑，且只授權最小必要資料夾；不要填磁碟根目錄、個人家目錄、下載資料夾或含有憑證的資料夾。Windows 請在 Windows Terminal 的 PowerShell 分頁，以實際完整 Windows 路徑取代它。

   想知道原理：指令裡那個 -- 是做什麼的？

   那兩條橫線 -- 是一個分界線：它告訴 claude mcp add「我的設定講完了，後面整段，是要實際去執行、把這個工具跑起來的程式」。以範例二來說，-- 後面的 npx -y @modelcontextprotocol/server-filesystem /你的/信任資料夾完整路徑 就是真正被執行的程式，連同它能讀取的資料夾路徑。只替換占位路徑，不要自行猜測、補寫或換成陌生套件。 不確定某個工具的指令格式時，先查該工具官方文件或打 claude mcp add --help。

3. 3

   用 /mcp 確認它真的連上了

   加完別急著走，回到 Claude Code 的對話視窗裡，直接打 /mcp 按 Enter。它會列出你目前接了哪些工具、每個是不是連上了（connected）、各提供幾個工具可用。看到你剛加的那個名字、狀態是「已連線」，就成功了。

   ✅ 預期會看到

   # 在對話裡打 /mcp，大致會看到這類清單（實際畫面依版本略有不同）
   MCP Servers
     stripe       ✔ connected   ·  18 tools
     filesystem   ✔ connected   ·  11 tools

   複製

其實共有四種連法，你會用到的通常只有前兩種

剛剛你已經用過 http（連網路上的服務）和步驟①講的「本機執行」——這種本機執行，正式的技術名稱叫 stdio，也是省略 --transport 時的預設值。這兩種也確實涵蓋了你會遇到的絕大多數情境。完整來說，Claude Code 支援四種連線方式，剩下兩種你至少要認得名字、知道什麼時候會用到：

這幾種傳輸方式的旗標名稱和細節，各版本可能會微調——真的要接超出前兩種的情境時，先跑一次 claude mcp add --help 或查官方文件，確認當下版本的實際寫法最保險。

9.3　這個連線給誰用？三種範圍（scope）

加工具的時候，還有一個選擇：這條連線，是「只有你自己、只在這個專案」能用，還是「你所有的專案」都能用，又或者「整個團隊」一起共用？這個「給誰用」的設定，就叫 scope。不特別指定的話，預設是最小的那種（只給你、只給這個專案）。下面這張表，告訴你三種怎麼選。

如果同一個名字在好幾個地方都被定義呢？比方說你自己在 user scope 加了一個叫 github 的伺服器，團隊的 .mcp.json（project scope）裡也剛好有一個同名的——Claude Code不會把兩邊設定合併，而是照優先權「整組採用其中一份」：local ＞ project ＞ user ＞ 外掛（plugin）提供的伺服器 ＞ claude.ai 的連接器（connectors）。三種 scope 之間用「名字」比對重複；外掛和連接器則是用連線位址（網址或指令）來比對，是另一套判斷方式。記住這個順序，之後遇到「明明改了 user scope 設定卻沒生效」的情況，多半是被優先權更高的 local 或 project 蓋過去了。

9.4　進階：直接手寫 .mcp.json 設定檔

前面都是靠 claude mcp add 這個指令幫你把設定寫好。但如果你要接的伺服器比較多、想一次看到全貌，或想把設定完整地跟團隊共用，直接打開 .mcp.json 這份檔案自己編輯，反而更方便。這一節教你怎麼安全地手寫它——不想碰設定檔的話，這節可以先跳過，回頭要用再來查。

格式是一份標準 JSON，最外層固定是 mcpServers，底下每一個 key 就是你自訂的伺服器名字。混合 HTTP 和本機（stdio）兩種寫法可以放在同一份檔案裡：

// project scope 的 .mcp.json，放在專案根目錄
{
  "mcpServers": {
    "claude-code-docs": { "type": "http", "url": "https://code.claude.com/docs/mcp" },
    "playwright": { "type": "stdio", "command": "npx", "args": ["-y", "@playwright/mcp@latest"] }
  }
}

團隊共用設定，但金鑰各自環境提供：環境變數展開

手寫設定檔最實用的地方，是它支援環境變數展開：把 ${VAR} 寫進去，Claude Code 讀檔案的時候會自動換成你電腦上那個環境變數的實際值；想留一個「沒設定時的預設值」，寫成 ${VAR:-default} 就行，這招在 command、args、env、url、headers 這五個欄位都能用。這代表一件很實用的事：你可以把「接哪些工具」這個共同基準放進 .mcp.json 讓全團隊 commit 共用，但每個人的 API 金鑰各自從自己的環境變數讀，設定檔裡完全不出現任何一組真正的金鑰明文。

// 網址跟 token 都留白，交給各自的環境變數補上
{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": { "Authorization": "Bearer ${API_KEY}" }
    }
  }
}

要注意：如果某個變數沒有預設值、你電腦上也沒設定它（像上面例子的 API_KEY，故意不給預設值），Claude Code 會直接解析失敗——不是「那個伺服器連不上」而已，是整份設定檔讀不進來。所以真的要留白給每個人自己補的欄位，通常是像金鑰這種本來就該因人而異、不該有共同預設值的東西。

手寫最容易踩到的三個雷

9.5　把外部資料「@」進對話，把範本變成斜線指令

9.1 提過，MCP 伺服器除了 Tools，還能提供 Resources（唯讀資料）和 Prompts（可重複套用的範本）。這兩種東西不必特地叫 Claude 去找，Claude Code 直接幫你做成兩個你已經很熟悉的操作介面——一個像「引用檔案」，一個像「打斜線指令」。

像引用檔案一樣引用外部資料

你可能已經習慣在對話裡打 @ 引用專案裡的某個檔案。MCP 的 Resources 也能用一模一樣的手感引用，只是格式多了「伺服器名字」和「協定」兩段，長得像 @伺服器:protocol://路徑。打 @ 之後，這些外部資源一樣會出現在自動完成選單裡，選下去，內容就自動抓回來當附件放進對話。

# 引用 GitHub 上第 123 號 issue，請它分析並給修法
Can you analyze @github:issue://123 and suggest a fix?

# 一次引用兩個不同伺服器的資源，讓它互相比對
Compare @postgres:schema://users with @docs:file://database/user-model

這招最省事的地方在於：你不用先叫 Claude「去讀那個 issue」再等它跑一次工具呼叫，資源直接以附件形式出現在同一輪對話裡，跟你自己貼上一段文字幾乎沒有差別。

MCP Prompt 自動變成 /斜線指令

伺服器提供的 Prompts，Claude Code 會自動幫你註冊成斜線指令，格式是 /mcp__伺服器名__prompt名，需要參數的話，直接空白分隔接在後面：

# 呼叫 github 伺服器的 pr_review prompt，帶入 PR 編號
/mcp__github__pr_review 456

# 呼叫 jira 伺服器的 create_issue prompt，帶入標題和優先度兩個參數
/mcp__jira__create_issue "Bug in login flow" high

效果跟你 8.3 學過的自訂 Skill 指令很像——差別是這些指令不是你寫的，是伺服器那一端的作者事先設計好、隨著連線一起帶過來的範本。打 / 叫出指令清單時，你會看到自己寫的 Skill 和伺服器帶來的 Prompt 混在同一份清單裡，不用特別分辨從哪來，能用就是能用。

9.6　日常管理與安全：列出、查看、移除、授權

工具接好之後，平常你會用到幾個簡單的管理指令：想看接了哪些、查某個的細節、不想要了就移除。下面幾個記起來就夠用了。再來談一件很重要的事——安全。MCP 工具能碰到你的資料，所以它什麼時候能動、什麼時候不能，主導權一定在你手上。

• claude mcp list — 列出你目前接了哪些 server
• claude mcp get <名字> — 看某一個 server 的詳細設定
• claude mcp remove <名字> — 把某個 server 移除
• 在對話裡打 /mcp — 查看連線狀態（會顯示每個 server 連上沒、各提供幾個工具）
• claude mcp add-json <名字> '{...}' — 直接貼一整段 JSON 設定加入伺服器，不用一個個選項慢慢拼
• claude mcp add-from-claude-desktop — 匯入你電腦上 Claude Desktop 既有的 MCP 設定（僅 🍎 macOS 與 WSL 可用）

💡 建議執行：先用這行看看你接了哪些工具

claude mcp list

想看某個工具的細節，或想拿掉它，把下面的「名字」換成你的工具名（例如上面例子裡的 stripe）：

# 看某個 server 的詳細設定
claude mcp get stripe

# 不想要了就移除它
claude mcp remove stripe

9.7　遠端伺服器的進階驗證與安全

9.6 教的「一定要你點頭」是所有 MCP 工具共通的第一道防線。這一節專門講遠端伺服器（HTTP／SSE 那一類）常遇到的驗證機制，以及怎麼用權限規則把「誰能用什麼工具」定得更精準。這節偏進階，用不到遠端登入型伺服器的話可以先跳過。

遠端伺服器要求登入？OAuth 全部自動處理

有些遠端伺服器（像需要你先登入帳號的服務）在你呼叫時會回應 401 或 403。Claude Code 偵測到這個狀況，會直接在 /mcp 面板把那個伺服器標成「需要驗證」，你選它，就會走一次標準的 OAuth 登入流程——瀏覽器跳出來、你用帳號登入、按下授權，之後拿到的權杖會被安全地存起來，過期也會自動更新，不用你每次重新登入。

不想進 session 才處理登入的話，也有純 CLI 版本：claude mcp login <名字> 和 claude mcp logout <名字>，跑完、清掉授權都不必真的打開對話。在沒有瀏覽器的環境（像用 SSH 連進去的伺服器）跑這個指令，它會改成直接印出一段授權網址，讓你自己複製到有瀏覽器的電腦上打開、登入後再把結果貼回終端機——這種情境記得用 ssh -t 連線保留互動式終端機才貼得進去，也可以加 --no-browser 直接強制走這條路。

少數伺服器沒有支援「動態客戶端註冊」，需要你先在服務商後台申請好一組 OAuth App，這時候用 --client-id、--client-secret、--callback-port 把申請到的資訊帶進去；也可以直接用 add-json 一次把完整設定貼進去：

# 帶預先申請好的 OAuth 憑證，一次用 JSON 加入
claude mcp add-json my-server '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' --client-secret

想把授權範圍鎖在團隊審核過的子集合，而不是照單全收伺服器廣播出來的所有權限，可以在設定裡加 oauth.scopes（空白分隔的字串）明確指定要哪些範圍；不設的話就照伺服器提供的範圍全收。之後如果某次工具呼叫回你一個 403 insufficient_scope（權限範圍不夠），Claude Code 會拿同一組被鎖定的範圍自動重新驗證一次——這時才需要你回頭手動放寬 oauth.scopes。

少數企業內部系統不是走 OAuth，而是用 Kerberos、短效權杖這類機制，這種情況可以設一個 headersHelper，指到一支會印出 JSON 格式 headers 的 shell 指令——它每次連線／重連都會重新執行一次（不快取），把權杖續期邏輯寫進腳本裡，而不是寫死在設定檔裡。這是比較進階的企業場景，一般個人使用大多用不到。

權限規則怎麼精準鎖到單一工具：mcp__伺服器__工具

第 8 章你在 /permissions 學過 allow／deny 清單的寫法。MCP 工具有自己一套固定的命名規則：mcp__伺服器名__工具名。想細部控制「這個伺服器的哪些工具能用、哪些不行」，就是照這個格式寫規則：

{
  "permissions": {
    "allow": ["mcp__github__create_issue", "mcp__linear__*"],
    "deny": ["mcp__filesystem__write_file", "mcp__*"]
  }
}

這裡有一個不對稱的地方，容易寫錯：deny 清單可以用比較寬鬆的萬用字元，像 mcp__*（比對所有 MCP 工具）甚至單獨一個 *（比對全部工具）都合法；但 allow 清單的萬用字元只能接在寫死的 mcp__伺服器名__ 前綴後面，像範例裡的 mcp__linear__* 就合法。如果你在 allow 清單裡單獨寫一個 mcp__* 或 *，Claude Code 會直接忽略這條、跳出警告，不會生效——道理不難懂：拒絕清單可以「寧可錯殺」，放行清單卻不能讓你一次不小心放行過了頭。

9.8　連線出問題怎麼辦：常見錯誤與排查

接 MCP 工具十次有兩三次會卡關，這很正常，原因通常也高度重複。這一節整理你最可能撞到的狀況——先學兩招萬用的排查手法，再對照後面的錯誤訊息表找答案。

兩招萬用排查法，先學這個

/mcp 面板看到「disconnected」的時候，其實有兩種完全不同的可能：這個伺服器根本沒啟動起來，或者啟動後又當掉了——但畫面上的文字沒辦法幫你分辨是哪一種。遇到這種「看不出所以然」的連線問題，下面兩招最有效：

• 開偵錯模式看真正的錯誤內容：用 claude --debug 2>&1 | grep -E "mcp|spawn|stdio" 啟動，過濾出跟 MCP 啟動有關的訊息，通常能看到被 UI 吃掉的那段真正錯誤原因。
• 把設定檔裡的指令直接貼到終端機手動跑一次：打開 .mcp.json 或跑 claude mcp get <名字>，把它顯示的那條指令原封不動複製到終端機執行。指令卡住等你輸入，代表伺服器本身沒問題，問題出在 Claude Code 這端的設定（十之八九是漏了 -- 分隔符）；指令直接跳錯誤訊息，代表問題在伺服器或執行環境本身（缺 Node.js、缺瀏覽器之類）。這一招幾乎能把「設定錯」和「環境缺東西」這兩大類原因立刻分開。

如果是遠端 HTTP／SSE 伺服器連線異常，還有第三招：用 curl -I <mcp網址> 先探探底。回應 404 或 405 其實是好消息——很多 MCP 端點本來就只接受 POST，代表伺服器有在線上；回應 401 或 403 代表要走 9.7 教的 OAuth，或補上 --header "Authorization: Bearer 你的token"；完全沒有任何回應，才是網路或網址本身的問題。

常見錯誤訊息對照表

錯誤訊息的確切文字可能因版本略有出入，下面抓的是最常見、最好辨認的關鍵字，找到最像的那一列，照右欄處理：

9.9　進階調校：逾時、輸出上限與 Tool Search

這節收三個「東西能動，但你可能會想微調」的細節：工具回傳太多資料怎麼辦、伺服器啟動太慢怎麼辦，以及接的伺服器一多、context 被工具定義塞爆怎麼辦。都是預設值就夠用的設定，真的遇到才回來查。

工具回傳的資料量太大：輸出上限

MCP 工具的回傳內容超過 10,000 tokens 時，Claude Code 會先跳警告；預設的硬上限是 25,000 tokens，超過會被截斷。真的需要一次拿到更多資料（例如查一份很大的資料表），可以調高環境變數：

# 把單次工具輸出上限調到 5 萬 tokens 再啟動
MAX_MCP_OUTPUT_TOKENS=50000 claude

如果你自己寫 MCP 伺服器，也可以不驚動全域設定，只針對「本來就會回傳大量資料」的單一工具（像整份資料庫 schema、完整檔案樹）調高上限——在 tools/list 回應裡加 _meta["anthropic/maxResultSizeChars"]，讓那個工具單獨享有更高的字元上限（硬上限 500,000 字元），比要求使用者全域調高 MAX_MCP_OUTPUT_TOKENS 更精準。要注意這個字元上限只對文字內容有效，圖片類的回傳內容還是受全域的 MAX_MCP_OUTPUT_TOKENS 限制。

伺服器啟動太慢、工具呼叫卡住：逾時設定分三層

接的伺服器一多，context 被工具定義塞爆怎麼辦：Tool Search

早期的做法是「連上的每個伺服器，工具名字、說明、完整參數規格，一次性全部塞進 context」——伺服器接多了非常燒 token，社群實測光接 4 個伺服器就吃掉快 7 萬 tokens，工具數一多到 50、100 支以上，context 很快就被工具定義本身佔滿，還沒開始做事就先燒掉一大截預算。

現在 Claude Code 預設換了做法，叫 Tool Search：一開始只載入工具的名字和伺服器的簡短說明，Claude 真的判斷需要某個工具時，才即時去搜尋、載入它完整的規格，大幅降低平常閒置時的 context 消耗。這個機制預設就是開著的，一般不用特別設定；真要調，環境變數是 ENABLE_TOOL_SEARCH（可設 true／false／auto／auto:N）。

如果有少數幾個工具是「每個回合都一定會用到」，被延後搜尋反而不划算，可以在該伺服器設定裡加 "alwaysLoad": true，讓它的工具永遠常駐 context、不經過搜尋這一步。這是拿 context 預算換即時可見性的取捨——用多了會反過來抵銷 Tool Search 省下來的 token，而且每個 alwaysLoad 的伺服器，啟動時都可能讓你多等最多 5 秒去等它連上，建議只留給真正每回合都要用的那一兩個工具。

9.10　小結