Claude Code｜MCP 安裝、設定與排錯

MCP 排錯要把設定、程序、網路、登入與資料權限逐層拆開。本篇延續 notion-lab，也說明本機 stdio 伺服器的差異。你會建立一份可交給維護者的診斷紀錄，指出哪一層已通過、哪一層失敗，避免反覆重裝卻沒有新證據。

先閱讀MCP 入門。本篇不提供通用權杖或隨機套件安裝命令；伺服器啟動方式必須來自該服務的官方文件。處理真實帳號時，分享錯誤前先移除權杖、授權碼、私人 URL 參數與內容。

先確認設定存在哪裡

閱讀完整文字說明

MCP 安裝、設定與排錯，以流程和文件圖形呈現教學重點。

local 範圍是目前專案的個人設定，project 範圍使用專案 .mcp.json，適合團隊共享伺服器宣告，user 範圍則可跨專案使用。相同名稱出現在多個範圍時可能覆蓋，排錯時先查清有效來源，再修改正確位置。

claude mcp list
claude mcp get notion-lab

記錄名稱、transport、URL 或啟動命令與狀態，不把完整憑證貼進聊天。若 list 看不到伺服器，先確認目前目錄是不是加入 local 設定時的專案；換一個資料夾並不保證會看見相同 local 連線。

理解 project 設定格式

下面是只有遠端端點、沒有金鑰的專案範例。需要共享時才放入 .mcp.json，並依工作區信任提示確認載入。從陌生儲存庫取得的 .mcp.json 可能包含啟動本機程式的命令，應先閱讀再接受。

{
  "mcpServers": {
    "notion-lab": {
      "type": "http",
      "url": "https://mcp.notion.com/mcp"
    }
  }
}

使用此範例前，先備份現有設定並確認沒有其他伺服器要保留。不要為了測試把原 mcpServers 整個覆蓋。若服務需要 header 或環境變數，依官方支援的變數引用方式提供，不把真實秘密提交到版本庫。

遠端連線逐層檢查

第一層是端點。確認使用的是 MCP 專用 URL，不是服務首頁或一般 REST API。第二層是 transport，HTTP 與舊 SSE 端點的支援可能依版本不同；先按服務文件明確設定，不因瀏覽器能開首頁就認定 MCP 協定成功。

第三層是登入，在 /mcp 內查看是否需要認證、授權失效或連線重試。第四層才是資料權限：一個工具可以成功列出清單，仍可能無法讀取指定私密頁。每層都保存一個具體結果，才知道下一步應找網路管理者、帳號管理者還是伺服器維護者。

請先查看 notion-lab 的可用工具及目前連線狀態。
只嘗試讀取我提供的測試頁，不進行寫入。
若失敗，區分連線、認證、授權或找不到資料；附上可分享的錯誤摘要。
不要反覆重試，不要把權杖或完整私人內容放進回報。

本機 stdio 的不同問題

stdio 模式需要啟動一個本機程序。claude mcp add 中的雙連字元分隔 Claude 的選項與伺服器命令，後面的參數交給伺服器。套件名稱、版本與啟動參數都必須照官方文件，不可把遠端 HTTP URL 當作本機可執行檔。

先在相同終端機確認程式與執行環境存在。桌面 App、原生 Windows、WSL 與遠端主機的 PATH 不一定相同；在 Windows 安裝 Node，不能證明 WSL 中也能找到 Node。程序啟動失敗時，先重現官方的最小啟動方式，再檢查 Claude 設定。

stdio 的標準輸出是協定通道，伺服器不能任意插入一般歡迎文字，否則可能造成解析錯誤。診斷紀錄通常應寫到標準錯誤或指定檔案。若自行寫伺服器，先用協定工具驗證，再把它接入 Claude，減少同時排查兩端的困難。

對照症狀與處理層級

timeout 不應一律調成很大的數字。若伺服器根本沒有啟動，延長等待只會讓錯誤更晚出現。先保留一次完整但去除秘密的失敗紀錄，確認問題能穩定重現，再做單一變更並比較結果。

修正時一次只改一層，例如先修正 URL，再重新連線；不要同時換 transport、權杖與帳號。若一次改太多，即使成功也無法知道真正原因，未來遇到相同症狀仍要從頭猜測。

公司代理伺服器、憑證檢查與防火牆也可能影響連線。遇到這類錯誤，保存去除秘密的網域、時間與錯誤碼，交由環境管理者核對。不要關閉憑證驗證或把私人權杖傳給不明中繼服務來測試。

恢復原設定前，先保存本次有效差異與測試結果；如果只是暫時停用故障伺服器，也應在筆記中寫明，避免下一個 session 的使用者以為它仍然可用。

完成一份診斷紀錄

日期與 Claude Code 版本：
平台與啟動方式：
伺服器名稱、範圍與 transport：
設定是否存在：
連線與認證狀態：
最小只讀操作與預期結果：
實際結果及去除秘密後的錯誤：
本次只改了什麼：
重測結果與下一步：

完成判準是能成功執行一次預期的工具操作，或將問題縮小到有證據的具體層級。只看到設定存在不算修好；如果服務本身不可用，清楚記錄外部阻塞即可，不要回報虛構成功。需要暫停時移除或停用對應設定，並另外處理服務端授權。

小練習是在測試專案比較 local 與 project 範圍，保存同名設定的有效來源，再恢復單一來源。接著可用Plugins 管理了解打包分發，但外掛安裝完成後仍要重新通過這裡的連線與操作驗證。

回 Claude Code 教學總目錄

• AI 工具
• 教學
• Claude Code