发布日期：2026-11-09

截至 2026 年 11 月，OpenAI 官方文档支持 Codex 通过 MCP（模型上下文协议）接入外部工具与信息，连接方式包括本地 STDIO 和远程 Streamable HTTP。本文以七牛云 MCP 服务演示远程地址与 Bearer 鉴权，以 Context7 演示本地进程接入，再说明 OAuth 登录、工具白名单和审批配置。配置是否生效，需要分别检查服务注册、连接状态与实际工具调用；桌面端和命令行还可能读取不同的进程环境。命令与字段按 2026 年 11 月 9 日官方文档核验。

先分清连接方式，再准备配置

Codex 接 MCP，是让编程任务调用外部系统提供的工具，例如查询文档、读取业务记录或处理文件。服务器负责暴露工具，Codex 负责连接和调用；准备配置时，先确认服务提供的是启动命令还是远程地址。

据 OpenAI 官方 MCP 文档（2026 年 11 月核验），当前支持以下连接方式：

连接方式

服务如何运行

配置重点

STDIO

Codex 启动本地进程

可执行命令、参数及进程环境

Streamable HTTP

Codex 连接服务地址

完整 URL，以及服务要求的 Bearer 或 OAuth 鉴权

通用配置位于 ~/.codex/config.toml；项目配置可以放在 .codex/config.toml，但仅可信项目会加载。配置段名采用 [mcp_servers.server_name]，其中 server_name 替换为自定义别名。

下面的命令面向 macOS/Linux 的 Bash 或 Zsh。开始前，确认终端能运行 codex；本地 Context7 示例还需要能执行 npx。

用远程 MCP 服务完成一次接入

本例的七牛云远程接入需要真实服务地址和对应凭据。《MCP 使用说明》（2026 年 6 月更新）提供了 HTTP-Streamable 地址与 Bearer 鉴权示例，可以与 Codex 的远程 MCP 配置对应。

先进入七牛云 AI 控制台的 MCP 服务管理页，创建或选择一个服务，完成该服务要求的配置，复制实际 MCP-ID。再按《获取 AI 大模型推理 API 密钥》（2026 年 10 月更新），到【AI大模型推理 / API Key】创建或复制用于连接的密钥。

这里的 MCP-ID 属于实际配置的服务。不同服务暴露的工具和所需授权可能不同，调用前按对应控制台说明准备；费用也以所选服务规则为准。

在终端依次输入以下命令。密钥通过隐藏输入读取，配置文件只保存环境变量名：

printf '请输入实际 MCP-ID：'
read -r QINIU_MCP_ID
printf '请输入七牛云 AI 推理 API Key：'
read -r -s QINIU_MCP_API_KEY
printf '\n'
export QINIU_MCP_API_KEY

codex mcp add qiniu_mcp \
  --url "https://api.qnaigc.com/v1/mcp/http-streamable/${QINIU_MCP_ID}" \
  --bearer-token-env-var QINIU_MCP_API_KEY

codex mcp get qiniu_mcp
codex mcp list

qiniu_mcp 是本例的自定义别名。已有同名配置时，先查看并编辑原配置，不要重复注册。--bearer-token-env-var 后面填变量名，实际密钥由启动 Codex 的进程环境提供。

接着在同一终端启动 codex，进入后用 /mcp 查看服务状态。可以输入：“列出 qiniu_mcp 当前提供的工具、用途和参数，先不要执行写入操作。”若服务提供只读查询工具，再选择其中一个完成读取验证。

codex mcp list 用来检查已登记的配置。判断接入成功，还需要看到服务连接正常，并让一个真实工具返回结果。

本地 STDIO 服务怎样添加

STDIO 接入由 Codex 启动本地 MCP 程序，重点是启动命令能在对应环境中执行。OpenAI 官方文档在 2026 年 11 月核验时，给出的 Context7 文档查询示例如下：

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

-- 后面的内容是服务器启动命令：这里启动的是 npx，后面才是它的参数。若提示找不到命令，先确认 Node.js、npx 和客户端进程的 PATH，再检查 MCP 配置。

这个示例用于补充本地进程的接法。团队私有服务、文件处理程序或业务系统的 MCP，仍需使用各自官方提供的启动命令，不能只换一个包名就推定可用。

OAuth 登录与 API Key 配置分别怎么用

