本文目錄

想讓 Claude Code 查 issue、讀資料庫或存取監控服務，不必每次都把結果複製進對話。MCP 是開放的工具接入協議，伺服器把相應能力交給 Claude Code 使用。能讀什麼、能改什麼，取決於伺服器提供的工具和你授予的權限。

第一次接入，最容易混在一起的是三個問題：地址或啟動命令有沒有登記、伺服器能不能連上、工具有沒有真的被呼叫。把這三步分開，比一次加很多服務更容易找出問題。我們暫時未實際執行這些示例。

先用文件伺服器走完一遍

先安裝 Claude Code 並完成它自身的登入，再在準備使用 MCP 的專案目錄開啟終端。空目錄也可以。下面的命令要在終端執行，不要貼到已經開啟的 claude 工作階段裡：

bash
claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

這是官方 quickstart 用來示範首次連線的文件 MCP，提供 Claude Code 文件全文檢索，不需要額外帳號或 token。claude-code-docs 是你給伺服器起的名字，不是固定關鍵字；--transport http 表示按 URL 連線託管服務，而不是在本機啟動行程。

命令成功時會顯示 Added ...，並用 File modified: 告訴你寫入哪個檔案。先別把它當作“接通了”：Added 只代表設定已儲存，新增時不會替你驗證憑證。接著執行：

bash
claude mcp list
claude mcp get claude-code-docs

文件伺服器預期顯示 ✔ Connected。再執行 claude，輸入 Use the claude-code-docs server to look up what MCP_TIMEOUT does。這裡特地點名，是為了讓這次請求明確使用剛加的伺服器。若出現工具權限提示，讀清內容後再批准；看工具呼叫旁有沒有伺服器名，不要只憑答案像是對的就認定走了 MCP。

試完不想保留，可以執行 claude mcp remove claude-code-docs。每個伺服器的工具名稱和說明會佔一些上下文，沒用的伺服器不用一直留著。

拿到的是 URL，還是一條啟動命令？

先看服務提供方給的接入說明，再選傳輸方式。遠端地址與本機命令不是同一種輸入。

手上的設定通常怎麼選需要注意
HTTPS MCP 地址HTTP，使用 --transport http優先選遠端服務提供的 HTTP 介面
SSE 地址HTTP 自動回退，或 --transport sse自動回退需要 v2.1.265 或更新版本
npx、uvx 或可執行程式命令stdio啟動命令完整放在 -- 後面
要主動推送事件的 WebSocket 地址JSON 的 "type": "ws"不接受 --transport ws，也不支援 OAuth

遠端優先 HTTP。 JSON 中可以寫 "type": "http"，也接受別名 "streamable-http"。只寫 url 卻省掉 type 會出錯：Claude Code 把沒有 type 的條目當成 stdio，因而跳過這條遠端設定。

SSE 非推薦，但並非不能用。 官方標記為 deprecated，意思是有 HTTP 就優先 HTTP。Claude Code v2.1.265 起，--transport http 會先試 HTTP，對方不接受再改走 SSE；更早版本，或者明確要直接走 SSE，可以用 --transport sse。舊版請直接指定 SSE，不要依賴自動回退。

本地行程用 stdio。 官方 quickstart 的例子是 Playwright，需要 Node.js 18 或更新版本：

bash
claude mcp add playwright -- npx -y @playwright/mcp@latest

-- 後面的內容原樣交給伺服器啟動命令。漏掉分隔符，伺服器自己的選項可能被 Claude Code 當成自己的引數。第一次檢查狀態時，npx 可能還在下載套件，出現失敗可以等下載完成再查。選擇套件之前也要確認信任來源，因為這會在你的電腦上執行程式。

