Codex MCP 配置入门教程-CSDN博客

Codex MCP 配置入门教程

Codex 连上了，但工具列表是空的，或者一调用 MCP 就报错，大多数时候不是 Codex 本身的问题，而是 MCP 服务根本没起来，或者启动命令、环境变量、端口方式写错了。先别急着改配置，最有效的排查顺序是：先单独启动服务，再看命令路径，再核对环境变量，最后再回到 Codex 里确认配置是否生效。

MCP 配置先看什么

Codex 接 MCP，核心就两种方式：stdio 和 端口连接。前者适合本地进程拉起，后者适合已经单独起好的服务。

stdio：Codex 直接执行命令，和子进程通过标准输入输出通信。
端口连接：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_KEY="xxx"
export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://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 或端口连接有没有选对。把这三层按顺序排一遍，基本就能定位大部分问题。先跑通一个最小配置，再逐步加工具，比一开始堆一堆服务稳得多。

Codex MCP 配置入门教程