×−+
MCP第 9 课 · Codex 教程
第 9 课 · MCP

MCP：给 Codex
接上外部工具

Codex 能读写你电脑上的项目，可 GitHub 上的 issue、Sentry 里的报错、Figma 里的设计稿，它够不着。MCP 就是给它接上这些外部工具的标准接口。这一课带你接一个、管好它，再让它读一个 issue、把 bug 修掉。

约 35 分钟 10 节 · 6 个动手练习 章末测验 形式参考 luongnv89/claude-howto · 事实依据 OpenAI 官方文档
Codex通过 MCP
连接外部工具
入门先用起来 原理弄懂为什么 实战动手练 深入进阶与避坑

时间紧就先看"入门"和"实战"，照着做就能接上第一个服务器；"原理"讲登录和工具审批，决定你接得安不安全。

01入门

MCP 是什么

MCP（Model Context Protocol，模型上下文协议）是一个开放标准，用来把 Codex 连到外部的工具和数据上。

像给新同事开通公司系统的账号第 1 课说过，Codex 像坐到你电脑前的朋友。他能翻你的项目文件夹，却进不了 GitHub、Sentry、Figma。给他开通一个系统的账号，他就能自己去查、去操作，不用你来回复制粘贴。
而且用的是同一种插口每个外部系统做一个"MCP 服务器"，Codex 按同一套规矩去接。接好一次，桌面 App、命令行、IDE 扩展都能用。

什么时候该接

官方最佳实践给了四种情况：

  • Codex 需要的信息不在仓库里（issue、报错日志、设计稿）；
  • 这些信息经常变，每次复制粘贴很累；
  • 你想让它直接用一个工具，而不是照着你贴的说明去猜；
  • 你需要一个能在多人、多个项目里重复用的连接。
先接一两个

官方的建议是：只在能打通一个真实工作流时才接，别一上来把你用的所有工具都接上。先挑一两个最能省掉你手动操作的，用顺了再加。服务器接得越多越耗额度，第 9 节细说。

服务器能给 Codex 什么

工具Tools
能做的动作，比如"读一个 issue""开一个 PR"。本课主要讲它。
资源Resources
可以读的数据，给 Codex 当上下文看。
提示词Prompts
服务器提供的提示词模板，可以反复用。

有的服务器主要提供信息，有的能做很有分量的操作。后面讲的工具过滤和审批，就是用来管住后一种的。

在哪能用

ChatGPT 桌面 App、Codex CLI、IDE 扩展都支持 MCP 服务器，而且共用同一份配置。ChatGPT 网页版不读你电脑上的配置，只能通过插件用 MCP 工具（第 11 课讲插件）。

02原理

两种连接方式

MCP 服务器分两种：一种是在你电脑上运行的程序（STDIO），一种是通过网址访问的服务（Streamable HTTP）。切换看看它们的区别。

怎么知道是哪一种

看服务器自己的说明：给你的是一条命令，就是 STDIO；给你的是一个网址，就是 Streamable HTTP。有的服务两种都提供，比如 Figma 就有本地版和远程版。

两种服务器都写在同一个地方：config.toml 里的 [mcp_servers.名字] 表。"名字"是你给它起的，比如 context7、github。在 App 里点几下，存下来的也是这张表，下一节就能看到。

03入门

在 App 里添加服务器

打开 Settings（设置）里的 MCP servers 页面，点 Add server 填好，Save，再 Restart。下面的界面是示意，按钮文字以你的 App 为准。

