生活分享

Claude Code|遠端 MCP 登入、授權範圍與重新認證

在測試服務演練連線與權限故障。遠端 MCP 連不上時,可能是網路、協定、登入或權限問題,重登不一定能全部解決。本篇先用本機假服務辨認 401、403 與連線錯誤,再說明如何對你已取得授權的測試 MCP 服務完成登入、最小權限查詢與撤銷驗證。

閱讀時間約 7 分鐘

LINE 分享
遠端 MCP 登入、授權範圍與重新認證:文件、螢幕與完成記號的幾何插圖
圖片:Mokaair (© Mokaair)
本篇目錄
  1. 1. 先區分傳輸與認證
  2. 2. 啟動本機對照服務
  3. 3. 讀懂三種不同失敗
  4. 4. 加入已授權的真實測試 MCP
  5. 5. 核對授權畫面與第一筆查詢
  6. 6. 過期、撤銷與重新認證
  7. 7. 把本機狀態碼練習接到遠端驗證表
  8. 8. 完成判準與排錯表

遠端 連不上時,可能是網路、協定、登入或權限問題,重登不一定能全部解決。本篇先用本機假服務辨認 401、403 與連線錯誤,再說明如何對你已取得授權的測試 MCP 服務完成登入、最小權限查詢與撤銷驗證。

先讀、及。下載第 81 篇材料,開啟 starter。需要 Node.js 22;真實 OAuth 部分另需服務提供者的測試 HTTPS 端點、測試帳號及授權權限。閱讀約 20 分鐘,實作約 75 分鐘。

先區分傳輸與認證

先區分傳輸與認證 → 啟動本機對照服務 → 讀懂三種不同失敗
先區分傳輸與認證 → 啟動本機對照服務 → 讀懂三種不同失敗 · 圖片:Mokaair (© Mokaair)
閱讀完整文字說明

遠端 MCP 登入、授權範圍與重新認證,以流程和文件圖形呈現教學重點。

stdio 與 HTTP 描述客戶端和伺服器如何交換訊息;OAuth、權杖與登入流程則決定誰可以使用服務。HTTP 服務不一定支援 OAuth,也不代表網址能開就符合 MCP 協定。應從服務官方文件確認端點、傳輸及認證要求,不能猜一個 /mcp 路徑就開始測試。

這份下載包提供 auth-fixture.mjs,它只是一個本機 HTTP 認證示例,明確不是 OAuth,也不是 MCP 伺服器。它沒有真正的登入頁、授權伺服器、權杖更新或撤銷流程。完成這段只能標為理解錯誤分類,不能算真實 MCP OAuth 已驗收。

真實部分需要你自己控制或已獲准使用的測試服務。沒有這個前提時,先完成本機分類與紀錄表,將遠端授權欄位保留待測。不要使用生產機密或陌生人的服務嘗試權限,也不要把測試權杖放入文章、Git 或網址查詢字串。

啟動本機對照服務

在一個終端機執行 auth-fixture。程式只綁定 127.0.0.1,作業系統會分配一個空閒埠;把當次輸出的網址記到私人練習筆記。不要照抄另一輪的埠號,因為每次啟動可能不同。

專案終端機 A:保持開啟直到測試完成 · text
node mcp/auth-fixture.mjs

在第二個終端機使用 Node fetch 測試,或執行附帶的 environment 測試。自動測試會自己啟動服務並取得埠號,依序送出沒有權杖、錯誤權杖及正確的課程假權杖,完成後停止自己啟動的程序。

專案終端機 B:自動驗證假服務的三種回應 · text
node --test tests/environment.test.mjs

此檔也包含 MCP 故障客戶端測試,先執行 npm ci --ignore-scripts 安裝鎖定依賴。輸出中的假服務測試通過,證明其固定 401、403、200 行為符合教材。它不會存取外部帳號,不能拿這份輸出替代後面的真實認證紀錄。

讀懂三種不同失敗

沒有 Authorization 時,假服務回傳 401;給錯誤的示例值則回傳 403;Bearer read-demo 才得到 200 與 fixture=true。這是為了教分類而設計的契約,真實服務可能對過期權杖回傳不同細節,應查該服務的文件和回應。

401 常表示需要有效認證;403 常表示身分已辨識但操作或資源不被允許。然而不能只看數字就確定根因,還要檢查回應內容、授權來源與服務要求。網路 timeout、DNS 或 TLS 失敗通常還沒拿到這類 HTTP 回應,應先查連線層。

範例:本機假服務缺少權杖的回應 · json
{"error":"missing_token","fixture":true}

測完在終端機 A 按 Ctrl+C,再連線應失敗。這個前後比較讓你確認「服務關閉」與「服務仍在但拒絕授權」不同。不要在服務已停止時反覆更新認證,因為那不會修復缺少的網路端點。

加入已授權的真實測試 MCP

向你的服務文件或管理者取得測試 HTTPS 端點,確認允許使用的資料和操作。先選唯讀工具,不要一開始就測新增、刪除或寄送。記錄提供者、端點來源、帳號種類與預期 scope,將需要的條件寫清楚。

下方 PowerShell 會讓你輸入已確認的網址,再以 local 範圍加入本機設定。網址是資料,沒有拼成可執行的 shell 字串。請勿輸入帶有帳密的 URL;若提供者要求其他認證設定,先依其正式說明處理,不能把所有服務都假定為相同流程。

PowerShell:輸入自己的測試 HTTPS MCP 端點 · powershell
$labMcpUrl = Read-Host '輸入已授權的測試 MCP HTTPS 網址'
$labMcpUri = [Uri]$labMcpUrl
if ($labMcpUri.Scheme -ne 'https' -or $labMcpUri.UserInfo) { throw '需要不含帳密的 HTTPS 網址' }
claude mcp add --transport http --scope local lab-remote $labMcpUrl

