CX-05 MCP 完整指南：在 App 中连接外部工具

本篇只讲 MCP 外部工具连接。Subagents 已单独拆到 CX-08。

主要来源：OpenAI Codex MCP 官方文档、Codex App Settings、Codex CLI MCP 命令。

课程信息

• 作者：老金
• GitHub：https://github.com/KimYx0207
• 公众号：老金带你玩AI
• X（Twitter）：老金带你玩AI
• 个人博客：https://aiking.dev
• 预计学时：2-3小时
• 难度等级：⭐⭐ 入门级
• 更新日期：2026年5月30日
• 信息来源：OpenAI Codex MCP 官方文档、Codex App Settings、Codex CLI MCP 命令
• 前置要求：已完成 CX-01 安装、CX-02 桌面工作流、CX-04 权限配置

📚 本课学习目标

完成本课学习后，你将能够：

1. 理解MCP的本质：掌握MCP是工具连接层，不是提示词，不是搜索
2. 确认MCP工具可用：通过/mcp和App Settings验证工具是否加载
3. 区分MCP与其他能力：清楚MCP、Plugins、Connectors、Skills各自的边界
4. 管理MCP权限：给MCP工具设置最小读写权限，保护生产数据
5. 理解MCP与数据库交互：默认只读，不给生产写权限
6. 学会用CLI辅助排查：知道什么时候用CLI管理MCP配置
7. 核对MCP配置：配置完成后能确认工具可见、权限正确、可审计、可撤销
8. 避免MCP常见错误：不假设自动可用、不写API Key进配置

🗺️ 学习路径导航（先看这里！）

💡 根据你的情况选择学习路径：不用全看！

路径A：快速上手（⏱️ 10分钟）

适合人群：想快速确认MCP能不能用

只看这些章节：

✅ 第1部分：MCP是什么（2分钟）
✅ 第2部分：App中的MCP工作流（5分钟）
✅ 第9部分：配置核对（3分钟）

路径B：完整学习（⏱️ 2-3小时）

适合人群：想系统掌握MCP配置和使用

学习顺序：从头到尾所有章节

术语表（小白必读）

MCP 章节最常见的误区是：把 MCP 当成“搜索”“插件”“账号连接”或“万能 API”。先把词拆开：

一句话：MCP 给 Codex “手”，Connector 给 Codex “账号上下文”，Skill 教 Codex “怎么做”，Plugin 把这些能力打包。

0. MCP 的工作机制

我在 MCP 这一讲里坚持要求列来源，是因为老金不希望读者把模型记忆当成官方证据。

一次 MCP 调用可以理解为：

你提出任务
  -> Codex 判断是否需要外部工具
  -> Codex 查看当前可用 MCP server 和工具说明
  -> 如需调用，按工具权限和 approval 设置发起调用
  -> MCP server 执行真实工具逻辑
  -> 结果回到线程，Codex 基于结果继续推理或写代码

这个流程里有三个关键点：

1. 工具是否可见：配置存在不等于 App 当前线程已经能看到。
2. 工具是否合适：能查数据库不代表应该查生产数据。
3. 结果是否可信：MCP 返回的是外部工具结果，仍要看来源、时间、权限和副作用。

0.1 MCP 适合解决的问题

0.2 MCP 配置不是最终目标

很多教程会把重点放在“怎么 add 一个 server”。但真正的学习目标应该是：你能判断这个 server 从哪里来、能做什么、能读写什么、失败时怎么排查、离职或不用时怎么撤销。

一条成熟 MCP 工作流应该包括：

来源确认
  -> 权限评估
  -> 配置
  -> App 可见性核对
  -> 只读试跑
  -> 写操作边界
  -> 日志和撤销方式

1. MCP 是什么

MCP 是 Model Context Protocol。它让 Codex 借助标准协议连接外部工具，例如：

• 浏览器自动化。
• 数据库查询。
• 内部 API。
• 文档系统。
• 设计工具。
• GitHub / issue / PR 工具。

一句话：MCP 不是提示词，而是工具连接层。

2. App 中的 MCP 工作流

App 主线应该这样学：