OAuth 登录用于明确支持 OAuth 的 Streamable HTTP 服务；前面的 Bearer 示例通过环境变量读取 API Key。服务要求哪种认证，就使用对应流程。

假设某个已经注册的 OAuth 服务别名为 my_oauth_server，登录命令如下。执行时将该别名替换成自己的配置名：

codex mcp login my_oauth_server

OpenAI 官方 CLI 文档（2026 年 11 月核验）还提供 --no-browser 选项。终端无法自动打开本地浏览器时，可以使用：

codex mcp login my_oauth_server --no-browser

按终端提示打开授权链接并完成登录，再将完整重定向 URL 粘贴回终端。OAuth 回调配置有额外要求的服务，应按它的官方说明设置，不自行猜测回调地址或权限范围。

工具权限应配置到具体服务器

工具权限可以按服务器设置，再细化到单个工具。先查看服务实际返回的工具名称，确认哪些任务需要保留，避免把不存在的示例名称写入配置。

据 OpenAI 官方配置文档（2026 年 11 月核验），enabled_tools 是工具白名单，disabled_tools 是黑名单；黑名单在白名单之后应用，同名工具仍会被禁用。

希望该服务器的工具默认请求确认时，可在已有的 [mcp_servers.qiniu_mcp] 配置段内追加这一行：

default_tools_approval_mode = "prompt"

这行属于服务器配置段，不应放在文件顶层。也可以按实际需求设置单个工具的 tools.<tool>.approval_mode；其中 <tool> 必须替换为真实工具名。

同一 Codex 主机上的本地客户端可共享 MCP 配置，但环境变量仍由各自进程读取。从终端启动的 CLI 能读到刚导出的密钥，不代表从程序坞启动的桌面客户端也能读到。切换客户端后，需要重新确认凭据是否在该进程环境中可用。

连不上时，按配置、环境和调用顺序排查

排错时先定位失败阶段，再决定是否调整参数。可以按下面的顺序检查：

  1. 核对配置条目与当前项目。 用 codex mcp get qiniu_mcp 检查本例条目；项目配置还要确认项目是否可信，再在会话中检查连接状态。

  2. 确认运行环境。 STDIO 检查命令和依赖；HTTP 检查完整服务 URL，以及客户端进程是否能读到凭据。

  3. 确认认证匹配。 Bearer 服务检查密钥和服务权限；OAuth 服务检查登录状态与授权范围。

  4. 确认工具可见。 查看 /mcp 状态，以及白名单、黑名单是否过滤了需要的工具。

  5. 最后检查超时。 区分连接启动、初始工具目录等待和实际调用耗时。

OpenAI 官方文档（2026 年 11 月核验）给出的服务器启动超时 startup_timeout_sec 默认是 10 秒，单次工具超时 tool_timeout_sec 默认是 60 秒。

同一文档中，顶层 mcp_optional_startup_grace_ms 默认是 1000 毫秒，控制可选 MCP 服务器在构建初始工具目录时的等待。

这几个参数作用于不同阶段。工具暂未出现在初始目录，不等于一次调用已经超时。确需调整时，服务器超时字段放在对应配置段，例如 [mcp_servers.qiniu_mcp] 下，初始目录等待字段放在顶层。

修改后重新启动 CLI 会话，再检查连接。IDE 扩展按官方界面的 Restart extension 操作重启，避免继续沿用旧会话判断结果。

OpenAI 的 MCP 与 CLI 文档明确了客户端配置方式，七牛云 MCP 文档给出了可对应的远程协议地址与鉴权示例。完成接入的判断标准，是当前客户端连接正常、所需工具可见，并能完成一次预期调用。

本文数据截至 2026 年 11 月 9 日；配置按官方文档核验，账户下服务的实际连通性需在自己的环境验证。

参考资料

  • OpenAI：Model Context Protocol：learn.chatgpt.com/docs/extend/mcp?surface=cli

  • OpenAI：Developer Commands（CLI）：learn.chatgpt.com/docs/developer-commands?surface=cli

  • OpenAI：Configuration Reference：learn.chatgpt.com/docs/config-file/config-reference

  • 七牛云：MCP 使用说明：developer.qiniu.com/aitokenapi/12984/mcp-user-manual

  • 七牛云：获取 AI 大模型推理 API 密钥：developer.qiniu.com/aitokenapi/12884/how-to-get-api-key

相关文章

七牛云产品