1
打开 Settings > MCP servers这一页列着你自己加的服务器和官方推荐的服务器。推荐的那些可以直接启用，需要登录的会带你走一遍 OAuth。
2
点 Add server，填三样名字；类型选 STDIO 或 Streamable HTTP；再填启动命令或服务器网址（看它的说明）。
3
Save，然后点 Restart保存之后重启一下，新服务器才会生效。
4
要登录的，点 Authenticate列表会标出哪些服务器已启用、哪些需要 OAuth 登录。需要登录的点 Authenticate，按提示在浏览器里完成（第 5 节）。
Settings› MCP serversAdd server1
2
名称github
类型STDIOStreamable HTTP
URLhttps://github-mcp.example.com/mcp
Save
3重启后生效Restart
githubStreamable HTTP需要登录Authenticate4
context7STDIO已启用
位置：Settings（设置）里的 MCP servers 页面
  1. 1Add server新加一个服务器。
  2. 2名字、类型、命令或网址STDIO 填启动命令，Streamable HTTP 填网址。
  3. 3Save 之后 Restart重启之后才生效。
  4. 4Authenticate需要 OAuth 登录的服务器，点它去浏览器里登录。

它存到了哪里

App 里加的服务器，写进的就是 ~/.codex/config.toml。上面那个 github 服务器存下来大致是这样：

~/.codex/config.toml

            
ChatGPT 桌面 App、CLI、IDE 扩展读的是同一份，所以在哪加都行，换着用不用重配。想做更细的设置（下面几节讲的白名单、审批、超时），直接改这个文件就行；在 Settings > Configuration 里可以打开它。


            
检查一下：/mcp

            
在对话的输入框里打 /mcp，能看到现在连上了哪些服务器。加完服务器、登录完，先用它确认一下，再布置任务。

            
也可以让 Codex 帮你装
官方的原话大意是：很多时候，Codex 能帮你把需要的服务器装好，你只要开口说。比如"帮我接上 Context7 的 MCP 服务器"。


            
命令行里也能管（命令行）

            
用 CLI 的话，codex mcp 这组命令管的也是同一份 config.toml。第 14 课讲 CLI 时还会提到。

            

              

                
命令做什么

                
                  
codex mcp add 名字 -- 启动命令加一个 STDIO 服务器，例如 codex mcp add context7 -- npx -y @upstash/context7-mcp；--env 键=值 可以给它设环境变量

                  
codex mcp add 名字 --url 网址加一个 Streamable HTTP 服务器；--bearer-token-env-var 指定放令牌的环境变量

                  
codex mcp list列出配好的服务器

                  
codex mcp get 名字看某个服务器的配置

                  
codex mcp remove 名字删掉一个服务器

                  
codex mcp login 名字OAuth 登录（只对支持 OAuth 的 Streamable HTTP 服务器有效）；logout 删掉存好的登录凭据

                
              

            

          


          
          

            

              04实战
              
练一练：这件事该不该接 MCP

              
MCP 不是万能的。项目规矩、固定流程、项目里的文件，各有更合适的办法。6 个场景，选最合适的一个。

            

            

            

          


          
          

            

              05原理
              
登录：OAuth 和令牌

              
远程服务器大多要登录，确认"你是谁、允许 Codex 做什么"。常见三种方式，切换看看。

            

            

              

              

            


            
Codex 先用哪一种

            
同一个 Streamable HTTP 服务器配了好几种，Codex 按这个顺序找：

            
    
              
  1. 你明确配的令牌和请求头（bearer_token_env_var、http_headers、env_http_headers）；
    2. 
              
  2. 都没有，再看 auth：默认是 oauth，用你之前登录存下的 OAuth 凭据；设成 chatgpt 是用当前的 ChatGPT 登录，只对受信任的 ChatGPT 自家服务有效；
    3. 
              
  3. 什么都找不到，就不带登录直接连。能不能用，看那个服务器给不给。
    4. 
            

            
另外，http_headers_helper 给出的 Authorization 头排在明确配的令牌和 OAuth 凭据之后：这两样有了，就不用它给的。

            
令牌别直接写进配置文件
配置文件，尤其是项目里的 .codex/config.toml，可能会被提交到 Git、发给同事。令牌放进环境变量，配置里只写变量名（bearer_token_env_var、env_http_headers、env_vars 都是这个思路）。

          


          
          

            

              06原理
              