1. 在 App Settings 或集成入口启用 / 配置 MCP。
2. 回到线程。
3. 用 /mcp 查看当前可见工具。
4. 用自然语言要求 Codex 使用工具。
5. 观察工具调用和权限提示。
6. Review 结果。

示例：

使用当前可用的文档 MCP，核对 README 里的安装步骤是否和官方文档一致。只读，不修改文件。

3. 从 0 配一个 MCP 前先确认什么

不要一上来复制一段 MCP 配置。先确认四件事：

App 里已经能通过 Connector / Plugin 完成的事情，优先用 App 入口。MCP 更适合“需要把一个具体工具暴露给 Codex 调用”的场景。

4. App 用户常见场景

5. CLI 管理 MCP 是辅助路径

当 App 里看不到 MCP，或团队要统一配置时，才用 CLI：

codex mcp --help
codex mcp list
codex mcp add <name> -- <command>

也可以在 config.toml 中写 MCP server。具体字段以官方 Config Reference 为准。

CLI 配好后回到 App 仍要核对：

1. 重启或刷新 Codex App。
2. 打开项目线程。
3. 输入 /mcp。
4. 确认 server 名称、工具列表、连接状态。
5. 用一个只读任务试跑。

不要把“CLI 显示配置存在”当成“App 已经能用”。最终以 App 线程里能看到并成功调用为准。

6. MCP Server 类型

常见类型：

App 用户重点不是背协议，而是知道工具从哪里来、权限是什么、结果能否验证。

6.1 三类 server 的配置差异

配置里常见的安全字段包括：

• enabled：临时禁用 server，而不是删配置。
• enabled_tools / disabled_tools：限制工具集合。
• default_tools_approval_mode：决定工具默认审批行为。
• 单工具 approval override：高风险工具单独要求审批。
• startup_timeout_sec / tool_timeout_sec：避免工具卡死太久。

字段会随官方 Config Reference 更新，教程示例只讲用途，不把所有字段写成静态背诵表。

6.2 密钥和环境变量怎么放

MCP 配置里最危险的是 token。原则：

如果配置示例需要提 token，只写变量名，不写真实值：

[mcp_servers.docs]
url = "https://example.com/mcp"
bearer_token_env_var = "DOCS_MCP_TOKEN"

读者看到这段应该知道：真实 token 在环境变量里，不在教程、不在仓库、不在截图里。

7. MCP、Plugins、Connectors、Skills 的区别

不要把 MCP 当万能插件系统。如果只是写固定流程，用 Skill；如果要连接外部工具，用 MCP 或 Connector。

8. 安全边界

配置 MCP 前先问：

• 它能读什么数据？
• 它能写什么数据？
• 它是否会联网？
• 它是否需要账号授权？
• 它是否会把数据发给第三方？
• 它能不能在只读模式下完成任务？

生产数据库、客户数据、内部文档、邮箱、云盘都要按最小权限配置。

9. 配置核对

一个 MCP 配置写完后，建议按这张表核对：

9.1 MCP 排障流程

排障时不要第一步就重装。先确认“配置在哪一层、当前线程是否加载、server 是否启动、工具是否可见、调用是否被审批拦住”。

9.2 生产数据访问矩阵

MCP 的安全原则不是“绝不用”，而是“先只读、再小范围、可审计、可撤销”。

10. 课堂工坊：从只读文档工具到安全排查

案例一：用文档 MCP 做只读核对

目标：让 Codex 使用已连接的文档工具核对课程或 README，不修改文件。

1. 在 App Settings 或 /mcp 中确认文档类 MCP server 可见。
2. 在项目线程发送：

使用当前可用的文档 MCP，核对 README 里的安装命令是否和官方文档一致。只读，不修改文件。请列出你查询到的来源和 README 中需要关注的行。

你应该看到：Codex 明确调用了文档工具，输出来源、差异和建议；Review 面板没有新增 diff。

案例二：数据库 MCP 只读查 schema

目标：练习“查数据库”和“改数据库”之间的权限边界。

使用当前数据库 MCP 只读查看用户表相关 schema。只输出字段名、字段含义推测和需要人工确认的点。不要写入数据库，不要导出用户数据。

你应该看到：任务只做 schema 或元数据读取；如果工具要求写权限、生产库权限或导出数据，应取消并改成只读连接。

