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