工具过滤与审批

              
一个服务器可能带十几个工具，有的只读，有的能删东西。先用两份名单决定哪些交给 Codex，再用审批方式决定哪些要先问你。

            

            

              
第一关：白名单 enabled_tools写了它，就只留名单里的工具；不写，服务器的工具全部进来。

              
第二关：黑名单 disabled_tools在白名单之后生效，名单里的去掉。两份名单都写了同一个工具，结果是去掉。

              
第三关：审批方式default_tools_approval_mode 定这个服务器的默认；tools.工具名.approval_mode 给单个工具开例外，例外优先。

            

            

              

                
审批方式意思

                
                  
auto按工具自己声明的标注来：标了只读的直接用，声明了会改东西的先请求批准（文档没细说，按官方描述推断，以你的 App 为准）

                  
prompt每次调用都先问你

                  
writes没标"只读"的工具都要问（官方原话）

                  
approve预先批准，调用时不再问（文档没细说，按官方描述推断，以你的 App 为准）

                
              

            

            
文档只列出这四个值，并明确解释了 writes。auto 和 approve 的解释，依据是官方"有副作用的工具调用会请求批准"和"按工具标注或审批方式决定是否需要批准"这两处描述；不写这一项时默认按哪一种，文档也没说。拿不准时以你的 App 为准。

            
一条铁律
工具声明了自己是破坏性的（比如删除），调用前一定要批准，审批方式怎么设都一样。（它同时声明了"只读"时怎么算，官方两处文档说法不同，以你的 App 为准。）


            
动手：一个 GitHub 服务器的 8 个工具

            
点名单里的工具、切换审批方式，看每个工具最后是直接用、要问你，还是根本用不了。最下面同步生成对应的配置。

            

            
工具名和标注是示意，真实的以 /mcp 里显示的为准。"你的权限档位"就是第 3 课讲的三档：Approve for me 下，要批准的请求交给自动审查代你判断，官方写明它也会审 MCP 工具调用。

          


          
          

            

              07实战
              
练一练：这个工具会不会问你

              
都是 github 服务器，权限档位是默认的 Ask for approval。看配置，判断 Codex 想用那个工具时会怎样。

            

            

            

          


          
          

            

              08实战
              
演练：接上 GitHub，读 issue 修 bug

              
从添加服务器、登录，到让 Codex 读 issue、修代码、回 issue 留言，完整走一遍。中途要你点两下：一次登录，一次批准。放完可以接着在输入框里提要求。

            

            

              

              
            

            
画面为教学示意：服务器地址用的是官方示例配置里的占位网址，issue 内容、工具名、测试数量都是虚构的；添加步骤、按钮名称、审批规则与官方文档一致。

          


          
          

            

              09深入
              
进阶与避坑

              
超时、必需服务器、项目级配置、额度、安全边界，以及 MCP 和别的功能怎么配合。

            


            
几个进阶配置

            

              

                
配置默认什么时候用

                
                  
startup_timeout_sec10 秒服务器启动慢，老是启动超时

                  
tool_timeout_sec60 秒某个工具要跑很久

                  
enabled = false—暂时不用，但不想删配置

                  
required = true—这个服务器必须在：连不上就让启动直接失败，而不是悄悄少了一批工具

                  
tools.工具名.output_token_limit—某个工具的输出太长、占上下文，给它单独设一个输出上限

                  
mcp_optional_startup_grace_ms1000 毫秒顶层设置：准备工具列表时等"非必需"服务器多久；设成 0 就等到各自的启动超时

                
              

            


            
项目级配置：团队共用

            
服务器也可以写进项目里的 .codex/config.toml，跟着仓库走，同事拉下来就有。但它只在你信任了这个项目时才加载（信任和配置优先级是第 3、7 课的内容）。比如给 order-admin 加一份团队约定：

            
order-admin/.codex/config.toml


            
省额度：不用的就关掉

            
官方在"怎么让额度用得久一点"里专门写了一条：少接几个 MCP 服务器。每个服务器都会往你的消息里加上下文，多用你的额度。暂时不用的服务器，在设置里关掉或写 enabled = false。额度的具体数字见专题 A。

            
另外（这是推断，官方那条没提）：工具多的服务器，用白名单只留用得上的，也能让 Codex 少看一些用不上的工具。


            
安全：MCP 不归沙箱管

            
第 3 课的沙箱管的是 Codex 在你电脑上跑的命令，"默认不联网"说的也是这些命令。MCP 服务器走它自己的进程或连接，命令沙箱的网络设置管不到它，要靠 mcp_servers 里的配置来管。所以：

            
    
              
  • 只接信得过的服务器。STDIO 服务器是一个在你电脑上运行的程序；你通过 MCP 发出去的数据，适用那个服务自己的条款和隐私政策。
    • 
              
  • 服务器能影响 Codex 的做法。服务器可以附带一段使用说明（instructions），Codex 会把它当成指导来读。
    • 
              
  • 写操作收紧一点。用不上的写工具放进 disabled_tools；敏感的设成 prompt。
    • 
              
  • 公司统一管理的电脑上，管理员可以限定你能启用哪些服务器，不在名单里的会被停用。
    • 
            


            