案例三：MCP 不可见时的排查顺序

目标：不用猜配置，按 App 到 CLI 的顺序定位问题。

1. 在线程输入 /mcp，看 server 是否出现。
2. 如果 App 看不到，再到终端运行：

codex mcp list
codex mcp --help

3. 检查 token 是否只在环境变量或 secret 中，不在仓库文件中。
4. 重启或刷新 App 后，再用只读任务试跑。

你应该看到：CLI 和 App 对同一 server 的可见性差异被说清楚；最终以 App 线程能否调用为准。

11. MCP Cookbook：五个真实场景

MCP 的价值不在“连上了”，而在能把外部工具放进可控工作流。下面五个场景可以直接用来训练团队。

11.1 官方文档核对

适合：课程、README、SDK 用法、API 参数核对。

使用当前可用的官方文档 MCP，只读核对 docs/install.md 中的安装命令是否仍然准确。
请输出：
1. 你查询的文档来源
2. 教程中可能过期的行
3. 建议修改
不要修改文件。

关键点：必须列来源，不允许只说“官方文档显示”。

11.2 浏览器本地验证

适合：前端页面、登录流程、响应式布局。

使用当前可用的浏览器 MCP 打开 http://localhost:3000/settings。
只读检查：
1. 页面是否能打开
2. 375px 宽度下按钮文字是否溢出
3. 控制台是否有明显错误
不要修改文件。

关键点：先确认本地服务是否已启动；如果要让 Codex 启动服务，要写清命令和停止方式。

11.3 数据库 schema 只读核对

适合：确认字段、索引、迁移状态。

使用数据库 MCP 只读查看用户相关 schema。
只输出表名、字段名、索引、需要人工确认的字段含义。
不要读取用户数据行，不要导出数据，不要写入数据库。

关键点：schema 和真实用户数据要分开；生产库默认不可写。

11.4 PR / issue 上下文读取

适合：结合 GitHub issue、PR 评论、本地 diff 做判断。

使用 GitHub 相关连接器或 MCP，只读读取这个 PR 的描述和 review comments。
结合当前本地 diff，输出哪些评论已处理、哪些未处理。
不要评论 PR，不要 push。

关键点：外部评论可能过期，要和当前 diff 对照。

11.5 内部 API 诊断

适合：只读健康检查、接口元数据、测试环境状态。

使用内部 API MCP 查询测试环境的 /health 和 /version。
只输出状态码、版本号、时间戳和异常摘要。
不要调用写接口，不要访问生产环境。

关键点：内部 API MCP 要有服务端审计日志；不要把它当成万能生产运维入口。

12. MCP 设计评审清单

如果你要为团队新增一个 MCP server，先过这张表：

13. 常见错误

14. 团队 MCP 登记表

团队只要引入 MCP，就应该有一张登记表。它不必复杂，但必须能回答“谁装的、能读什么、怎么关”。

这张表能避免“某个 MCP 以前能用，但没人知道它为什么能访问生产系统”的事故。

常见问题

Q1：App 里一定能管理所有 MCP 吗？

不一定。部分配置可能需要 CLI 或 config.toml。但 App 仍是使用主线。

Q2：MCP 工具会不会自动运行？

Codex 会根据任务调用工具，但是否需要审批取决于工具、权限和设置。

Q3：MCP 和 Web search 一样吗？

不一样。Web search 是搜索网页；MCP 是连接具体工具或服务。

Q4：MCP 工具返回的内容一定可信吗？

不一定。它只是外部工具返回的结果。你仍要看来源、时间、查询条件、权限范围和是否可能被外部内容误导。

Q5：MCP 配好了为什么 Codex 还是不用？

可能是任务不需要、工具说明不清、server 不可见、权限需要审批，或 Codex 判断自然语言和本地文件足够。你可以明确要求“使用当前可用的某个 MCP，只读核对来源”。

Q6：一个 MCP server 工具越多越好吗？

不是。工具越多，选择成本和权限风险越高。团队 server 应该把常用工具命名清楚，把高风险工具单独审批或禁用。

Q7：MCP 可以替代 Connector 吗？

