当前位置：首页 > news >正文

Codex MCP server failed MCP 服务启动失败处理

news 2026/7/1 3:12:25

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 module：Node 依赖没装，或包名写错。
ModuleNotFoundError：Python 环境不对，客户端没用到你的虚拟环境。
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_KEY=sk-xxx OPENAI_BASE_URL=https://api.example.com/v1 node /Users/you/mcp-search/dist/index.js

Windows PowerShell：

$env:OPENAI_API_KEY="sk-xxx" $env:OPENAI_BASE_URL="https://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 服务里日志建议打到 stderr：

console.error("mcp server starting...");

Python 里也类似：

import sys print("mcp server starting...", file=sys.stderr)

2. 端口型服务先确认监听状态

如果你的 MCP 服务需要监听本地端口，先确认端口有没有起来。

lsof -i :3000 curl http://127.0.0.1:3000/health

Windows 可以用：

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 JSON：stdio 输出被日志污染，检查标准输出。

如果客户端日志不够详细，可以先写一个包装脚本，把启动过程输出到文件：

#!/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指向这个脚本。确认问题后再换回正式命令，避免调试脚本长期留在线上配置里。