MCP error -32602 是什么意思？这个错误码有歧义，别只按「参数错了」查
配 MCP 时看到这么一条：
MCP error -32602
或者带上下文的形式，比如 modelcontextprotocol/servers 仓库的 issue #3074（已关闭）里那条：
Memory MCP, schema validation error: MCP error -32602
-32602 在 JSON-RPC 里的标准含义是 Invalid params（参数无效）。看到这个词，第一反应通常是「我哪个参数写错了」，然后去逐个核对调用参数。
这个方向不能说错，但很可能不够。 因为按官方调试文档的说明，这个错误码同时覆盖好几种不同的情况——它是 MCP 里歧义最大的一个码。
一、这个码的歧义在哪
官方调试文档在讲连接问题排查时，专门点出了一件事：
每个请求都必须携带这两个 _meta 字段：
io.modelcontextprotocol/protocolVersionio.modelcontextprotocol/clientCapabilities
（另外客户端还应该带上 io.modelcontextprotocol/clientInfo。）
缺少任何一个必填字段，会被以 -32602（Invalid params）拒绝。
然后官方紧跟着补了一句关键的话：这个错误码同时也用于很多其他的格式错误。
所以 -32602 实际上至少覆盖两类完全不同的问题：
| 类别 | 具体是什么 | 该怎么查 |
|---|---|---|
| 协议层缺字段 | 请求的 _meta 里少了必填的 protocolVersion 或 clientCapabilities | 查客户端/SDK 版本与实现 |
| 业务层参数错 | 你调工具时传的参数不符合 schema | 查工具的参数定义和你传的值 |
这两类的排查方向完全相反：一个要往客户端和 SDK 那边查，一个要往你的调用参数查。
看到 -32602 不能直接断定是哪一类——这是本文最需要记住的一句。
二、怎么分清是哪一类
几个能快速分开的信号：
第一，看报错有没有带 schema 相关的描述。
像 issue #3074 那条 schema validation error: MCP error -32602，前面明确写了 schema validation——这指向业务层的参数校验，也就是你传的参数不符合工具定义的结构。
如果报错只有一个光秃秃的 -32602，没有任何补充信息，那协议层的可能性更大。
第二，看是不是所有调用都失败。
- 所有调用都报 -32602 → 更像协议层。因为协议层的必填字段是每个请求都要带的，缺了就全军覆没
- 只有某个工具、某种参数组合报 → 更像业务层
这条是最好用的判断，因为它不需要你看协议细节。
第三，看是不是换了客户端就好。
同一个 MCP 服务，用 MCP Inspector 连能用、用某个客户端连就报 -32602——那基本可以锁定在客户端的实现或版本上。
这也是官方为什么把 Inspector 列为排查第一站：它能把「服务端的问题」和「客户端的问题」一刀切开。
三、跟另外两个码区分开
MCP 里还有两个码，比 -32602 精确得多。认出它们能省很多事，因为它们的报错内容里直接带答案。
-32022：UnsupportedProtocolVersionError
含义是协议版本不支持。
官方给的关键信息：它的 data 字段会列出服务端支持的版本。
所以撞上 -32022，不用猜、不用查文档——直接看 data 字段里列的版本，对齐过去就行。
配套的排查动作是调 server/discover，看服务端支持哪些协议版本。
-32021：MissingRequiredClientCapabilityError
含义是：服务端需要某项能力，但请求的 clientCapabilities 里没有声明。
官方举的例子是 elicitation（服务端需要向用户征询信息的能力）。
同样地，这条报错会点名缺哪些能力——答案就在报错里。
三个码放在一起
| 码 | 名称 | 答案在哪 |
|---|---|---|
-32602 | Invalid params | 不在报错里，需要自己判断是协议层还是业务层 |
-32021 | MissingRequiredClientCapabilityError | 在报错里，它会点名缺哪些能力 |
-32022 | UnsupportedProtocolVersionError | 在报错里，data 字段列出支持的版本 |
只有 -32602 需要动脑子，另外两个照着报错做就行。
顺带提一个不同性质的：-32603 是 Internal error（服务端内部错误）。modelcontextprotocol/typescript-sdk 的 issue #291（已关闭）里那条 McpError: MCP error -32603: keyValidator._parse is not a function 就是这个码。它说的是服务端内部出错了，跟你传的参数没关系——社区普遍往依赖版本不匹配的方向查，但那条 issue 里没有官方结论，只能当作排查方向。
四、排查顺序
- 看报错里有没有额外描述（比如 schema validation）
- 有 → 业务层参数问题，走第 4 步
- 没有 → 继续
- 看是不是所有调用都失败
- 全失败 → 协议层，走第 3 步
- 只有部分失败 → 业务层，走第 4 步
- 协议层：
- 用 MCP Inspector 单独连一次，划清是客户端还是服务端
- 检查客户端和 SDK 的版本
- 调
server/discover看协议版本是否对得上 - 如果报的其实是 -32022 或 -32021，答案就在报错内容里，直接照着改
- 业务层：
- 对照工具的参数定义，检查字段名、类型、必填项
- 用 Inspector 直接调一次那个工具，Inspector 能让你手工构造参数，比在客户端里反复试快得多
五、为什么 Inspector 在这里特别有用
本文提了三次 Inspector，值得说清楚为什么。
官方调试文档把它描述为交互式、跨传输的测试 UI，能连 stdio 或 Streamable HTTP 的服务、调用工具、看通知流，并且明确建议把它作为排查的第一站。
对 -32602 这种有歧义的错误码，它的价值在于能做受控实验：
- 同一个服务，Inspector 连得上 → 服务端没问题，去查客户端
- Inspector 也报同样的错 → 跟客户端无关，去查服务端
- 在 Inspector 里手工改参数再调一次 → 立刻知道是不是参数的问题
在客户端里反复试，每一轮都要重启客户端、重新触发场景；在 Inspector 里试，一次几秒钟。
六、为什么会缺必填字段
上面说了「协议层缺字段」这一类，但一个正常的客户端不该缺这些字段——那为什么还会发生？
几种现实中的情况：
客户端版本旧。 必填字段是随协议版本演进的。规范里新增了必填项，而你的客户端还是按旧版本构造请求，就会缺。这类问题的解法是升级客户端或 SDK，而不是改你的服务端。
自己写的客户端实现不完整。 如果你在用某个 SDK 自己搭客户端，可能漏了某些字段的设置。这种情况下 Inspector 特别有用——用 Inspector 连同一个服务，对比它发的请求和你发的请求有什么不同。
中间有代理或封装层。 有些集成方案会在客户端和服务端之间加一层转发。如果那一层重新构造了请求而没有透传 _meta，字段就丢了。这一类最难查，因为两端的代码看起来都是对的。
判断的方法还是那条：全部调用都失败，指向协议层；只有部分失败，指向业务层。 协议层的必填字段是每个请求都要带的，缺了不可能只影响一部分调用。
七、业务层参数错的常见形态
如果确定是业务层（也就是你传的参数不符合工具定义），常见的几种：
- 字段名拼错，或者用了驼峰写成下划线
- 类型不对：该传数字传了字符串、该传数组传了单个值
- 缺必填字段，或者传了 schema 里没定义的额外字段
- 枚举值不在允许范围内
- 嵌套结构层级不对
排查方法：拿工具的参数定义（schema）对着看。Inspector 能显示工具的参数结构，比翻文档快。
一个实用技巧：从最小的合法参数开始试。只传必填项，能通过就逐个加可选项，加到哪个报错就是哪个的问题。比一次传全部然后逐个排除快得多。
八、总结
-32602（Invalid params）有歧义，它同时覆盖「协议层缺必填_meta字段」和「业务层参数不合 schema」。- 必填字段是
io.modelcontextprotocol/protocolVersion和io.modelcontextprotocol/clientCapabilities（另外应带clientInfo）。 - 分清两类的最快信号：全部调用都失败 → 协议层；只有部分失败 → 业务层。
-32021和-32022比它精确得多，答案直接写在报错内容里（缺哪些能力、支持哪些版本），照着改就行。-32603是服务端内部错误，跟你的参数无关。- 用 MCP Inspector 做受控实验，一刀切开客户端和服务端的问题，比在客户端里反复试快一个数量级。
本文所引官方内容来自 Model Context Protocol 官方调试文档，issue 编号来自 modelcontextprotocol 的 servers 与 typescript-sdk 仓库，核对日 2026-08-08。协议版本与错误码定义会随规范演进，以官方规范为准。