MCP Inspector 怎么用来排查问题？官方建议的第一站，能一刀切开客户端和服务端
排查 MCP 问题时，最耗时的做法是在客户端里反复试：改一下配置，完全退出客户端，重新打开，触发场景，看报错，再改一下……一轮下来几分钟，而你可能要试十几轮。
官方调试文档给的建议是另一条路：把 MCP Inspector 当作排查的第一站。
这篇讲它在排查里的定位——不是「怎么点按钮」，而是它能帮你划清哪些界限，以及为什么这些界限值得先划清。
一、Inspector 是什么
按官方的描述，它是一个交互式、跨传输的测试 UI：
- 能连 stdio 或 Streamable HTTP 的服务
- 能调用工具、提示词、资源
- 能看通知流
官方把它列在三层调试工具的第一位，并明确写了「这应该是你的第一站」。
二、它真正的价值：划清界限
Inspector 的价值不在于功能多，而在于它脱开了客户端。
MCP 的链路至少有三方：你的客户端 → 协议 → 你的服务端。出问题的时候，客户端能告诉你的信息非常有限（通常只有「连接关闭」这种），而你没法判断问题在哪一方。
Inspector 相当于换了一个已知行为正常的客户端。 于是你可以做一次受控实验：
| Inspector 的结果 | 结论 | 接下来查哪 |
|---|---|---|
| 连得上、工具能调 | 服务端没问题 | 去查你的客户端配置、版本、实现 |
| 也连不上 | 跟客户端无关 | 去查服务端：启动、依赖、环境变量、路径 |
| 连得上但调某个工具报错 | 启动和协议都没问题 | 去查那个工具的参数和实现 |
这一次实验，能砍掉一半以上的排查空间。
三、几个典型场景
场景一：报了 -32000 Connection closed，但不知道是谁的问题
这是最常见的场景。客户端报连接关闭，可能是服务端没起来、起来就退了、或者客户端配置有问题。
用 Inspector 连一次：
- Inspector 也起不来 → 服务端本身的问题。去查启动三类（路径问题、配置错误、环境问题），并看日志里的启动记录
- Inspector 起得来 → 你的客户端配置跟 Inspector 用的不一样。对比两边的差异，重点看绝对路径和
env里的环境变量
场景二：报了 -32602，不知道是协议层还是业务层
-32602（Invalid params）在 MCP 里有歧义——它既覆盖「请求缺必填 _meta 字段」，也覆盖各种格式错误。
用 Inspector：
- Inspector 调同一个工具没问题 → 协议层没问题，是你的客户端在构造请求时缺了东西
- Inspector 调也报 → 业务层，去看那个工具的参数定义
而且 Inspector 能让你手工构造参数——改一个字段调一次，几秒钟一轮，比在客户端里触发场景快得多。
场景三：改了服务端代码，想快速验证
官方在「测试更改」那一节给的建议就是这条：
- 改配置 → 重启 MCP 客户端
- 改服务端代码 → 重启客户端（Claude Desktop 必须完全退出再开，只关窗口不算）
- 快速迭代 → 用 Inspector
开发阶段最该用 Inspector 的理由就在这里：每改一行代码就要完全退出并重开客户端，这个循环太慢了，而且「只关窗口不算」这个坑会让你反复怀疑自己的修改到底生效没有。
四、配合日志用
Inspector 解决的是「问题在哪一方」，日志解决的是「具体为什么」。两个配合才完整。
官方给的排查顺序里，这两样是相邻的：
- 查客户端日志
- 确认服务端进程在跑
- 用 Inspector 单独测
- 验协议版本兼容
- 查请求的
_meta字段
实际操作时，推荐这么组合：
一边开着日志，一边用 Inspector 操作。
- macOS：
tail -n 20 -F ~/Library/Logs/Claude/mcp*.log - Windows：
type "$env:AppData\Claude\logs\mcp*.log"
（注意这是 Claude Desktop 的日志路径；用 Inspector 时，服务端打到 stderr 的内容通常在 Inspector 自己的界面里能看到。）
这样你在 Inspector 里点一下，能立刻看到服务端那边发生了什么——比只看一端的信息完整得多。
顺带提醒一句：如果服务端往 stdout 打了日志，stdio 传输下会破坏协议。官方对这条有明确警告，日志必须走 stderr。用 Inspector 排查时如果看到协议流里混着人类可读的文字，那就是撞上这个了。
五、协议版本这一层，Inspector 之后再查
如果 Inspector 也连不上，而服务端进程确实起来了，那问题可能在协议层。官方给的动作是：
- 调
server/discover，看服务端支持哪些协议版本 - 如果报
-32022（UnsupportedProtocolVersionError），它的data字段会列出服务端支持的版本，直接对齐过去 - 如果报
-32021（MissingRequiredClientCapabilityError），它会点名缺哪些能力
这两个码的答案都写在报错里，不用猜。
必填字段方面：每个请求必须带 io.modelcontextprotocol/protocolVersion 和 io.modelcontextprotocol/clientCapabilities，客户端还应带 io.modelcontextprotocol/clientInfo。
六、官方给的开发调试循环
官方把开发过程分成两个阶段，各自的调试重点不同：
1. 初始开发
- 用 Inspector 做基础测试
- 实现核心功能
- 加日志点
2. 集成测试
- 在目标 MCP 客户端里测
- 监控日志
- 检查错误处理
这个顺序值得照做：先在 Inspector 里把服务端本身调通，再拿到真实客户端里集成。 反过来做——一上来就在客户端里调——你会同时面对服务端 bug 和客户端配置问题两类变量，很难定位。
七、什么时候不用 Inspector
也不是所有情况都要开它：
- 报错内容已经指明了答案（比如
-32022的 data 字段列出了支持版本）→ 直接改 - 日志里已经能看到服务端的启动错误（缺依赖、命令找不到）→ 直接修
- 只有某个特定客户端有问题，别的客户端都正常 → 已经划清界限了，直接去查那个客户端
Inspector 是用来消除不确定性的。不确定性已经消除了，就不必再多一步。
八、Inspector 连不上时，说明什么
有一种情况值得单独说：Inspector 也连不上。
这不是坏消息，反而是好消息——它把不确定性消掉了一半。既然换了一个行为已知正常的客户端还是连不上，那客户端这一侧就可以排除了，接下来专心查服务端。
按官方的启动失败三分类去查：
1. 路径问题——服务端可执行文件的路径不对、缺文件、权限不足。官方的建议是给 command 用绝对路径。
2. 配置错误——JSON 语法错、缺必填字段、类型不匹配。这一类最容易验，几秒钟就能排除掉。
3. 环境问题——缺环境变量、变量值不对、权限限制。注意官方明确说过：stdio 启动的服务只自动继承一个有限的环境变量子集，具体是哪些跟平台有关。需要什么就在配置的 env 里显式写。
还有一个容易忽略的：工作目录可能是未定义的（macOS 上可能是 /）。所以配置和 .env 里都要用绝对路径，相对路径在客户端拉起时含义会完全不同。
这几条正好解释了那个经典现象：同一条命令你在终端里跑得好好的，客户端拉起来就挂——因为你的终端有完整的 PATH、有你所在的工作目录，而客户端拉起的进程两样都不一定有。
九、把排查压成一条路径
结合 Inspector 和日志，完整的排查路径是这样：
- 开着日志（macOS
tail -F ~/Library/Logs/Claude/mcp*.log） - 完全退出客户端再打开（只关窗口不算，没有新的启动记录就是没真正重启）
- 看日志里有没有服务端启动记录
- 没有 → 配置层（命令路径、JSON 语法）
- 有但紧接着退出 → 看那条错误（缺依赖、缺环境变量）
- 用 Inspector 单独连一次
- 连不上 → 服务端问题，按上一节三分类查
- 连得上 → 客户端配置问题，对比两边的差异，重点看绝对路径和
env
- 连得上但调工具报错 → 业务层，用 Inspector 手工改参数快速试
- 报
-32021/-32022→ 答案在报错内容里，直接照着改
第 4 步是整条路径的分水岭，也是 Inspector 存在的意义。
十、总结
- Inspector 是交互式、跨传输的测试 UI，官方建议作为排查的第一站。
- 它的核心价值是脱开客户端做受控实验，一次实验就能划清「服务端问题」和「客户端问题」。
- 三种典型用法：定位
-32000是谁的问题、分清-32602是协议层还是业务层、开发时快速验证代码改动。 - 开发阶段尤其值得用——每改一行就完全退出重开客户端太慢，而且「只关窗口不算」的坑会让你怀疑修改有没有生效。
- 配合日志用：Inspector 告诉你问题在哪一方，日志告诉你具体为什么。
-32021和-32022的答案直接写在报错里，不需要 Inspector 也能改。- 官方的开发循环：先在 Inspector 里调通服务端，再拿到真实客户端集成。
本文所引官方内容来自 Model Context Protocol 官方调试文档，日志路径来自该文档中 Claude Desktop 的说明，核对日 2026-08-08。工具形态与协议细节会演进，以官方文档为准。