mcpsnoop：把 MCP 调用现场放进终端里看
调 MCP server 时，最麻烦的往往不是协议本身，而是你看不到真实现场。
一个工具在 Claude Code、Codex、Cursor 里没有被调用，可能是能力声明没被客户端读到，可能是模型没有选它，可能是参数 schema 不合预期，也可能是请求已经发出但 server 卡住了。你当然可以打开日志、加断点、跑 MCP Inspector，但这些手段经常只能看到“测试客户端”的行为，或者只能看到请求已经到达 server 之后的状态。
今天想记下的 kerlenton/mcpsnoop，切的是这个很具体的问题：它把自己放在真实 MCP client 和真实 MCP server 中间，作为一个透明代理复制每一帧 JSON-RPC，再用终端 TUI 展示出来。换句话说，它不是另起一个调试客户端，而是让你看见 Codex、Claude Code、Cursor 等真实客户端到底和 server 说了什么。
按 GitHub repository page、README、release page、commits page、LICENSE 和 Git history 在 2026-07-08 能看到的公开信息，kerlenton/mcpsnoop 当前有 226 stars、13 forks。仓库主语言是 Go，GitHub 语言统计中 Go 约 99.5%，许可证是 MIT。仓库初始化提交是 2026-06-27 10:25:46 UTC，GitHub 搜索结果显示最近 push 是 2026-07-08 09:19:34 UTC。默认分支是 main，最新 release 是 v0.4.0，发布时间为 2026-07-08 09:11 UTC。
项目概览
| 属性 | 详情 |
|---|---|
| 仓库 | kerlenton/mcpsnoop |
| 定位 | 透明 MCP proxy、JSON-RPC trace、终端 TUI、会话导出 |
| Stars | 226 |
| Forks | 13 |
| 主语言 | Go |
| 许可证 | MIT |
| 仓库初始化提交 | 2026-06-27 10:25:46 UTC |
| 最近 push | 2026-07-08 09:19:34 UTC |
| 最新版本 | v0.4.0 |
| 版本发布时间 | 2026-07-08 09:11 UTC |
| 核心入口 | mcpsnoop demo、mcpsnoop -- <server>、mcpsnoop http --target ...、mcpsnoop export |
它看的是“真实路径”
mcpsnoop 的 README 把问题讲得很直接：MCP Inspector 会作为自己的 client 连接 server，所以它不一定能复现你的真实 client 行为。真实问题可能恰好发生在 client 选择工具、发送参数、处理 capability 或等待响应的那一段。
mcpsnoop 的用法更像给 server 命令套一层壳：
{
"mcpServers": {
"my-server": {
"command": "mcpsnoop",
"args": ["--", "node", "build/index.js"]
}
}
}-- 后面还是原本启动 server 的命令。真实 client 照常启动这个 server，mcpsnoop 在中间转发字节，同时把 JSON-RPC 帧复制到本机日志和 TUI。对于 streamable HTTP server，它也提供 mcpsnoop http --target http://localhost:3000/mcp --listen :7000 这种反向代理模式。
这个设计的好处是边界清楚。它不要求你改 server 代码，也不要求 client 用另一个调试协议。你看到的就是同一个 client、同一个 server、同一条数据路径上的请求和响应。
比日志更适合看 MCP 会话
纯日志当然也能排查问题，但 MCP 的失败经常不是一行 error 能解释的。
- 工具列表有没有被客户端正确看到；
- 某个
tools/call请求到底带了什么参数； - server 有没有发出
stderr； - 哪些调用是
slow、pending、error； - 某个 request id 对应的 response 是哪一条；
- capability、sampling、roots 这类双向请求有没有出现。
mcpsnoop 把这些都放进 TUI 里处理。README 里列出的快捷键包括进入详情、过滤、按列排序、复制、暂停、follow、查看 capability、replay 调用和导出 session。过滤语法也偏实用，可以按 tool:、method:、id:、dir:、kind:、status: 组合，比如只看 method:tools/call status:error。
这比“在一堆 JSON 日志里 grep”舒服很多，尤其适合调试 agent 为什么没有按预期调用工具，或者 server 为什么偶尔挂住。
导出和远程排查是加分点
mcpsnoop 不只看 live stream。它会把 session 落到本机磁盘，TUI 可以 backfill 过去的会话，也可以把捕获结果导出成 json、html 或 text。这对复盘很有用：你可以在 bug report 里附一个删敏后的 HTML，或者把 JSON 交给脚本进一步分析。
README 还专门写了远程工作流：live view 时用 SSH remote socket forwarding，把远端机器上的 mcpsnoop socket 转回本机；post-mortem 时可以直接通过 SSH 把远端 session JSONL 管道到 mcpsnoop open -。这个选择很克制，不另外发明一套远程传输，而是复用已有 SSH 的认证、加密和审计边界。
最新 v0.4.0 也延续了这个方向。release 页面显示，这个版本加入了常见 secret key 的 redaction preset，并支持从 stdin 直接打开 session。对调试工具来说，这些细节比多一个炫酷面板更重要。
适合谁用
如果你只是装了一个成熟 MCP server，平时也不改它，mcpsnoop 可能不是每天都需要打开的工具。
但下面几类人会很快用上：
- 正在写 MCP server，需要确认真实 client 是否看到正确能力；
- 在 Codex、Claude Code、Cursor 等多个 client 间测试同一个 server；
- 排查“模型明明应该调用工具却没有调用”的问题；
- 想看慢调用、挂起调用和错误响应的完整 JSON-RPC 上下文；
- 需要把一次 MCP 故障导出给同事或 issue 讨论。
它的价值不在于替代 Inspector，而是补上 Inspector 不容易覆盖的那一层：真实客户端流量。
需要注意的地方
第一，项目很新。仓库初始化提交在 2026-06-27，当前 release 已到 v0.4.0，迭代速度很快，但 API 和交互仍可能继续变化。
第二，它会捕获真实 payload。MCP tool arguments、prompt 片段、工具返回、错误输出里都可能有密钥或内部数据。README 里提供了 --redact-secrets 和 --redact-key，但也说明这是尽力而为的 JSON key scrub，不会神奇地清掉所有非 JSON 或任意字符串里的秘密。
第三，透明代理仍然是代理。调试生产环境前，要确认它的运行位置、日志保存路径、文件权限和团队的数据处理规则。尤其是导出 HTML 或 JSON 时，要把它当作日志证据处理。
第四，它主要解决“看见 MCP 流量”，不是自动解释所有 agent 行为。看到模型没有调用工具之后，下一步仍然要回到 prompt、tool description、schema、权限和 client 实现去判断原因。
小结
MCP 生态继续长大后，调试工具会变得越来越重要。不是因为协议复杂到不能理解，而是因为真实链路里有 client、模型、server、工具描述、JSON schema、权限和网络状态，任何一层都可能让工具调用消失或变形。
mcpsnoop 的思路很朴素：先把真实 JSON-RPC 现场摆出来。它是一个小 Go 二进制，可以包装 stdio server，也可以代理 HTTP server，用终端 TUI 看 live trace，再把 session 导出做复盘。对正在做 MCP server 或重度使用 AI coding client 的开发者来说，这正好补上了“我到底发了什么、收到了什么”的那块空白。