WebSocket 不等於普通遠端 HTTP。 它適合伺服器主動推事件；如果只是你發請求、服務回結果，HTTP 更直接。WebSocket 要透過 .mcp.json 或 claude mcp add-json 設定 "type": "ws"，認證只走請求頭，可使用 headers 或連線時生成請求頭的 headersHelper。claude mcp add --transport 不接受 ws，瀏覽器 OAuth 也不能套到 WebSocket 上。

local、project、user 選錯，會像是設定丟了

傳輸方式決定怎麼連線，作用域決定這份設定在哪兒生效。local 範圍的 HTTP 伺服器仍在遠端，“local”不是“本機 stdio”的另一個名字。

作用域誰能用、在哪兒用設定位置
local，預設只有你，只在當前專案~/.claude.json 裡這個專案的條目
project當前專案的使用者，可隨倉庫共享專案根目錄 .mcp.json
user只有你，所有專案~/.claude.json 頂層 mcpServers

個人先試用選 local；團隊要重用同一組服務選 project；你在不同專案都要用的個人工具選 user。MCP 的 local 設定不在 .claude/settings.local.json。Windows 的 ~/.claude.json 對應 %USERPROFILE%\.claude.json；設了 CLAUDE_CONFIG_DIR，則到指定目錄下找 .claude.json。

作用域在新增時確定。要把剛才的文件伺服器從 local 改成 user，先刪原條目，再按新範圍新增：

bash
claude mcp remove claude-code-docs --scope local
claude mcp add --scope user --transport http claude-code-docs https://code.claude.com/docs/mcp

共享給專案成員則改用 --scope project。同名伺服器同時存在時，local 優先於 project，project 優先於 user；採用的是整條定義，不是把幾份設定的欄位拼起來。其他普通來源低於這三種作用域，組織透過 managedMcpServers 提供的定義則在 v2.1.259 起優先於它們。改了 URL 卻沒變化時，先確認實際生效的是哪一份，而不是反覆修改被覆蓋的設定。

手寫 JSON 時，檔案位置和外層鍵都要對

專案設定應放在倉庫根目錄 .mcp.json，不是 .claude/ 目錄。只新增文件伺服器可以寫成：

json
{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    }
  }
}

外層鍵叫 mcpServers，不是其他客戶端可能使用的 servers；把 mcpServers 放進 settings.json 也不會被讀取。儲存後退出並重開工作階段，Claude Code 在啟動時讀取 .mcp.json。

互動工作階段第一次使用專案級伺服器，會要求批准。先檢查倉庫裡給出的 URL 或啟動命令再決定，不要因為檔案隨程式碼一起克隆下來就直接信任。關掉過批准提示，可以到 /mcp 處理；要重置之前的選擇，使用 claude mcp reset-project-choices。非互動的 claude -p 無法彈出這種提示，會直接載入專案伺服器，因此自動執行之前尤其要看過共享設定。

如果提供方只給了另一個客戶端的 JSON，想改用 claude mcp add-json，應傳入 mcpServers 裡面單個伺服器的定義，不要連最外層一起塞入。名稱只用字母、數字、連字元或底線。

登入要先分清 OAuth 與請求頭 token

需要 OAuth 的遠端服務，加完地址後顯示 ! Needs authentication，往往只是提醒你還差登入一步。在 Claude Code 工作階段輸入 /mcp，選伺服器，再選 Authenticate，按瀏覽器提示完成授權。也可以在有互動終端的 shell 執行 claude mcp login <name>，把 <name> 換成剛才登記的名稱。

瀏覽器沒有自動開啟，可以使用 Claude Code 顯示的授權 URL。若授權後瀏覽器回跳失敗，按 Claude Code 的提示貼上位址列中的完整回呼 URL，不要把這個 URL 發進工單或聊天。claude -p 沒有 /mcp 面板，應該先在互動工作階段或透過登入命令完成認證，再啟動非互動任務。

另一類服務要求固定 token，透過 --header 新增。以下地址、名稱和 token 都是佔位示例，需要換成服務提供方給你的值，不能原樣當作可用憑證：