不一定。Connector 通常负责账号级外部上下文；MCP 负责工具调用。GitHub、Figma、文档系统等场景可能同时存在 Connector、Plugin 和 MCP，先选官方推荐和团队已治理的路径。

15. MCP 深入：它不是搜索框，而是工具协议

MCP 的全称是 Model Context Protocol。学习时不要把它简化成“给 Codex 上网查资料”。MCP 更像一个标准接口，让 Codex 可以连接外部工具、上下文和服务。

15.1 MCP 能给 Codex 什么

15.2 MCP 不自动等于可信

MCP 返回的是外部系统给的信息。Codex 仍然要判断：

- 这个 server 是否可信？
- 工具返回的内容是否完整？
- 是否有权限或分页限制？
- 是否可能是过期缓存？
- 是否需要和本地文件交叉核对？

课程里要强调：MCP 是“接入能力”，不是“事实保证”。

16. MCP Server 类型详解

Codex 支持常见的 STDIO server 和 streamable HTTP server。学习时可以这样理解：

16.1 STDIO 示例

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env_vars = ["LOCAL_TOKEN"]
 
[mcp_servers.context7.env]
MY_ENV_VAR = "MY_ENV_VALUE"

关键字段：

16.2 Streamable HTTP 示例

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }

关键字段：

16.3 OAuth 登录

支持 OAuth 的 MCP server 可以通过 CLI 登录：

codex mcp login server-name

如果 OAuth callback 端口或 URL 有企业网络要求，可以在 config.toml 配置 callback port 或 callback URL。

17. MCP 工具审批：不是所有工具都该自动跑

MCP server 可能暴露很多工具。工具越多，越需要治理。

17.1 server 默认审批

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
default_tools_approval_mode = "prompt"
startup_timeout_sec = 20
tool_timeout_sec = 45
enabled = true
 
[mcp_servers.chrome_devtools.tools.open]
approval_mode = "approve"

这个配置表达：

• 只启用 open 和 screenshot。
• 默认需要 prompt。
• open 可以更宽松。
• 超时显式设置，避免 server 卡住任务。

17.2 Allowlist 和 denylist

教学建议：企业或新手优先用 enabled_tools。因为“只开需要的”比“先全开再禁几个”更容易解释。

17.3 工具风险分级

18. MCP 与密钥：环境变量比硬编码安全

MCP 配置经常涉及 token。课程里必须反复强调：不要把 token 写进教程、prompt 或仓库。

18.1 错误示例

[mcp_servers.internal_docs]
url = "https://docs.example.com/mcp"
http_headers = { "Authorization" = "Bearer real-token-here" }

18.2 更好的写法

[mcp_servers.internal_docs]
url = "https://docs.example.com/mcp"
bearer_token_env_var = "INTERNAL_DOCS_TOKEN"

或者：

[mcp_servers.internal_docs]
url = "https://docs.example.com/mcp"
env_http_headers = { "Authorization" = "INTERNAL_DOCS_AUTH_HEADER" }

18.3 密钥排障 prompt

我的 MCP server 需要 token，但我不想把密钥写进配置文件。
请帮我设计环境变量方案。
不要让我把真实 token 粘贴到聊天里。
请说明：
1. config.toml 应该引用哪个环境变量
2. 本机如何设置这个变量
3. 如何验证变量存在但不打印真实值

19. MCP 与 Plugin 的关系

插件可以 bundle MCP server。这个设计很适合团队分发，但也容易让新人困惑。

19.1 普通 MCP 配置

[mcp_servers.docs]
command = "npx"
args = ["-y", "@example/docs-mcp"]

19.2 Plugin-provided MCP 配置

[plugins."sample@test".mcp_servers.sample]
enabled = true
default_tools_approval_mode = "prompt"
enabled_tools = ["read", "search"]
 
[plugins."sample@test".mcp_servers.sample.tools.search]
approval_mode = "approve"

区别是：普通 MCP 的启动命令由用户配置；插件带来的 MCP server 由插件 manifest 管理，用户配置主要控制启用状态和工具策略。

19.3 什么时候打包进 Plugin

20. MCP 课堂案例：文档核对

场景：你要确认课程里的 Codex 命令是否符合官方文档。

