MCP 設定與連線排除

返回 Codex 教學總目錄

目標與準備

本段提到的教學與資源: 安裝篇

MCP 是讓客戶端呼叫工具與取得上下文的協定。伺服器提供哪些能力，取決於該伺服器；接上文件服務不會自動取得你的 GitHub 或本機瀏覽器。OpenAI Docs MCP 提供文件搜尋與原文內容，不會代你呼叫 OpenAI API。本篇用它練習讀取驗收；日後換成會寫入資料的服務，仍須重新檢查工具與權限範圍。

步驟 1：選擇傳輸方式與設定位置

本篇只做 Streamable HTTP。一般網站首頁不等於 MCP 網址，必須使用服務官方列出的端點；也不能把 STDIO 的 command 貼到 URL 欄。

同一 Codex 主機的桌面版、CLI、IDE 共用 MCP 設定。預設使用者設定為 ~/.codex/config.toml；Windows 通常在使用者資料夾下的 .codex，macOS、Linux 同樣在自己的家目錄。若已設定自訂 CODEX_HOME，請依實際位置確認。可信任專案也能用 .codex/config.toml；本篇沿用使用者層設定，不在不明來源專案內調整。位置判斷見 config.toml。

步驟 2：先檢查既有項目，再新增

codex mcp list

在 Windows PowerShell、macOS 終端機或 Linux 終端機執行上面的命令。這是管理命令，不需先進入 codex 對話。檢查是否已有 codexLearningDocs；若有同名項目，先看詳情，不要覆寫。已有相同官方網址的可用項目也能直接使用其現有名稱，並在驗收紀錄寫明「沿用既有設定」，收尾時保留它。列表可能含私人服務網址，不要直接公開整份輸出。

若確定要新增，先在編輯器開啟實際使用者 config.toml，將現有檔案另存一份有日期且不覆蓋舊檔的備份。檔案原本不存在就記錄此狀態，不必自行建立空設定。只做這次單一變更，保存前後差異；備份可能含敏感值，放在自己的本機資料夾，不加入 Git。完成練習時優先移除新增的單一區段，避免用舊備份覆蓋其他任務剛加入的設定。

codex mcp add codexLearningDocs --url https://developers.openai.com/mcp
codex mcp get codexLearningDocs

預期 get 顯示名稱、HTTP 傳輸與完全相同的官方網址。這時只能勾選「設定保存成功」，尚未證明伺服器可達、工具列出或查詢成功。實際工具數量會改變，不抄教材中的固定數字；管理命令回傳零也不能作為讀取證據。若命令不存在，先用 codex mcp --help 確認版本與可用命令，再回到 CLI 更新說明。

桌面與 IDE 的相同步驟

不使用 CLI 時，桌面版到 Settings → MCP servers → Add server；輸入 codexLearningDocs，選 Streamable HTTP，貼上同一官方網址後保存，再按 Restart。IDE 從齒輪選 MCP servers → Add server，欄位相同，保存後按 Restart extension。Windows、macOS、Linux 使用其實際可用客戶端完成相同步驟；Linux 預覽或版本中沒有這個入口時可改用 CLI，不把缺少 UI 按鈕誤判為服務故障。

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

上面是同一設定的檔案表示，CLI、UI、手動編輯三條路選一條即可。不要先用命令新增又把相同 TOML 表格貼一次，重複表格可能使設定無法解析。若要手動編輯，只合併該區段後重新啟動客戶端。ChatGPT 網頁與手機不讀取你電腦的本機 config.toml；網頁的外部能力走 Plugins，不能因本機成功就宣稱手機也已設定。

步驟 3：確認工具並查詢原文

/mcp

在桌面版、CLI 或 IDE 的新任務／工作階段輸入 /mcp，查看練習伺服器與當下工具；這是 Codex 輸入框指令，不是終端機命令。也可回到 MCP servers 設定頁確認狀態，再觀察新任務的實際工具活動。若要求認證，先核對公開端點。其他 OAuth 服務可能需要 Authenticate 或 codex mcp login 名稱，本篇公開文件服務不需任意填入 API key。

Use the codexLearningDocs MCP tools to find the official AGENTS.md instructions.
Read the relevant page and explain global versus project rules in three bullets.
Include the source URL and the section you checked.
If the MCP tools are unavailable, report that limitation instead of answering from memory.
Do not edit files or call paid APIs.

如果沿用既有伺服器，先把提示詞中的名稱替換成那個名稱。觀察至少一次搜尋或讀取工具的活動，再打開回覆的官方來源，確認段落確實支持全域與專案規則的說明。模型回覆格式可能不同，驗收重點是工具證據、網址與內容一致，不是一定三句或固定工具名稱。回答雖然正確但沒有經過 MCP，應記為一般回答，這次連線練習仍未完成。

步驟 4：停用、重測與移除

失敗對照只改自己新增的項目：原區段已有 enabled 就把該值改成 false；沒有才新增一次 enabled = false，不能重複鍵或表格。也可使用客戶端停用控制。保存並重新啟動後，在桌面版、CLI 或 IDE 的新任務／工作階段用 /mcp 和實際工具活動確認不再提供該工具。舊對話文字不算新讀取。恢復時還原原值，或只移除這次新增的 enabled 鍵，再重新啟動並重做讀取。

codex mcp remove codexLearningDocs
codex mcp list

移除後新任務應不再列出這個新增項目；這不會移除其他伺服器、刪除文件或撤銷別的 OAuth 授權。如果原先只是沿用既有項目，跳過移除並保留原狀。本篇若未變更設定，收尾紀錄就寫未變更。對有登入的其他服務，remove 與 logout 的目的不同，請依 MCP 排除問題 核對，而不是一口氣清空所有連線。

常見問題與完成判準

找不到伺服器時先查設定層級、名稱、enabled 與是否重新啟動；出現 TOML 解析錯誤時看重複表格與引號，不要重置整檔；設定正確但連不上時核對完整 URL、目前主機網路與服務狀態，再保存遮蔽後錯誤。工具回覆沒有來源，則重問讀取原文並核對連結，不把模糊答案當通過。這四類問題分別有不同證據，全部改成放寬權限通常不能解釋原因。

驗收至少記錄實際客戶端版本、設定保存、一次帶來源的工具結果，以及自己新增項目的停用或移除結果。Windows 的獨立設定測試與公開服務協定測試可另外記錄，但不等同於桌面 UI、macOS、Linux 或你的模型任務已實測；無法操作的入口依官方文件查證。接續用連線檢查範本保存結果，遇到問題再進下一篇。

返回 Codex 教學總目錄

閱讀完整文字說明

Configuration to Handshake to Tool result

• AI 工具
• 教學
• Codex