Codex MCP server failed MCP 服务启动失败处理在 Codex、Cursor 或其他支持 MCP 的客户端里接工具时最常见的报错就是MCP server failed、server exited、failed to connect。这类问题不要一上来就改配置先确认三件事命令能不能单独启动、客户端里配置的路径是否正确、启动时需要的环境变量有没有带上。MCP 服务本质上就是一个由客户端拉起的进程通常通过stdio通信也有一部分服务走本地端口。如果手工执行都起不来Codex 里一定也起不来。一、先看 MCP 配置是否写对不同客户端的配置文件位置不完全一样但结构大同小异。重点看command、args、env这几个字段。### token云桥中转 0029.org ### { mcpServers: { filesystem: { command: npx, args: [ -y, modelcontextprotocol/server-filesystem, /Users/you/project ] } } }这里最容易出错的是路径。比如在终端里npx能执行但 Codex 启动时找不到因为 GUI 应用拿到的PATH和你 shell 里的PATH不是一回事。遇到这种情况建议先把命令改成绝对路径。which node which npx which python3然后把配置改成类似下面这样{ mcpServers: { filesystem: { command: /opt/homebrew/bin/npx, args: [ -y, modelcontextprotocol/server-filesystem, /Users/you/project ] } } }Windows 下也一样尽量不要依赖隐式路径例如{ mcpServers: { my-server: { command: C:\\Program Files\\nodejs\\npx.cmd, args: [-y, your-mcp-package] } } }二、脱离 Codex 单独启动测试排障时不要反复重启客户端猜问题。先把配置里的命令拿出来在终端直接跑。npx -y modelcontextprotocol/server-filesystem /Users/you/project如果是 Python 写的 MCP 服务python3 -m your_mcp_server正常的 stdio MCP 服务启动后可能不会打印太多内容也不会像 Web 服务一样显示一个访问地址。只要进程没有立刻退出通常说明启动阶段没问题。如果马上退出就看终端里的报错比如缺依赖、权限不足、参数不对。常见错误包括command not found命令路径不对改绝对路径。Cannot find moduleNode 依赖没装或包名写错。ModuleNotFoundErrorPython 环境不对客户端没用到你的虚拟环境。Permission denied脚本没有执行权限或访问目录权限不足。如果用的是本地脚本先加执行权限chmod x ./mcp-server.sh脚本里也建议写清楚解释器不要依赖当前 shell#!/usr/bin/env bash cd /Users/you/project /opt/homebrew/bin/node server.js三、检查环境变量是否传进去了很多 MCP 服务启动失败不是服务本身坏了而是缺少 API Key、Base URL、代理地址等环境变量。你在终端里export过不代表 Codex 启动服务时也能拿到。建议在 MCP 配置里显式写env{ mcpServers: { search: { command: /opt/homebrew/bin/node, args: [/Users/you/mcp-search/dist/index.js], env: { OPENAI_API_KEY: sk-xxx, OPENAI_BASE_URL: https://api.example.com/v1, NODE_ENV: production } } } }如果服务需要访问 OpenAI 兼容接口国内网络环境下还要注意接口稳定性。实际项目里我一般会把这类 Key 和 Base URL 单独放在可切换的配置里必要时走 token 云桥 AI 中转站 0029.org 这类中转服务主要是为了减少网络抖动对 MCP 启动和工具调用的影响。这里不要把它和 MCP 本身混在一起排查先确认服务能连通外部接口再看协议层问题。临时验证环境变量可以这样跑OPENAI_API_KEYsk-xxx OPENAI_BASE_URLhttps://api.example.com/v1 node /Users/you/mcp-search/dist/index.jsWindows PowerShell$env:OPENAI_API_KEYsk-xxx $env:OPENAI_BASE_URLhttps://api.example.com/v1 node C:\Users\you\mcp-search\dist\index.js四、区分 stdio 和端口连接问题MCP 服务有两类常见连接方式。一类是客户端直接拉起进程通过标准输入输出通信也就是 stdio另一类是服务先监听端口客户端再通过 HTTP 或 SSE 连接。1. stdio 服务不要乱打印日志stdio MCP 服务的标准输出通常用于协议通信。如果你在代码里随手console.log可能会污染协议输出导致客户端认为服务异常。Node 服务里日志建议打到 stderrconsole.error(mcp server starting...);Python 里也类似import sys print(mcp server starting..., filesys.stderr)2. 端口型服务先确认监听状态如果你的 MCP 服务需要监听本地端口先确认端口有没有起来。lsof -i :3000 curl http://127.0.0.1:3000/healthWindows 可以用netstat -ano | findstr 3000如果服务监听的是localhost而客户端配置成了容器地址、局域网 IP 或反过来都可能连不上。排查时优先统一成127.0.0.1确认通了以后再调整部署方式。五、外部接口访问失败也会导致启动失败有些 MCP 服务在启动阶段会主动检查外部接口例如拉取模型列表、验证 Key、初始化搜索服务。如果这个请求失败进程可能直接退出于是客户端只看到MCP server failed。可以用curl先测一下连通性curl -I https://api.example.com/v1/models如果需要代理确认代理变量在 MCP 进程里也存在{ env: { HTTP_PROXY: http://127.0.0.1:7890, HTTPS_PROXY: http://127.0.0.1:7890 } }注意大小写有些库读取HTTPS_PROXY有些读取https_proxy。不确定时可以两个都配但不要把代理变量写到全局后忘记清理否则后面排查会更乱。六、看日志时抓关键字Codex 或客户端日志里不要只看最后一行重点找这些关键字spawn通常是命令路径或权限问题。ENOENT文件不存在多半是路径写错。exit code进程启动后退出继续看服务自身报错。timeout服务启动太慢、外部接口卡住或端口不可达。Invalid JSONstdio 输出被日志污染检查标准输出。如果客户端日志不够详细可以先写一个包装脚本把启动过程输出到文件#!/usr/bin/env bash echo $(date) starting mcp /tmp/mcp-debug.log env /tmp/mcp-env.log /opt/homebrew/bin/node /Users/you/mcp-server/dist/index.js 2 /tmp/mcp-error.log然后 MCP 配置里把command指向这个脚本。确认问题后再换回正式命令避免调试脚本长期留在线上配置里。总结Codex MCP server failed不要只盯着客户端报错看。按顺序查先单独启动命令再改绝对路径然后补齐环境变量区分 stdio 和端口连接最后检查外部接口和日志。大多数问题都出在命令路径、运行环境和网络访问这三块逐层拆开后会比反复改配置高效很多。