请使用可用的官方文档 MCP 或本地官方文档缓存，核对下面这段课程内容。
只做事实核对，不润色。
输出：
1. 正确的说法
2. 可能过期的说法
3. 需要删除或改写的命令
4. 证据来源

适合用 MCP 的原因：

• 事实可能随版本变化。
• 官方文档比模型记忆可靠。
• 输出需要证据。

不适合让 MCP 做的事：

- 替你决定课程风格。
- 替你判断商业定位。
- 自动修改所有文档而不 review。

21. MCP 课堂案例：浏览器验证

场景：本地 web app 改了 UI，需要用浏览器 MCP 或 App in-app browser 验证。

请使用浏览器相关能力打开本地开发服务器。
检查：
1. 页面是否能加载
2. 主要按钮是否可见
3. 控制台是否有明显错误
4. 移动宽度是否有文本重叠
 
不要提交代码。
如果需要修改，先告诉我问题和涉及文件。

注意：浏览器能力和截图不是占位。课程可以讲“如何验证”，但不要在文章里放“此处插入截图”。

22. MCP 课堂案例：数据库 schema 只读核对

请使用数据库 MCP 的只读能力查看 schema。
目标：
- 确认 users 表是否有 deleted_at 字段
- 确认 orders 表和 users 表的关联字段
- 不读取真实客户数据
- 不执行写操作
 
输出只包含 schema 结论和后续代码修改建议。

这个案例的重点是最小数据原则：能看 schema 就不看数据，能看测试库就不看生产库。

23. MCP 课堂案例：GitHub PR 上下文

请使用 GitHub 相关 MCP 或连接能力读取当前 PR 的评论。
只读操作。
把评论分成：
1. bug
2. 测试
3. 文档
4. 产品问题
5. 可以忽略或需要解释的评论
 
不要回复评论，不要打 label，不要修改 PR。

这个 prompt 可以和 Review 课联动：外部评论来自 GitHub，本地 diff 在 Review 面板里看。

24. MCP 课堂案例：内部 API 诊断

请使用内部 API 文档 MCP 查询 `/v1/invoices/{id}` 的错误响应约定。
只读取文档，不调用真实 API。
然后对比当前代码里的错误处理。
输出：
- 文档约定
- 代码当前行为
- 差异
- 建议最小改动

这个场景展示 MCP 的强项：把外部规范带进本地代码审查。

25. MCP 失败模式大全

25.1 MCP 不被调用时

Codex 没有调用我配置的 MCP。
请先判断：
1. 当前任务是否真的需要 MCP
2. MCP server 是否启用
3. 相关工具是否在 enabled_tools 中
4. prompt 是否明确要求外部上下文
5. 是否有更合适的内置能力

25.2 MCP 返回不可信时

请把 MCP 返回内容和本地仓库文件交叉核对。
标出：
- MCP 明确给出的事实
- 本地文件支持的事实
- 两者冲突的地方
- 需要人工确认的地方

26. 综合工坊：接入一个只读文档 MCP

这个工坊适合让学生第一次体验 MCP。目标不是追求复杂配置，而是理解连接、可见、调用、核对四步。

26.1 第一步：明确需求

我想让 Codex 在写课程时能查官方开发文档。
请判断是否适合接入文档 MCP。
先解释 MCP 相比普通 Web search 的价值。
不要修改配置。

26.2 第二步：添加 server

示例：

codex mcp add context7 -- npx -y @upstash/context7-mcp

或者直接写 config.toml：

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

26.3 第三步：查看可见性

在 CLI TUI：

/mcp

在 App 中：

请帮我确认当前项目是否能看到文档 MCP。
如果看不到，请按配置层、重启、新线程和项目信任状态排查。

26.4 第四步：第一次使用

请使用可用文档 MCP 核对 Codex Skills 的目录位置和触发方式。
只做事实核对。
输出：
1. 官方说法
2. 当前课程说法
3. 是否需要修改

26.5 第五步：复盘

请复盘这次 MCP 使用：
1. MCP 解决了什么问题
2. 哪些信息仍然需要本地文件核对
3. 这个 MCP 是否应该给团队共享
4. 需要哪些权限或工具限制

27. MCP 设计评审题

给学生一个 server 方案，让他们判断是否能接入：

# Proposed MCP
 