macOS 或 Linux 可用相同 claude mcp add 參數,將已確認的 HTTPS 網址作為最後一個加引號的參數。這一步保存連線設定,不表示已登入。啟動 Claude 後進入 /mcp,選擇該服務提供的認證流程;若沒有認證入口,先核對它是否支援 OAuth 及當前傳輸。

核對授權畫面與第一筆查詢

在服務提供者的授權畫面確認網域、帳號與 scope。若實驗只需要讀取測試待辦,不應因為方便就授予管理或寫入整個組織的權限。若服務只能提供較寬權限,先記錄限制並使用獨立測試資料,不把它說成已做到最小範圍。

授權完成後回到 Claude,先列出可用工具,再呼叫一個結果已知的唯讀查詢。驗收需要工具名稱、輸入、實際結果與資源是否正確,不能只看到 Connected 就完成。可用的方式驗證空值與資料邊界。

Claude Code 對話框:真實服務的首次唯讀驗證 · text
使用 lab-remote 的唯讀工具查詢我已指定的測試資源。
先說明將使用的工具與所需權限,再執行一次查詢。
回報實際工具結果,不修改資料,也不擴大到其他工作區。
若缺少資源識別碼,先要求補充。

把這份結果與授權前狀態比較。若登入成功但仍得到 403,檢查 scope、資源成員資格及工作區是否正確。不要不停重登相同權限;新的認證不會自動讓帳號成為另一個工作區的成員。

過期、撤銷與重新認證

權杖過期與撤銷要用服務支援的測試方式演練,不以隨便改一段本機字串假裝完成 OAuth 撤銷。到提供者的已授權應用管理位置撤銷測試連線,再回到 Claude 重新呼叫同一唯讀工具,記錄是否被拒絕、是否要求重新登入,以及舊工作階段是否仍有暫存結果。

重新認證後再次查詢同一資源,確認結果恢復。不要只讀先前對話中的舊資料當成新呼叫;工具紀錄應有本次實際請求。若提供者有撤銷延遲,依文件等待並標明時間,不宣稱按下撤銷後所有權杖必定立即失效。

完成後依服務管理介面撤銷本次測試授權,再移除本機 lab-remote 設定。移除設定與提供者撤銷是兩件事,前者不必然讓已核發權杖失效。也不要刪除整個個人認證目錄,造成其他連線中斷。

把本機狀態碼練習接到遠端驗證表

實際遠端服務可能多出重新導向、權杖期限與組織政策,因此本機 401、403、200 結果只是理解狀態差異的起點。遠端驗證表至少列出端點、授權方式、成功工具呼叫及撤銷後結果;秘密值只記是否已提供,不複製到文章或報告。

若瀏覽器顯示登入成功但工具仍不能使用,重新查看用戶端錯誤與伺服器允許的權限範圍。登入頁完成不等於工具操作成功,最後仍需要一筆可核對的讀取結果。

完成判準與排錯表

階段應保留的結果常見下一步
網路連線是否收到 HTTP 回應查服務、網址、TLS
認證登入前後差異查提供者與有效權杖
授權已知資源的實際結果查 scope、成員資格
撤銷新請求被拒絕或重新認證查撤銷狀態與延遲

交付內容包含本機錯誤分類、真實服務前提、授權前後與撤銷後紀錄。真實服務尚未具備時,明確寫「本機假服務完成,OAuth 待測」,不要將兩者合併為全部通過。小練習是將一次失敗依階段定位,說明為何重登會或不會解決,再接續。

覺得這篇整理實用嗎?分享給需要的朋友

LINE 分享

回總目錄

  • 生活分享

    Claude Code|建立第一個 mod:在 Claude Code 行程內數工具呼叫

    寫一個三檔案的 mod,用驗證器與測試確認它掛上的事件。文件把 mod 定義成多了入口檔的 plugin:入口檔叫 hooks module,Claude Code 在事件發生時呼叫裡面的函式,函式可以觀察、改寫或接手事件。

  • 生活分享

    Claude Code|Git Worktree 平行工作

    隔離多個任務的檔案與分支。Git Worktree 讓同一儲存庫擁有多個工作目錄,各自使用分支與檔案。本篇會把待辦篩選與文件整理分開,確認兩個 session 不會直接改到彼此的檔案,再把其中一個成果整合回主分支。你也會知道何時可以安全清理工作目錄。

  • 生活分享

    Claude Code|雙 Worktree 實作與衝突整合

    隔離兩項功能,最後完成整合與回歸。兩個 Claude 工作階段同時編輯專案,最容易出現的問題是互相改到同一份檔案,或各自測試通過、整合後卻失敗。本篇用兩個 Worktree 分別處理篩選預設值與介面文字,故意製造一次小衝突,再完成整合、驗證與清理。你不需要先啟用 Agent Teams。

  • 生活分享

    Claude Code|比較流程品質、用量與執行時間

    以同一資料集比較兩種工作方法。比較兩種 Claude 工作方法時,不能只挑成功那一次,也不能只看第一個答案有多快。本篇用固定案例、原始紀錄和一致判準,比較品質、重試、等待與人工整合時間,最後寫出有樣本數與限制的報告,而不是保證某個方法一定省錢。

資料來源

本文依據上方所列參考來源與標示之核對日期整理;票價、時刻、功能規格或服務條款可能變動,出發、預訂或購買前請至相關官方網站確認最新資訊。

生活分享