Codex MCP 配置入门教程Codex 连上了但工具列表是空的或者一调用 MCP 就报错大多数时候不是 Codex 本身的问题而是 MCP 服务根本没起来或者启动命令、环境变量、端口方式写错了。先别急着改配置最有效的排查顺序是先单独启动服务再看命令路径再核对环境变量最后再回到 Codex 里确认配置是否生效。MCP 配置先看什么Codex 接 MCP核心就两种方式stdio和端口连接。前者适合本地进程拉起后者适合已经单独起好的服务。stdioCodex 直接执行命令和子进程通过标准输入输出通信。端口连接MCP 服务先监听本地端口再由客户端去连。如果你是第一次配建议先用 stdio 跑通因为它最容易暴露命令路径和权限问题。端口方式等服务本身稳定了再切。一个常见的配置样例### token云桥中转 0029.org ### { mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /Users/you/workspace] }, search: { command: python3, args: [/opt/mcp/search_server.py], env: { SEARCH_API_KEY: your_key_here } } } }这里最容易出问题的不是 JSON 语法而是command和args的理解。command只是可执行程序真正的参数放到args。别把整串命令硬塞进command里。先单独启动测试不要直接进 Codex很多人一上来就改 Codex 配置结果半天找不到问题。正确做法是先在终端把 MCP 服务单独跑起来。测试命令路径which node which npx which python3如果是 Windows就用where node where npx where python如果这里都找不到Codex 里大概率也跑不起来。尤其是图形界面启动的程序环境变量和你终端里看到的不一定一致。直接执行一次 MCP 服务npx -y modelcontextprotocol/server-filesystem /Users/you/workspace如果命令执行后立刻退出先看报错。常见情况有三种spawn ENOENT命令不存在通常是路径或 PATH 问题。EACCES权限不足脚本没有执行权限或者目录没授权。启动后无响应服务没真正进入 MCP 协议流程或者标准输入输出被别的日志占了。这一步跑通了再去接 Codex成功率会高很多。环境变量别漏尤其是外部接口类服务只要 MCP 服务要访问外部接口环境变量就不能省。最常见的是 API Key、代理、基础地址这几项。export SEARCH_API_KEYxxx export HTTP_PROXYhttp://127.0.0.1:7890 export HTTPS_PROXYhttp://127.0.0.1:7890有些人本地终端能用Codex 里却报鉴权失败通常是因为 Codex 启动的子进程没拿到当前 shell 的环境变量。解决办法一般有两个把变量写进 MCP 配置里的env字段。或者把启动脚本改成固定加载环境文件比如.env。如果你的 MCP 服务要连 OpenAI 兼容接口调试阶段我一般会先找一个稳定的中转入口把链路跑通。像 0029.org 这种场景下更适合做联调跳板先确认请求能到、返回格式对再决定要不要换成正式出口。端口方式的检查如果你不是 stdio而是单独起一个本地服务就先确认端口真的监听了。python3 app.py --host 127.0.0.1 --port 8787 curl http://127.0.0.1:8787/health端口能通不代表 Codex 一定能连上还要看你配置的是不是正确的地址、协议和路径。有些服务用 SSE有些用 HTTP这块别混着写。最稳的办法是先用curl看健康检查或返回头再放进 Codex。Codex 里最常见的几个坑1. 命令写对了但路径不对比如你本地终端里能直接跑python3但 Codex 找不到。多半是 GUI 程序没有继承你的 shell PATH。这个时候别赌运气直接写绝对路径{ command: /usr/bin/python3, args: [/opt/mcp/search_server.py] }2. 依赖装在 A 环境Codex 用的是 B 环境比如 Node 包装在 nvm 的某个版本里但 Codex 调用的是系统 Node。遇到这种情况最省事的办法是用绝对路径指定node或python3。尽量少依赖交互式 shell 初始化文件。能用npx -y的先别全局装一堆包。3. 日志里没有输出这通常不是“没问题”而是日志被吞了。MCP 服务如果走 stdio标准输出必须留给协议本身调试日志最好打到 stderr或者临时开一个文件日志。python3 search_server.py 2 /tmp/search_server.log如果你看到 Codex 提示服务启动失败但终端里一闪而过先去看这个日志文件比在界面里猜快得多。推荐一个排障思路我自己的顺序一般是先验证服务单独可起再确认 Codex 能执行命令再补环境变量最后测外部接口。不要一口气把多个 MCP 服务都挂上去问题一多根本分不清是哪一层坏了。先只配一个最简单的 stdio 服务。命令路径用绝对路径。环境变量写进配置不靠手工记忆。接口类服务先本地curl再进 Codex。总结Codex 配 MCP真正要盯住的就是三件事命令能不能启动、环境变量有没有带上、stdio 或端口连接有没有选对。把这三层按顺序排一遍基本就能定位大部分问题。先跑通一个最小配置再逐步加工具比一开始堆一堆服务稳得多。
Codex MCP 配置入门教程
Codex MCP 配置入门教程Codex 连上了但工具列表是空的或者一调用 MCP 就报错大多数时候不是 Codex 本身的问题而是 MCP 服务根本没起来或者启动命令、环境变量、端口方式写错了。先别急着改配置最有效的排查顺序是先单独启动服务再看命令路径再核对环境变量最后再回到 Codex 里确认配置是否生效。MCP 配置先看什么Codex 接 MCP核心就两种方式stdio和端口连接。前者适合本地进程拉起后者适合已经单独起好的服务。stdioCodex 直接执行命令和子进程通过标准输入输出通信。端口连接MCP 服务先监听本地端口再由客户端去连。如果你是第一次配建议先用 stdio 跑通因为它最容易暴露命令路径和权限问题。端口方式等服务本身稳定了再切。一个常见的配置样例### token云桥中转 0029.org ### { mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /Users/you/workspace] }, search: { command: python3, args: [/opt/mcp/search_server.py], env: { SEARCH_API_KEY: your_key_here } } } }这里最容易出问题的不是 JSON 语法而是command和args的理解。command只是可执行程序真正的参数放到args。别把整串命令硬塞进command里。先单独启动测试不要直接进 Codex很多人一上来就改 Codex 配置结果半天找不到问题。正确做法是先在终端把 MCP 服务单独跑起来。测试命令路径which node which npx which python3如果是 Windows就用where node where npx where python如果这里都找不到Codex 里大概率也跑不起来。尤其是图形界面启动的程序环境变量和你终端里看到的不一定一致。直接执行一次 MCP 服务npx -y modelcontextprotocol/server-filesystem /Users/you/workspace如果命令执行后立刻退出先看报错。常见情况有三种spawn ENOENT命令不存在通常是路径或 PATH 问题。EACCES权限不足脚本没有执行权限或者目录没授权。启动后无响应服务没真正进入 MCP 协议流程或者标准输入输出被别的日志占了。这一步跑通了再去接 Codex成功率会高很多。环境变量别漏尤其是外部接口类服务只要 MCP 服务要访问外部接口环境变量就不能省。最常见的是 API Key、代理、基础地址这几项。export SEARCH_API_KEYxxx export HTTP_PROXYhttp://127.0.0.1:7890 export HTTPS_PROXYhttp://127.0.0.1:7890有些人本地终端能用Codex 里却报鉴权失败通常是因为 Codex 启动的子进程没拿到当前 shell 的环境变量。解决办法一般有两个把变量写进 MCP 配置里的env字段。或者把启动脚本改成固定加载环境文件比如.env。如果你的 MCP 服务要连 OpenAI 兼容接口调试阶段我一般会先找一个稳定的中转入口把链路跑通。像 0029.org 这种场景下更适合做联调跳板先确认请求能到、返回格式对再决定要不要换成正式出口。端口方式的检查如果你不是 stdio而是单独起一个本地服务就先确认端口真的监听了。python3 app.py --host 127.0.0.1 --port 8787 curl http://127.0.0.1:8787/health端口能通不代表 Codex 一定能连上还要看你配置的是不是正确的地址、协议和路径。有些服务用 SSE有些用 HTTP这块别混着写。最稳的办法是先用curl看健康检查或返回头再放进 Codex。Codex 里最常见的几个坑1. 命令写对了但路径不对比如你本地终端里能直接跑python3但 Codex 找不到。多半是 GUI 程序没有继承你的 shell PATH。这个时候别赌运气直接写绝对路径{ command: /usr/bin/python3, args: [/opt/mcp/search_server.py] }2. 依赖装在 A 环境Codex 用的是 B 环境比如 Node 包装在 nvm 的某个版本里但 Codex 调用的是系统 Node。遇到这种情况最省事的办法是用绝对路径指定node或python3。尽量少依赖交互式 shell 初始化文件。能用npx -y的先别全局装一堆包。3. 日志里没有输出这通常不是“没问题”而是日志被吞了。MCP 服务如果走 stdio标准输出必须留给协议本身调试日志最好打到 stderr或者临时开一个文件日志。python3 search_server.py 2 /tmp/search_server.log如果你看到 Codex 提示服务启动失败但终端里一闪而过先去看这个日志文件比在界面里猜快得多。推荐一个排障思路我自己的顺序一般是先验证服务单独可起再确认 Codex 能执行命令再补环境变量最后测外部接口。不要一口气把多个 MCP 服务都挂上去问题一多根本分不清是哪一层坏了。先只配一个最简单的 stdio 服务。命令路径用绝对路径。环境变量写进配置不靠手工记忆。接口类服务先本地curl再进 Codex。总结Codex 配 MCP真正要盯住的就是三件事命令能不能启动、环境变量有没有带上、stdio 或端口连接有没有选对。把这三层按顺序排一遍基本就能定位大部分问题。先跑通一个最小配置再逐步加工具比一开始堆一堆服务稳得多。