Name: internal-admin
Transport: HTTP
Tools:
 
- read_user
- update_user_role
- delete_user
- search_audit_log
  Auth: bearer token
  Data: production users

讨论问题：

1. 哪些工具应该默认禁用？
2. 是否应该允许新手使用？
3. 是否需要测试环境版本？
4. approval mode 应该怎么设？
5. 是否更适合只接 audit log，而不是用户写操作？

推荐答案方向：

- `update_user_role` 和 `delete_user` 不适合默认开放。
- 生产用户数据不适合教学。
- 先做只读 audit/search server。
- 写操作需要人工流程和外部系统审计。

28. MCP 进阶常见问题

Q1：MCP server 越多越好吗？

不是。server 越多，Codex 可选工具越多，误选和权限风险也越高。优先接入高频、可信、只读或可控的 server。

Q2：MCP 能替代项目文档吗？

不能。MCP 提供外部上下文，项目自己的命令、目录、规则仍然应该写在 AGENTS.md 和仓库文档里。

Q3：MCP 工具失败是不是任务就失败？

不一定。Codex 可以降级为本地文件、Web search 或让你补充资料。但如果任务依赖该工具的唯一数据源，就需要先修 MCP。

Q4：HTTP MCP 一定比 STDIO 好吗？

不一定。HTTP 适合远程服务和 OAuth；STDIO 适合本地工具和脚本。选型看数据位置、认证方式和团队维护能力。

Q5：Plugin 带的 MCP 是否自动可信？

不是。Plugin 可以打包 MCP，但工具权限、认证、数据范围仍然要看。安装来源可信也不等于每个工具都适合自动运行。

29. MCP 引入决策会：先问三条问题线

一个 MCP server 值不值得接入，不要只看“能不能跑”。至少要问三条问题线：它能不能帮当前任务，它会打开哪些数据和工具，它是否值得成为团队默认能力。

29.1 任务价值

请评估这个 MCP server 对当前开发任务是否有帮助。
只看：
1. 它能提供哪些本地没有的上下文
2. 哪些工具适合启用
3. 哪些工具暂时不需要

29.2 数据和权限

请从安全角度审查这个 MCP 配置。
重点看数据范围、写工具、token 管理、审批模式和 allowlist。

29.3 团队采用

请判断这个 MCP 是否应该作为团队默认能力。
给出：
- 推荐使用场景
- 不推荐使用场景
- 需要配套的 Skill 或文档
- 试点方式

这三条线可以由一个人先跑，也可以在团队评审里分开讨论。关键是不要只因为“配置成功”就把 server 放进所有项目。

30. MCP 作业：写一份 server 引入说明

# MCP Introduction Note
 
## Server
 
Name:
Owner:
Transport:
 
## Why
 
This server helps Codex...
 
## Tools
 
- Allowed:
- Prompt before use:
- Disabled:
 
## Auth
 
Environment variables:
OAuth:
 
## Example Prompt
 
...
 
## Risks
 
...

这份作业能训练学生把“我配好了”变成“团队知道怎么用”。

31. MCP 长案例：从“能接上”到“能放心用”

很多 MCP 教程停在“配置成功”。真正的课程不能停在那里，因为 MCP 的关键不是接通，而是接通以后 Codex 会用它读什么、写什么、什么时候应该停下来问人。

假设团队想接一个内部文档 MCP，用来回答项目设计问题。坏的引入方式是：

我们有一个 docs MCP，接上以后让 Codex 自己查文档。

这句话少了四件事：

1. 查哪些文档。
2. 是只读还是可写。
3. 查到的内容能不能进入代码修改依据。
4. 文档和代码冲突时听谁的。

更好的引入说明：

# Internal Docs MCP Adoption Note
 
## Purpose
 
Let Codex read internal architecture notes and API docs when answering questions or planning code changes.
 
## Allowed Use
 
- Search architecture docs.
- Read API examples.
- Summarize docs into a local implementation plan.
- Cite which document influenced the plan.
 
## Not Allowed
 
- Edit internal docs through MCP.
- Treat docs as newer than code without checking repository files.
- Use docs to justify broad refactors without local evidence.
 
## Conflict Rule
 
