MCP 启动时常见错误
1. 环境问题
未找到命令（spawn uvx ENOENT）
MCP Server 可以使用多种语言实现，例如 JavaScript、Python、Java 等。要运行这些服务器，需要在本地预先安装相应的运行环境和工具。有时会遇到上图中类似 “spawn uvx ENOENT” 的报错，这意味着系统中缺少名为 uvx 的可执行文件（例如 uv 提供的命令行工具）。同理，也可能出现 “spawn bunx ENOENT” 等错误，提示缺少 bunx 工具。这些报错的原因本质上都是本地没有安装相应的运行环境或工具，解决办法是在系统中正确安装所需的解释器或包管理工具（如 Python、Node.js、Bun、uv 等）。下面整理了一些常见运行环境的安装文档。
- uv: https://docs.astral.sh/uv/getting-started/installation
- bun: https://bun.sh/docs/installation
- node: https://nodejs.org/en/download
- python: https://www.python.org/downloads
开发机确认环境已安装但仍找不到
由于开发机上的 VSCode 或者 Comate 进程是启动比较早的，最开始启动时继承的环境变量里面并不包含 node 的路径等，所以在你登录开发机后且安装环境变量后，再次检查环境还是会出现找不到的情况，你需要重启 vscode-server 或者 comate-server 进程解决这个问题，命令如下：
1pgrep -u $(whoami) -f comate-server | xargs kill -9 # 如果使用 Comate 登录开发机
2pgrep -u $(whoami) -f vscode-server | xargs kill -9 # 如果使用 icoding 登录开发机重启后即可找到对应的环境变量。
2. node 类型 server 常见问题
存在 npx，但是执行时报错 You must supply a command.
上图这种情况有可能是因为 node 和 npx 版本不匹配导致的，比如 24 版本的 node 对应了一个 10 版本的 npx（正常来说应该是 11 版本），可以通过升级 npm 版本来解决，先尝试 npm install -g npm@latest 升级一下，如果遇到下面这样的报错（EEXIST），尝试 npm install -g --force npm。
1npm error code EEXIST
2npm error syscall symlink
3npm error path ../../../lib/node_modules/npm/man/man1/npx.1
4npm error dest /home/work/.nvm/versions/node/v24.11.0/share/man/man1/npx.1
5npm error errno -17
6npm error EEXIST: file already exists, symlink '../../../lib/node_modules/npm/man/man1/npx.1' -> '/home/work/.nvm/versions/node/v24.11.0/share/man/man1/npx.1'
7npm error File exists: /home/work/.nvm/versions/node/v24.11.0/share/man/man1/npx.1
8npm error Remove the existing file and try again, or run npm
9npm error with --force to overwrite files recklessly.
10npm error A complete log of this run can be found in: /home/work/.npm/_logs/2025-10-30T08_36_49_379Z-debug-0.lognpm 缓存损坏问题
遇到下面类似的错误日志（ENOENT），很有可能就是 npm 缓存损坏，问题，修复方式非常简单，执行 npm cache clean --force && rm -rf ~/.npm/_npx，然后重启 server 即可
1npm error 404 Note that you can also install from a
2npm error 404 tarball, folder, http url, or git url.
3[2025-11-24 16:17:15.286] [INFO] [Supabase] Server supabase: stderr: npm error signal SIGTERM
4[2025-11-24 16:18:31.831] [INFO] [Supabase] Server supabase: stderr: npm error process terminated
5npm ERR! A complete log of this run can be found in: /root/.npm/_logs/2025-11-24T08_17_13_537Z-debug-0.log
6
7[2025-11-24 16:18:32.052] [INFO] [Supabase] Server supabase: stderr: npm warn tar ENOENT: Cannot cd into '/root/.npm/_npx/4958318abc1c38b0/node_modules/which@2.0.2'
8(shas512-BL3TI1L3WP3VTb2yL3g9Y6li4+pwpvXgSGBYWkkQMtNbx9rMD seems to be corrupted. Trying again.
9
10[2025-11-24 16:18:32.065] [INFO] [Supabase] Server supabase: stderr: npm warn tar ENOENT: Cannot cd into '/root/.npm/_npx/4958318abc1c38b0/node_modules/which'
11(shas512-BL3TI1L3WP3VTb2yL3g9Y6li4+pwpvXgSGBYWkkQMtNbx9rMD seems to be corrupted. Trying again.
12
13[2025-11-24 16:18:32.070] [INFO] [Supabase] Server supabase: stderr: npm error code ENOENT
14npm error enoent ENOENT: Cannot cd into '/root/.npm/_npx/4958318abc1c38b0/node_modules/which'
15npm error enoent This is related to npm not being able to find a file.
16npm error enoent3. remote 类型错误（SSE 和 Streamable HTTP 类型）
mcp.json 配置 header 后找不到 header
很有可能是你的 server 有白名单过滤策略，把非白名单前缀的 header 给清理掉了，联系 server 管理员即可
一直处于连接状态
检查 type 或者 transportType 填写是否正确，目前回退仅实现了 Streamable HTTP -> SSE 的 fallback，未来会支持更多检测手段
4. 二进制类型 MCP问题
权限不足
如果你使用的是打包后的二进制 MCP，必须确保连接时这个 server 被赋予了执行权限，如果没有，就会遇到下面类似的问题：
输出中的日志类似
1[2025-12-02 15:56:23.039] [INFO] 等待 mediator 初始化
2[2025-12-02 15:56:23.057] [INFO] 等待 webview 初始化
3[2025-12-02 15:56:24.237] [INFO] 开始初始化 MCP Servers
4[2025-12-02 15:56:24.326] [INFO] 需要禁用的服务器: 无
5[2025-12-02 15:56:24.326] [INFO] 需要启用的服务器: baidu-go-codeseek
6[2025-12-02 15:56:24.326] [INFO] 保持状态的服务器: 无
7[2025-12-02 15:56:24.356] [ERROR] 启用 Server baidu-go-codeseek 失败: spawn ./bin/baidu-go-codeseek EACCES
8[2025-12-02 15:56:24.356] [INFO] MCP Servers 初始化完成