它和别的功能怎么配合

            

              
Skills（第 8 课）skill 定流程、点名用哪些 MCP 工具，MCP 负责连外部系统。skill 依赖某个服务器时，可以在 agents/openai.yaml 里声明，Codex 能帮你装好接上。

              
Hooks（第 10 课）hook 里，MCP 工具的名字长这样：mcp__filesystem__read_file，可以按它匹配、拦截。

              
插件（第 11 课）插件可以自带 MCP 服务器，启动方式由插件定；开关和工具策略写在 [plugins."插件名".mcp_servers.服务器名] 下，写法和本课一样。

              
子代理（第 12 课）自定义代理的配置文件里可以单独写 mcp_servers，比如只给"查文档"的代理接文档服务器；不写就沿用主对话的。

              
手机 Remote（第 13 课）用的是被遥控那台电脑上的 MCP 配置。

            


            
旧教程对照
网上的教程可能还这么写：
    
              
  1. codex mcp-server 已移除：把 Codex 自己当成 MCP 服务器给别的程序调用。它 2026 年 8 月 24 日废弃、9 月 5 日移除（见 changelog）；要把 Codex 集成进自己的程序，改用 app server 实验（第 14 课提一句）。本课讲的"Codex 连外部服务器"不受影响。
    2. 
              
  2. 从别的工具抄来的 JSON 配置 "mcpServers": {…}：Codex 的配置是 TOML，写成 [mcp_servers.名字]。只有插件里的 .mcp.json 用 JSON（第 11 课）。
    3. 
              
  3. startup_timeout_ms：还能用，是 startup_timeout_sec 的毫秒写法。
    4. 
            


            

              
加了服务器，Codex 却用不了
先确认 Save 之后点了 Restart，再在输入框打 /mcp 看它连上没有。列表里显示需要登录的，点 Authenticate。

              
启动超时
默认只等 10 秒。启动慢的服务器，把 startup_timeout_sec 调大。某个工具执行超过 60 秒被掐断，调 tool_timeout_sec。

              
项目里配的服务器没加载
项目级的 .codex/config.toml 只在信任的项目里加载。先确认这个项目被信任了（第 3 课）。

              
ChatGPT 网页版里找不到我配的服务器
网页版不读你电脑上的配置文件，也没有本地的命令菜单。要在网页版里用 MCP 工具，装一个带这些工具的插件（第 11 课）。

              
接了好几个服务器，额度掉得快
每个服务器都会给消息加上下文。官方的建议是少接几个，不用的关掉。

              
沙箱不是默认不联网吗，它怎么还能访问 GitHub
沙箱管的是 Codex 跑的命令。MCP 服务器走自己的连接，不受那个开关管。所以要靠名单和审批方式管住它，也只接信得过的服务器。

              
卸载了插件，之前连过的 MCP 集成怎么还在？
卸载插件会移除插件包本身。你在 ChatGPT 里另外单独连接过的 MCP 集成，不会跟着断开，要到 ChatGPT 那边自己断开。

            

          


          
          

            

              10检验
              
小测验

              
8 道题，每题选完会立刻看到解析。