If docs and code disagree, Codex should report the disagreement and ask the user which source is authoritative.

第一次试用不要让 Codex 直接改代码。先做只读问答：

请使用可用的内部文档 MCP 回答：
 
这个项目的 auth redirect 流程设计目标是什么？
 
要求：
1. 说明你读取了哪些文档。
2. 总结设计目标。
3. 标出仍需要看代码确认的地方。
4. 不要修改文件。

第二次试用再让它把文档和代码对齐：

请比较内部文档中对 auth redirect 的描述和当前代码。
 
输出：
1. 文档和代码一致的地方。
2. 文档提到但代码没体现的地方。
3. 代码存在但文档没提到的地方。
4. 建议先改代码还是先改文档。
 
不要修改文件。

只有当这两轮输出都稳定，才进入写入任务：

根据刚才的文档和代码对比，只更新 README 中 auth redirect 的说明。
 
边界：
1. 不修改业务代码。
2. 不调用写入型 MCP tool。
3. 文档描述必须和当前代码一致。
4. 如果发现代码行为不确定，先停止并说明。

这个案例训练的是 MCP 的真实风险感：工具能读外部系统，不等于外部系统永远正确；工具能写，不等于应该写；工具能给 Codex 更多上下文，不等于可以替代本地证据。

32. MCP 失败恢复：不是所有错误都叫“server 坏了”

MCP 出问题时，很多人会直接重装 server。更好的排查顺序是从使用场景开始。

32.1 Codex 没有调用 MCP

可能原因：

- prompt 没说清需要外部工具。
- 当前任务用本地文件就能完成。
- tool 没启用或被 allowlist 限制。
- server 已配置但没有在当前项目或当前会话可用。
- Codex 判断调用成本高于收益。

排查 prompt：

我希望你使用可用的 MCP 工具读取内部文档。
 
请先说明：
1. 当前会话中你能看到哪些相关工具。
2. 哪些工具适合这个任务。
3. 如果你不调用 MCP，原因是什么。
 
不要修改文件。

32.2 MCP 调用了，但答案不可信

不要立刻否定工具，先要求证据链：

请重新回答刚才的问题。
 
要求：
1. 列出你使用的 MCP 来源。
2. 每个关键结论对应哪个来源。
3. 标出需要用本地代码确认的结论。
4. 如果来源之间冲突，直接说明冲突。

如果回答仍然泛，可以收窄问题：

只查 auth redirect 相关文档。
不要总结整个系统。
只回答 callback URL 在登录前后如何保存。

32.3 MCP 需要授权或权限失败

这时不要把任务改成更大权限。先判断是否真的需要这个 tool。

请把当前任务拆成两部分：
1. 不需要 MCP 授权也能完成的本地分析。
2. 只有 MCP 授权后才能完成的外部信息读取。
 
对第二部分，说明读取的必要性和替代方案。

如果替代方案足够，就先用本地分析；如果确实需要授权，再让用户知道为什么。

32.4 MCP 输出让 Codex 想改外部系统

对课程读者来说，这是一条红线。先把任务降级为只读计划：

不要执行任何外部写入。
请只输出你想调用的 MCP tool、目的、可能影响和替代方案。
等我确认后再继续。

这个 prompt 不是为了增加麻烦，而是为了让外部系统写入从“模型顺手做了”变成“人明确决定了”。

33. MCP 与 Skills 的组合：把工具使用变成可复用流程

如果一个 MCP 流程只用一次，prompt 就够了。如果它每周都用，应该做成 Skill。

一次性 prompt：

用内部文档 MCP 查 auth redirect 设计，并和当前代码对比。

可复用 Skill 的思路：

Skill 名称：docs-code-drift-review
用途：比较内部文档和当前代码是否一致。
 
流程：
1. 读取用户指定的主题。
2. 使用文档 MCP 查相关资料。
3. 读取仓库中对应文件。
4. 输出一致、不一致、无法判断。
5. 不修改文件，除非用户明确要求下一步。

这样设计有三个好处：

- MCP 只是工具，Skill 才是流程。
- 每次不用重新解释输出格式。
- 团队能统一“文档和代码冲突时怎么说”。

一个调用示例：

