AI Agent / 系统课时

连接 MCP 服务器

连接 MCP 服务器

本课把 Codex 与一个真实 MCP 服务器接起来,并建立一套可重复的检查方法:先确认传输配置能启动,再核对服务器是否启用、认证是否就绪,最后用实际工具调用验证外部能力已经进入 Codex。

学习目标

  • 能为 Codex 添加 STDIO 或 Streamable HTTP 类型的 MCP 服务器
  • 能检查服务器启用状态、认证状态与当前会话中的可用工具
  • 能按“启动、认证、工具策略、调用”顺序定位常见连接失败

先看清连接链路

MCP 并不是把外部数据直接塞进提示词,而是让 Codex 在代理循环中增加一组由服务器提供的工具。Codex 先初始化服务器并取得工具定义,模型决定调用某个工具后,参数通过 MCP 发送给服务器,结果再回到当前对话。Codex 当前支持本地 STDIO 与远程 Streamable HTTP 两类服务器,远程连接还可以叠加 Bearer Token 或 OAuth。:contentReference[oaicite:0]{index=0}

Codex 连接 MCP 服务器的数据流与认证边界

真正需要记住的是三个状态不能混为一谈:配置存在只说明 Codex 知道这个服务器;服务器已启用且能初始化才说明连接成立;工具可以被当前会话调用还要继续通过认证、工具白名单和审批策略。

接入一个 STDIO 服务器

下面使用官方文档示例中的 Context7。它通过 npx 作为本地进程启动,所以先确保机器已经安装 Node.js,并且 codex 命令可以正常运行。:contentReference[oaicite:1]{index=1}

bash
node --version
npx --version
codex --version

预期输出

text
v<VERSION>
<VERSION>
codex-cli <VERSION>

版本号随本机安装而变化,因此这里用 <VERSION> 表示动态值。确认前置条件后添加服务器:

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

预期输出

text
Added global MCP server 'context7'.

这条命令会把服务器写入 Codex 配置。若更希望项目内共享配置,也可以在受信任项目的 .codex/config.toml 中声明 [mcp_servers.<name>];Codex 会读取项目级 MCP 配置。:contentReference[oaicite:2]{index=2}

检查状态与可用工具

添加完成后先用 CLI 查看静态状态,不要直接把“能看到配置”当成“工具一定可用”。

bash
codex mcp list

预期输出

text
Name      Command  Args                       Env  Cwd  Status   Auth
context7  npx      -y @upstash/context7-mcp  -    -    enabled  Unsupported

对于这种 STDIO 服务器,Auth 显示 Unsupported 表示 OAuth 不适用于该传输配置,并不等于服务器故障。Status 应为 enabled。CLI 还支持 codex mcp list --json,适合脚本化检查。:contentReference[oaicite:3]{index=3}

进入 Codex TUI 后输入 /mcp,可以查看当前会话中的活动 MCP 服务器。服务器初始化时提供的工具清单才是模型真正可调用的能力,因此工具名不要写死在团队文档里;升级服务器后应重新查看当前会话实际暴露的工具。官方文档也把 /mcp 作为检查活动服务器的入口。:contentReference[oaicite:4]{index=4}

对于支持 OAuth 的远程服务器,先配置 url,再运行 codex mcp login <server-name> 完成登录;远程服务器还可以使用 bearer_token_env_var、静态请求头或环境变量请求头提供认证信息。不要把长期令牌直接提交进项目配置。:contentReference[oaicite:5]{index=5}

按固定顺序排查失败

连接失败时按层次排查,比反复删除重加配置更快:

  1. 先确认 STDIO 的启动命令能在同一环境中执行,或 HTTP url 能从当前机器访问。
  2. 再看 codex mcp list 是否为 enabled;需要 OAuth 的服务器继续完成登录。
  3. 若服务器已连接但某些工具不出现,检查 enabled_tools、disabled_tools 与每个工具的审批模式。
  4. 若初始化或调用明显超时,再调整 startup_timeout_sec 或 tool_timeout_sec,不要先把超时无限放大。
  5. 最后在一个新会话中实际触发目标工具,确认请求确实到达服务器并返回结果。

把“配置、连接、认证、工具可见、实际调用”分层检查后,MCP 问题通常可以迅速定位到具体边界,而不是笼统归因于 Codex 或服务器不可用。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

连接 MCP 服务器

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通