MCP 連線診斷與故障復原

返回 Codex 教學總目錄

目標與準備

本段提到的教學與資源: MCP 入門

步驟 1：先查設定，別急著改逾時

codex --version
codex mcp get codexLearningDocs
codex mcp list

確認輸出中的名稱、enabled、傳輸方式與 URL，並記下本機還是遠端主機、CLI 或桌面入口，以及最後一次重新啟動的時間。若 get 找不到名稱，回到實際 config.toml；拼字、使用者層與專案層，以及自訂 CODEX_HOME 都要逐項核對。桌面、CLI、IDE 只有在同一 Codex 主機下才共用設定，Windows 原生與 WSL 的家目錄也不能當成同一個位置。

設定檔解析失敗時，先處理行號附近的引號、重複表格或錯誤類型，再談網路。用設定篇的方法保存自己的修改前副本，只修改練習區段；不要把整份設定貼上公開求助。若檔案能解析但名稱仍不見，檢查可信任專案的載入與當前工作目錄，並確認編輯器保存的是實際檔案，不是另一份備份。

公開文件服務沒有認證要求時，該欄填「不需要」，不是漏做登入。

步驟 2：重現工具被停用的情況

先用前篇的唯讀問題取得一次正常結果並保存原設定。既有練習區段已有 enabled 時把原值改為 false；沒有才新增一次 enabled = false，不能重複鍵或表格。桌面按 MCP 設定中的 Restart，IDE 重新啟動擴充套件，CLI 結束後開新工作階段。不要只在舊對話重新問一句，因為它仍可能引用已讀過的內容。這個練習刻意讓伺服器不可用，不代表遠端官方服務真的壞了。

[mcp_servers.codexLearningDocs]
url = "https://developers.openai.com/mcp"
enabled = false

/mcp

/mcp 可在桌面版、CLI、IDE 的 Codex 輸入框使用，不是終端機命令。重新啟動後，在新任務／工作階段同時用 /mcp、MCP servers 設定與實際工具活動確認停用。記錄「客戶端未提供工具」即可；跨入口測試要另記主機與設定位置。

預期新工作階段不再提供這個已停用伺服器的工具。此時即使 get 仍列出它，也符合預期：設定存在與工具可用是不同狀態。把 enabled 改回 true 或移除這次加入的 false，重新啟動後重做查詢並核對官方原文。保存「正常 → 停用 → 恢復」三個結果，不能只保存最後成功畫面，否則看不出故障演練是否真的生效。

步驟 3：區分 STDIO 啟動與 HTTP 連線

如果你使用其他 STDIO 伺服器，先看 command、args 與 cwd。Windows 用 Get-Command 查啟動程式，macOS、Linux 用 command -v；這只證明目前終端機找得到程式，不保證從桌面啟動的程序 PATH 完全一樣。相對路徑會受工作目錄影響，檔案不存在先修正路徑；需要 Node.js 的伺服器則核對 Node 版本。不要為檔名打錯直接拉長啟動逾時。

Get-Command node
node --version

command -v node
node --version

STDIO 伺服器把標準輸入輸出當協定通道，額外印出歡迎文字或除錯資料可能干擾連線。若你維護該伺服器，依其官方實作把一般紀錄寫到 stderr；若只是使用者，記錄啟動錯誤交給提供者，不要隨意改第三方套件內容。手動啟動後等待輸入而沒有文字，不必然是當機；看到程序活著也不等於 MCP 已成功初始化。

HTTP 則先核對完整協定、主機、路徑，例如本篇必須是官方 /mcp 端點。瀏覽器能開網站首頁，只能證明部分網路可達，不能證明 MCP 請求、代理設定與驗證都成功。TLS 錯誤應檢查系統時間、公司代理與憑證信任設定；先向環境維護者確認，不把關閉憑證驗證當成教學預設。暫時連不上時保留時間與遮蔽後錯誤再重試。

步驟 4：認證、工具篩選與逾時

需要 OAuth 的服務可以在客戶端按 Authenticate，或先查 codex mcp login --help 再以自己的伺服器名稱登入。要用哪個帳號、哪些權限，以及回呼網址都依提供者規格；若需要預先註冊 client ID，就註冊 Codex 顯示的完整回呼網址，不能猜固定埠或把 localhost 和 127.0.0.1 任意互換。公開 Docs MCP 不用這項登入練習。

認證已完成但看不到某個工具時，查看 enabled_tools、disabled_tools 與插件本身的工具政策。允許清單不會創造伺服器沒有提供的能力；同名工具同時列在兩份清單時，停用清單在允許清單之後套用。先用目前工具目錄取得真正名稱，不要猜成 search 或 read。插件提供的伺服器另有插件層設定，使用者設定不負責改寫它的啟動命令，詳見 Plugins 排除問題。

啟動逾時與工具執行逾時是不同階段：startup_timeout_sec 只處理初始化等待，tool_timeout_sec 處理單次工具。先確認程式、網址、認證都對，再用較小的唯讀請求判斷是否只是工作太大；只有確定是合理等待不足才調整那個伺服器的值並重測。optional startup grace 與 required 也會影響啟動時的行為，新手不必把所有伺服器改成 required；無法啟動的重要服務應保留錯誤並停止依賴它的工作。

收尾：可交接的故障紀錄

# MCP recovery record
Surface / OS / client version:
Host and effective config location (redacted):
Server name / transport:
Failure layer:
Original error (without secrets):
Single change:
New-session tool visibility:
Read-only request and verified source:
Normal / disabled / restored results:
Unrelated settings preserved:
Remaining limitation and next action:

如果練習改壞設定，先恢復本次練習區段，重新讀取確認；不要在其他任務同時寫設定時整檔還原。結束後按前篇移除自己新增的 codexLearningDocs 即可。OAuth 服務的 logout 用於清除該服務的已存認證，remove 用於移除設定；是否還有外部授權，要到提供者的帳號頁確認。兩者都不能撤銷已經寫進外部系統的資料，涉及寫入要依原服務自己的復原流程處理。

完成標準是能解釋哪一層失敗、提供一次可重現的停用與恢復，以及新的唯讀工具證據；只看到程序、設定檔或正確答案都不夠。尚未取得連線時保留「未完成工具驗證」，不用把未測環境填成正常。本篇產品流程依官方文件查證，本機設定與直接 MCP 協定驗證另存紀錄；macOS、Linux、IDE、OAuth 與實體手機未因這些測試而自動取得實測標記。下一步進入 Worktree 隔離。

返回 Codex 教學總目錄

閱讀完整文字說明

Three numbered stages: identify the starting point, perform the exercise, and verify the result. Original illustration, not a product screenshot.

• AI 工具
• 教學
• Codex