$docs-code-drift-review
主题：auth redirect callback URL
请比较内部文档和当前代码。
输出可行动建议，不要修改文件。

如果团队再想分发给别人，就进入 Plugin 章节：把 Skill 和需要的 app/MCP 说明一起打包，而不是让每个人手抄配置。

34. MCP 运行记录：工具调用之后要留下什么

MCP 工具调用如果只存在于线程里，团队很难复盘它是否可靠。对于重要任务，可以让 Codex 输出一份轻量运行记录。

# MCP Run Note
 
## Task
 
...
 
## Tools Used
 
- Server:
- Tool:
- Purpose:
 
## Data Read
 
- ...
 
## Result
 
- ...
 
## Local Evidence Checked
 
- Files:
- Tests:
 
## Conflicts
 
- Docs vs code:
- Tool result vs local result:
 
## Next
 
- ...

调用 prompt：

请在完成 MCP 查询后输出一份 MCP Run Note。
 
要求：
1. 说明调用了哪个 server / tool。
2. 说明读取了什么类型的数据。
3. 说明哪些结论已经用本地代码确认。
4. 标出不能确认或冲突的地方。
5. 不要包含敏感原文。

这个记录在三种情况下特别有用：

- 外部文档影响了代码修改。
- MCP 查询结果和本地代码不一致。
- 团队要决定是否把这个 MCP 加入默认工具集。

示例：

# MCP Run Note
 
## Task
 
Compare auth redirect docs with current code.
 
## Tools Used
 
- Server: internal-docs
- Tool: search/read docs
- Purpose: find redirect design notes
 
## Data Read
 
- Architecture note for auth redirect
- API example for callback URL
 
## Result
 
Docs say callback URL should be preserved through login.
 
## Local Evidence Checked
 
- `src/auth/redirect.ts`
- `tests/auth-redirect.test.ts`
 
## Conflicts
 
Current test covers default redirect only, not callback URL.
 
## Next
 
Add regression test before changing implementation.

MCP Run Note 能避免一个常见问题：过了两周以后，没人记得当时 Codex 为什么相信某份外部资料。课程里训练这个记录，会让外部工具使用变得可追踪。

35. MCP 课堂练习：把写入工具改成只读试点

给学生一个高风险描述：

我们想接一个 issue tracker MCP，让 Codex 自动更新 issue 状态。

要求先改成只读试点：

# Issue Tracker MCP Read-only Trial
 
## Goal
 
Let Codex read issue status and summarize work items.
 
## Allowed
 
- Search issues.
- Read issue comments.
- Summarize blockers.
- Suggest local next actions.
 
## Not Allowed
 
- Update issue status.
- Assign users.
- Add labels.
- Post comments.
- Create or close issues.
 
## Trial Prompt
 
Use the issue tracker MCP to read open issues related to auth redirect.
Summarize blockers and link them to local files.
Do not write to the issue tracker.

再让学生写升级条件：

只有当只读试点连续两周输出可靠，
并且团队明确 owner、授权范围、撤销路径后，
才讨论是否开放写入 tool。

这个练习能把“我们想自动化外部系统”改成“先验证读取是否真的有价值”。很多团队的 MCP 风险，就是跳过了这一步。

📝 总结与检查清单

完成本课后，请确认以下所有项：

• 理解MCP是工具连接层，不是提示词也不是搜索
• 知道用/mcp或App Settings确认工具是否可用
• MCP工具只给了当前任务需要的最小权限
• 密钥/token存放在环境变量或系统凭据中，不在仓库里
• 完成过一个只读MCP查询任务
• 工具调用结果能在线程中被Review
• 知道如何禁用server、撤销token或卸载插件

如果以上全部勾选，恭喜你掌握Codex MCP！

附录

A. MCP相关命令速查

B. MCP配置核对

C. 推荐学习资源

• Codex MCP 官方文档：https://developers.openai.com/codex/mcp
• 本系列上一篇：CX-04 权限配置
• 本系列下一篇：CX-06 Skills 可复用工作流

课程制作：老金 最后更新：2026年5月30日 许可：本课程采用 MIT License；转载、复制或二次分发时必须保留版权声明与许可声明

下一步

下一篇：CX-06 Skills：在 App 中调用和编写可复用工作流。