Codex MCP 怎么配置？STDIO、Streamable HTTP、OAuth 与工具权限指南

先说结论：先选传输方式，再处理认证与工具范围

Codex 本地主机支持 STDIO 与 Streamable HTTP MCP。STDIO 由本地命令启动服务器，适合本机工具；HTTP 连接远程地址，可使用 Bearer Token、OAuth 等认证。服务器连通不等于所有工具都应自动使用。

ChatGPT 桌面应用、Codex CLI 与 IDE 扩展在同一 Codex 主机上共享 MCP 配置。配置默认位于 ~/.codex/config.toml，受信任项目也可使用项目级 .codex/config.toml。

一、MCP 适合解决什么问题

MCP 用来把外部工具与上下文接入 Codex，例如文档搜索、浏览器、设计系统、工单平台或内部服务。它不是通用网络开关，每个服务器暴露的工具、资源和指令都应单独评估。

优先选择明确来源、最小工具集合和可审计操作。对于只需要读取文档的任务，使用只读服务器比接入拥有写入权限的完整业务系统更安全。

二、桌面应用怎样添加服务器

在 ChatGPT 桌面应用中打开 Settings，选择 MCP servers，点击 Add server，填写名称，选择 STDIO 或 Streamable HTTP，并提供命令或 URL。保存后需要 Restart。

服务器列表会显示启用状态和是否需要 OAuth。需要认证时选择 Authenticate；在编辑器中输入 /mcp 可查看连接。入口和文案随版本变化时，以当前设置页为准。

三、IDE 扩展与 CLI 的关系

IDE 扩展可从齿轮菜单进入 MCP servers，添加后重启扩展。由于配置保存在同一主机的 config.toml，桌面应用、CLI 和 IDE 扩展可以共享，不必重复建立相同服务器。

共享也意味着一次配置可能影响多个客户端。修改用户级服务器前确认其他项目是否依赖它；只服务单仓库的连接可放到受信任项目配置中，降低全局暴露。

四、STDIO 服务器需要哪些字段

STDIO 至少配置 command，可选 args、env、env_vars 与 cwd。command 启动本地进程，args 传递固定参数，cwd 决定启动目录。环境变量应从受控来源转发，而不是直接把密钥写进版本库。

启动失败时依次检查命令是否存在、运行时版本、cwd、参数引用与环境变量。先在终端单独运行服务器，再让 Codex 连接，能区分服务器自身错误与客户端配置问题。

五、HTTP 服务器如何认证

Streamable HTTP 至少配置 url。可使用 OAuth、Bearer Token 环境变量、静态请求头、从环境变量读取的请求头，或本地 header helper。认证方案应按服务器官方要求选择。

Bearer Token 使用环境变量名比把值写进 config.toml 更安全。静态 http_headers 不适合长期秘密。helper 输出临时请求头时也要控制日志，避免密钥出现在错误信息或终端历史中。

六、OAuth 登录与重启流程

支持 OAuth 的服务器可在界面选择 Authenticate，完成浏览器授权。认证完成后，仍需检查服务器是否启用、工具是否可见以及回调或企业代理是否拦截。

令牌过期、权限撤销或回调端口冲突时，应先重新认证并查看客户端日志。不要把他人的 OAuth 缓存复制到另一台机器，也不要共享个人授权给团队。

七、服务器 instructions 会影响什么

MCP 初始化时可以返回 instructions，Codex 会把它作为服务器级指导，与工具一起使用。维护服务器时，应把跨工具流程、限制与速率规则写在这里，并让开头自包含。

服务器指令来自外部系统，应像其他远程内容一样经过信任评估。它不能获得超出工具、沙箱和用户授权的权限，也不应要求上传无关秘密。

八、如何限制暴露的工具

配置可通过 enabled_tools 建立允许列表，再用 disabled_tools 排除不需要的工具。对包含读取、写入、删除和付款等不同风险的服务器，不应默认向所有项目暴露全部能力。

从只读查询开始，确认参数和返回值，再逐步开放写操作。高影响工具应保持 prompt 或更严格审批，并让服务器端也校验用户身份、资源范围和幂等性。

九、工具审批模式怎样设置

MCP 服务器可以设置默认工具审批模式，并按工具覆盖。自动批准适合低风险只读动作，写入或外部副作用工具应要求确认。具体可用字段与取值以当前配置参考为准。

审批不是唯一安全边界。服务器端权限、网络限制、最小令牌、审计日志和撤销机制必须同时存在，防止客户端配置错误造成扩大影响。

十、项目级 MCP 为什么可能不加载

项目 .codex/config.toml 只有在项目配置层受信任时才加载。若服务器在用户层可用、项目层却不显示，先检查信任状态、Git 根和配置文件位置。

不要通过把项目配置全部复制到用户层来绕过信任提示。先审查服务器命令、URL、环境变量和可用工具，确认来源后再信任。

十一、常见故障排查顺序

检查配置语法、服务器启用状态、客户端重启、命令或 URL、DNS 与代理、认证状态、环境变量、工具允许列表、超时和日志。STDIO 先单独启动，HTTP 先验证端点和证书。

出现 401 或 403 时，不要盲目更换 Token；先确认令牌受众、权限与是否过期。工具不可见时核对 enabled_tools 和服务器能力协商，而不是只看网络连通。

十二、安全清单与站内延伸

只连接可信服务器；优先只读；秘密放环境变量；限制工具；写操作保留审批；项目配置先审查；记录 OAuth 账号；定期撤销不用的令牌；不要在日志回显密钥；服务器端实施最小权限。

更多 Codex 工作流可访问 https://gptupcn.com/codex/ 。MCP 选项仍在演进，实施时以当前 OpenAI Docs、服务器文档与本机 /mcp 状态为准。

十三、超时、重试与可观测性

远程 MCP 可能受网络、认证服务和限流影响，本地 STDIO 也可能因依赖或进程退出中断。为连接和工具设置合理超时，对只读幂等操作使用有限重试，并让写操作通过请求 ID 避免重复副作用。

日志应记录服务器名、工具名、耗时、状态码与脱敏错误，不记录完整请求头、Token 或用户私密参数。出现性能问题时先区分连接建立慢、认证慢、工具执行慢还是模型等待，不要无限放宽超时。

结语

可靠的 MCP 配置不是把服务器连上就结束，而是明确传输、认证、作用域、工具列表和审批方式。先建立最小只读连接，再逐步开放必要能力，能兼顾效率与可控性。