bash
claude mcp add --transport http secure-api https://api.example.com/mcp --header "Authorization: Bearer your-token"

不要把真實 token 提交進共享設定。JSON 可以引用環境變數，例如 "Authorization": "Bearer ${API_KEY}"，API_KEY 是你為這個伺服器單獨準備的變數。檢查貼上內容有沒有首尾空白或換行，這類隱藏字元會導致認證失敗。

已經設定了 Authorization 請求頭，連線時卻被服務端以 401 或 403 拒絕，Claude Code 會顯示連線失敗，不會自動回退到 OAuth。該修的是這份請求頭憑證；如果本來想走 OAuth，就先去掉手寫的頭。反覆點瀏覽器登入，不會讓錯誤的固定 token 變正確。

按狀態排查，不要一上來就加超時

先用 claude mcp list 看目前專案的伺服器狀態，再用 claude mcp get <name> 看指定伺服器。工作階段內也可以開啟 /mcp。

完全沒有伺服器。 確認終端當前所在專案與新增時一致。預設 local 只跟當時的專案繫結，不在 Git 倉庫裡則跟當時的精確目錄繫結。再查檔案位置、JSON 語法和解析警告；壞掉的一條會被跳過，不代表整份檔案都沒讀。

停在批准或被策略阻止。 Pending approval 要在互動工作階段裡審閱並批准。企業策略攔截則要找管理員瞭解原因，調大超時解決不了權限問題。

Failed to connect。 先讀狀態後的 HTTP 狀態碼或失敗詳情，再用 get 檢視完整 URL，特別是 MCP 路徑。網站首頁能開啟，不代表設定的 MCP 地址正確。若是 Connection error，這個狀態不會附上詳情，需要繼續檢查網路或本機命令。

遠端可按 quickstart 建議，用 curl -I <url> 看是否有響應；PowerShell 用 curl.exe，避免命中別名。404、405 仍說明主機有響應，部分 MCP 端點只接受 POST；這不等於路徑正確或 MCP 協議已接通。401、403 指向認證，完全無響應則先查地址和網路。

stdio 啟動失敗。 把設定的命令與提供方說明對照，確認執行環境已安裝、沒有漏 --。command、args 中的相對路徑以啟動 Claude Code 的目錄為基準，不以 .mcp.json 所在位置為基準；本機腳本儘量寫絕對路徑，npx、uvx 這類在 PATH 上的命令可以保留原樣。還要確認沒有使用會禁用 MCP 的 --safe-mode。

啟動超時。 預設啟動時限是 30 秒。首次 npx 下載可能更慢，Bash、Zsh 可以用 MCP_TIMEOUT=60000 claude 放寬到 60 秒；PowerShell 用 $env:MCP_TIMEOUT = "60000"; claude。單位是毫秒。參考文件的 MCP_TIMEOUT=10000 claude 只是設成 10 秒的例子，不是預設值。v2.1.299 之前，一些實際仍在運作的 HTTP 伺服器可能不受這個設定影響仍啟動超時；符合這種情況就應更新 Claude Code，而不是不斷加大數字。

連線了卻沒有工具。 在 /mcp 看工具列表，檢查伺服器要求的環境變數，再選 Reconnect。仍為空可以執行 claude --debug=mcp，在 ~/.claude/debug/ 下檢視伺服器 stderr，分享日誌前移除秘密資訊。連線狀態只說明連線這一層，不保證伺服器列出了你想要的工具。

接通後，也別一次放開所有權限

先確認伺服器可信，再從一個小任務開始。會拉取外部內容的伺服器可能帶來提示注入風險，涉及寫入、刪除或外發的工具尤其要看清權限。MCP 也不會繞過 Claude Code 用量限制。

若下一步關心長任務怎麼執行、任務途中如何要輸入，可以再看 MCP Tasks 與任務中途提問；那是接入之後的使用方式，不是首次登記伺服器的步驟。