antigravity mcp 报错

你在 Antigravity 里配好一个 MCP 服务器，结果要么启动就红字，要么连上了但工具列表空着，要么调用时参数莫名报错。这篇不讲 MCP 是什么，只给一套从外到内的排查顺序：先看进程起来没有，再看握手通不通，最后看工具调用这一层。照着走一遍，大多数报错能自己定位到具体哪一环。

你在 Antigravity 里配好一个 MCP 服务器，结果要么启动就红字，要么连上了但工具列表空着，要么调用时参数莫名报错。这篇不讲 MCP 是什么，只给一套从外到内的排查顺序：先看进程起来没有，再看握手通不通，最后看工具调用这一层。照着走一遍，大多数报错能自己定位到具体哪一环。

核心思路是从外往里收：进程没起来，后面全是白忙；握手没通，工具列表当然空；工具能列出来但调用失败，问题就在参数或超时上。别一上来就改服务器代码，先把每一层的现象确认清楚。

第一步：先确认服务器进程到底起没起

这一层判断最简单：报错里出现 command not found、ENOENT、spawn 失败，基本就是命令路径或运行时环境的问题，跟 MCP 协议本身没关系。遇到这类报错，别在 Antigravity 里反复重试，先去终端把配置里的启动命令原样跑一遍。

1. 复制启动命令到终端把配置文件里的 command 和 args 拼成一条命令，在项目目录下原样执行，看它能不能在前台正常挂住。
2. 确认依赖装在哪区分全局安装和项目内安装。依赖装在项目 node_modules 里，却用全局命令启动，是最常见的一类错。
3. 对比 shell 环境Antigravity 继承的 shell 环境可能和你手动跑的不是同一个。环境变量、PATH、虚拟环境激活状态都要对一遍。

第二步：握手与传输层，连得上才算进了门

进程起来了但客户端还是连不上，问题就在传输层。stdio 和 HTTP/SSE 两类传输的报错长得完全不一样，先确认自己配的是哪一种，再对着那一类看日志，不要拿 stdio 的经验去套 HTTP。

• 把日志级别调到最细，找到客户端发出初始化请求和服务器应答这两行，确认有没有成对出现
• 只有启动日志没有握手日志，问题在传输层；握手有来有回但后续断了，多半在权限或超时设置
• 改配置时一次只改一个变量，改完立刻复现，避免多因素叠加后无法定位
• 传输层相关配置的说明可以到 /mcp 对照同类服务器的接入写法

第三步：连上了但工具列表是空的

握手成功却看不到工具，这种情况最容易被误判成服务器坏了。先排除一个前提：服务器自己声明的工具清单到底是不是空的。把它单独跑起来，看它暴露了什么，比在客户端里猜快得多。

声明为空

服务器确实没暴露工具，问题在服务器侧而不是客户端

名字冲突

工具名或前缀被同名覆盖，客户端可能只显示一部分，逐个启用再对比数量

权限过滤

权限不足会让工具被静默过滤，通常没有显式报错，只能靠开关前后列表变化来确认

清单字段缺失

有些服务器需要额外的清单或鉴权字段，缺了就不返回工具

逐个启用工具再对比总数，是判断静默过滤最直接的办法。如果关掉某个权限开关后工具数量回来了，说明是过滤而不是配置错误。同类服务器的接入说明可以到 /mcp 对照，看有没有额外的字段要求。

第四步：调用阶段的参数与超时报错

工具列出来了但一调用就错，先分清楚是参数问题还是超时问题。参数报错里，类型不对、数组少包一层、必填字段缺一个，这三类占了大多数。超时则要判断是服务器慢还是上游模型慢，两者的处理方式完全不同。

• 把失败请求的原始参数和完整返回落一份日志，报错信息里往往只给了一个笼统的理由
• 同一工具连续失败时，先退回到手工构造一次最小请求，确认是参数问题还是服务器状态问题
• 超时不要只调大数字，先记录每一步的耗时，定位到具体是哪个环节慢
• 参数结构以工具自身声明为准，不要照着别的服务器的写法套

排完还不行：做一次环境对照

上面四步都走完还是不行，说明问题可能在环境差异上。这时候最高效的动作不是继续读代码，而是换一个参照物做对照。换一台机器、换一个终端，或者找一份能跑通的配置逐行比对。

1. 换机器或换终端同样的配置换环境跑一次，能快速区分是机器环境问题还是配置本身的问题。
2. 逐行比对配置拿能跑通的那份配置逐行比对而不是整体替换，差异往往只有一两行。
3. 记录修复动作把这次的现象、排查路径和最终修复动作写进团队排错清单，下次同类报错直接查表。
4. 留下关键日志关键节点的时间戳和返回码留下来，方便到 /tools/quality-monitor 这类工具里做长期观察。

排查的顺序比排查的技巧更重要：进程、握手、工具列表、调用，一层不通就别跳。