要真正使用它，请将你的服务器封装到客户端的 MCP 配置中。```json
{
  "mcpServers": {
    "my-server": {
      "command": "mcpsnoop",
      "args": ["--", "node", "build/index.js"]
    }
  }
}

`wrap` 会找到 `claude_desktop_config.json`，首次运行时会将其复制为
`claude_desktop_config.json.mcpsnoop.bak`，并且只重写那一个
服务器的条目，因此你的格式设置和其他所有服务器都不会被改动。
重写后的条目内部，键会按字母顺序排列。`unwrap`
会恢复该文件，并且一旦没有服务器处于 wrapped 状态，就会删除备份。
在这两种操作之后都需要重启 Claude Desktop，因为 MCP 服务器只在启动时加载一次。

然后像平常一样使用你的客户端，并打开 UI。```bash
mcpsnoop

每个响应的 HTTP 状态都会显示在流中，因此即使响应本身
不携带 JSON-RPC 消息，也仍然是一个可见的帧，而不是什么都没有：
401 挑战、被拒绝的 Origin 上的 403、确认通知的 202，
以及目标完全无法访问时的 502。401 的
`WWW-Authenticate` 头会被原样保留并在检查器中显示，因为它
指明了认证方案以及下一步要访问的资源元数据。使用
`status:401` 可在 TUI 中按状态过滤，或使用 `status:err` 按任何失败过滤。4xx 或 5xx
会被计为错误，因此默认的 `mcpsnoop check` 运行会因此失败。

没有自己的服务器？[实际试一试](https://github.com/kerlenton/mcpsnoop/blob/HEAD/docs/TRY_IT.md)针对一个已发布的
测试服务器，并由你自己的客户端驱动。要检查已经发生的会话，
请参阅[从日志中回顾过去的会话](https://github.com/kerlenton/mcpsnoop/blob/HEAD/docs/POST_MORTEM.md)。

### 配置文件

如果你在项目中重复使用相同的 shim 标志，请将它们放在
当前工作目录下的 `.mcpsnoop.toml` 文件中。```toml
label = "filesystem"
trace-file = "trace.jsonl"
redact-secrets = true
redact-key = "token,authorization"
redact-value = "sk-[A-Za-z0-9]+"
redact-path = "$.params.arguments.password"
no-trace = false

### Homebrew```bash
brew install mcpsnoop

`--older-than` 是必需的（没有会删除任何内容的默认值），接受类似 `30d` 的天数或类似 `72h` 的 Go 持续时间。工具基线不会被触碰，因为基线是按服务器标签而非会话进行键控的。

因为它位于实际的管道中，而不是像 Inspector 那样在旁路，所以它能准确看到真实客户端和服务器彼此通信的内容，无论服务器用什么语言编写。

## 快捷键

| 键 | 操作 | | 键 | 操作 |
|---|---|---|---|---|
| `enter` | 检查 / 下钻 | | `/` | 筛选 |
| `esc` | 返回 | | `:` | 命令 |
| `j` / `k` | 移动 | | `r` | 重放调用 |
| `g` / `G` | 顶部 / 底部 | | `c` | 能力 |
| `ctrl-f` / `ctrl-b` | 翻页 | | `s` | 工具摘要 |
| `p` | 暂停 | | `y` | 复制 |
| `shift`+`<key>` | 按列排序 | | `e` | 导出 |
| `ctrl-d` | 删除会话 | | `f` | 跟踪 |
| `?` | 帮助 | | | |

在应用中按 `?` 查看完整列表。

## 筛选流

在会话中按 `/`，将空格分隔的令牌组合起来（AND 逻辑）。纯文本匹配方法、工具、ID 和负载。

| Token | 筛选依据 | Example |
|---|---|---|
| `tool:` | 工具名称 | `tool:search` |
| `method:` | JSON-RPC 方法 | `method:tools/call` |
| `id:` | 请求 ID，以及任何继续该请求的重试 | `id:7` |
| `task:` | 任务 ID | `task:01J...` |
| `dir:` | 方向 (`c2s`, `s2c`) | `dir:s2c` |
| `kind:` | 帧类型 (`req`, `resp`, `notify`, `stderr`, `invalid`) | `kind:invalid` |
| `status:` | 调用结果 (`ok`, `error`, `cancel`, `late`, `cancelled`, `pending`, `bad`, `warn`, `mismatch`, 或类似 `401` 的 HTTP 状态) | `status:error` |

堆叠令牌以进行更精确的筛选。```text
tool:search status:pending        # in-flight calls to one search tool
status:cancel                     # calls the client gave up on (status:cancelled is a cancelled task)
status:late                       # results that arrived after the cancellation
method:tools/call status:error    # tool calls that failed
dir:s2c kind:req                  # server-initiated requests (servers before 2026-07-28)

| 格式 | 你会得到什么 |
|---|---|
| `json` | 关联的调用、各工具计数及 p50/p95/p99 延迟、最慢调用、能力以及原始帧 |
| `html` | 一个自包含的浏览器文件，带搜索和可折叠的 JSON |
| `text` | 一份格式化的纯文本转储 |
| `har` | 每次关联调用对应一条条目，可在浏览器开发者工具以及任何支持读取 HAR 的工具中打开 |
| `otlp` | OTLP JSON，每次关联调用对应一个 span；W3C trace context 会接入调用方的 trace，否则每次会话使用一条 trace |

MCP 不是 HTTP，因此 HAR 条目中的 URL、状态码和计时是针对每次调用的有意映射，
而非线缆上的真实传输记录。

对于 OTLP，请求的 `_meta.traceparent` 提供该调用的 trace 和父 span ID，
而 `_meta.tracestate` 则随 span 一并携带。当 traceparent 缺失或无效时，
mcpsnoop 会保留会话派生的 trace 且不携带任何状态。mcpsnoop 只观察而不参与，
因此它不会添加自己的供应商条目，并会原样传递调用方的状态。```bash
mcpsnoop export -T html -o out.html                    # an HTML file to open in a browser
mcpsnoop export -T text server.py-48213-7f3a1c9e2b04   # a specific session, as text
mcpsnoop export -T json | jq                           # the newest session, piped to jq
mcpsnoop export -T har -o session.har                  # a HAR file to open in browser devtools
mcpsnoop export -T otlp -o trace.json                  # import into an OTLP-compatible tracing backend

这些标志会改写导出的文件或内存中的 TUI 视图，但绝不会改写源 JSONL。`export` 拒绝输出与输入同名的文件，并通过临时文件写入后重命名到位，因此一次失败的运行会让之前的文件保持完整。

`--redact-key` 与 `--redact-secrets` 不会改动 `tools/list` 结果中所公布的工具的 `inputSchema` 与 `outputSchema`。模式中的名字是类型声明而非值，因此名字本身无论何种情况都会保留在日志中；而清除名为 `token` 的属性下的子模式，会连同工具自身的检查一并删除。豁免仅限该位置，因此恰好名为 `inputSchema` 的参数会像其他任何参数一样被清除；该清除会在 `default`、`const`、`examples` 和 `enum` 处停止，因为这些位置保存的是数据而非结构。如需指定模式内部的某个对象，请使用 `--redact-path`；或使用 `--redact-value`，它匹配任意位置的文本，但 mcpsnoop 解析的两个关键字 `type` 与 `x-mcp-header` 除外。

每个标志覆盖的范围各不相同，因此请检查结果而非想当然。四个标志都会清除 JSON-RPC 载荷，而 `--redact-key`、`--redact-path` 与 `--redact-secrets` 仅作用于这些载荷。只有 `--redact-value` 还会清除 stderr、其他非 JSON 文本以及字符串内部内容。`Mcp-Param-*` 头会与其镜像的正文值一同被清除；其他信封元数据——服务器标签、`Mcp-Name`、`Mcp-Method` 与 HTTP 状态——均按捕获原样保留。清除是尽力而为的操作，因此请使用单独的输出路径，并在分享前先查看结果。

### 将已完成的调用流式发送到 OTLP 收集器

在代理运行期间，将其指向 OTLP/HTTP JSON 追踪端点即可发送 span。可重复指定 `--otlp-header` 以设置收集器认证或租户头。```bash
mcpsnoop \
  --otlp-endpoint http://localhost:4318/v1/traces \
  --otlp-header "Authorization=Bearer $OTLP_TOKEN" \
  -- node build/index.js

mcpsnoop http \
  --target http://localhost:3000/mcp \
  --otlp-endpoint http://localhost:4318/v1/traces

报告显示新增或移除的工具、描述和 `inputSchema` 变更、状态发生变化且匹配的工具调用，以及显著的时长变化。调用按工具名称和参数进行匹配，因此重新排序的调用仍能正确比较。默认情况下，时长变化至少需相差 100 毫秒且达到 2 倍；使用 `--duration-threshold` 和 `--duration-ratio` 可调整这些阈值。

传递 `--exit-code` 可在 CI 中基于回归进行门控：当后续会话移除工具、更改工具描述、标题、输入 schema、输出 schema 或注释，出现状态变差的调用，或发生性能下降时，它会以非零状态退出。改进（新增工具、修复调用、速度提升）仍以零状态退出，图标更改（仅改变工具外观而不改变其功能）也是如此。

## 在 CI 中检查会话

根据错误、流损坏、协议警告、路由头不匹配、从未收到响应的调用、导致捕获不完整的丢弃帧、工具定义漂移，或使用已弃用的协议功能，对录制的代理运行进行门控。```bash
mcpsnoop check [--format text|junit|sarif] [--fail-on error,invalid,warn,mismatch,pending,late-result,drift,deprecated,incomplete,schema] [session-id|log.jsonl|-]

丢帧计数也会随产物一并保存，因此，一个低估了自身丢帧数的捕获无论在哪里
打开都会如实体现这一点：JSON 导出中的 `missing_frames`、HAR 中的
`log.comment`，以及 OTLP 中的 `mcpsnoop.session.missing_frames`
资源属性。```bash
mcpsnoop check build-agent
mcpsnoop check --fail-on error,invalid artifacts/session.jsonl
mcpsnoop check --fail-on mismatch gateway-run.jsonl

### 在 CI 已经查看的地方报告

`--format junit` 为每个信号和会话写入一个 `<testcase>`，其失败遵循与文本输出相同的 `--fail-on` 选择。```yaml
- name: Check captured MCP session
  run: |
    mkdir -p test-results
    mcpsnoop check --format junit artifacts/session.jsonl > test-results/mcpsnoop.xml
- name: Upload mcpsnoop JUnit report
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: mcpsnoop-junit
    path: test-results/mcpsnoop.xml

### 捕获与请求体不一致的路由标头

在 streamable-HTTP 传输中，网关依据 `Mcp-Method` 和 `Mcp-Name` 进行路由，而服务器读取的是请求体，因此与请求体不一致的标头意味着两者看到的是两个不同的请求。`mismatch` 信号涵盖：标头与请求体不一致、标头搭载在它无法寻址的批次上、以及必需标头完全缺失。

在 2026-07-28 修订版中，缺少路由标头属于校验失败，合规的服务器会以 `400` 和 `-32020` 拒绝该请求。mcpsnoop 仅在确知会话使用该修订版或更高版本时才报告此信号，因为更早的修订版根本没有定义这些标头，在那里省略它们是正确行为。服务器自身的 `-32020` 拒绝也计为同一信号。

无法放入 HTTP 字段值中的名称或资源 URI 会以 Base64 形式置于 `=?base64?…?=` 哨兵中，并在比较之前解码，因此编码正确的客户端永远不会被标记。

在 HTTP `tools/call` 请求上，mcpsnoop 还会显示每个 `Mcp-Param-{Name}` 标头，并且在已知匹配的已发布工具定义时，将其与带注解的参数路径进行比较。嵌套属性、Base64 哨兵、布尔值以及数值等价的安全整数都能被妥善处理，不会因字符串比较而产生误报。未知的参数标头以及没有匹配工具定义的会话仅作观察。基于键和值的脱敏处理会在捕获的参数标头值到达接收端（sink）之前对其生效，而 mcpsnoop 自行擦除的值绝不会被报告为不一致。

### 检测工具定义漂移

对某个服务器标签观察到的第一个完整 `tools/list` 即成为其可信基线。后续会话会逐字段比较该基线：描述、标题、输入和输出 schema、注解和图标，以及新增或移除的工具。注解最为重要，因为一个以 `readOnlyHint` 获批使用、后来却声明自身具有破坏性的工具，正是此项检查所要防范的“撤梯子”（rug-pull）行为，而且规范告知客户端应将注解视为不可信。标题和图标之所以被跟踪，是因为它们是用户实际看到的内容；规范将工具的 `title` 排在 `annotations.title` 和工具名称之上。会话表和工具摘要会标记漂移，但不会阻塞或改变 MCP 流量。

注解通过其规范默认值进行比较，因此服务器开始显式写出它本来就依赖的提示时不会被报告。在 mcpsnoop 开始跟踪某个字段之前记录的基线，对其确实记录的字段仍然有效，并会指出哪些字段它无法回答；一旦你信任当前的定义，请使用 `mcpsnoop baseline --accept` 重新记录。

更改脱敏记录的内容，也就改变了漂移比较的对象。未使用 `--redact-value` 记录的基线，在对照使用该选项进行的捕获检查时，会把被擦除的字段报告为已更改——这是正确的，因为记录下的定义确实发生了变化。更改脱敏设置后，请使用 `--accept` 重新记录。

对于命令名称或目标主机本会冲突的每个服务器，请使用稳定且唯一的 `--label`。基线存储在 mcpsnoop 常规状态目录下，因此 `MCPSNOOP_HOME` 和 `XDG_STATE_HOME` 同样适用。```bash
mcpsnoop check --fail-on drift session.jsonl
mcpsnoop baseline session.jsonl
mcpsnoop baseline --accept session.jsonl  # trust a legitimate definition change
mcpsnoop baseline --reset session.jsonl   # trust the next complete tools/list

`drift` 对于 `check` 是可选启用的；默认的 `error,invalid,warn` 门控保持不变。

### 标记已弃用的协议特性

2026-07-28 修订版弃用了 Roots、Sampling 和 Logging。它们至少还能
再工作一年，因此 mcpsnoop 会将它们标记出来，而不是视为错误。
流、能力检查器和导出都会标记它们，并且每个标记
都会指明替代方案。

这三个中的两个现在只能通过多次往返请求访问，
方法名位于服务器的 `inputRequests` 映射中，而不是在
帧本身上。这些也会被标记，因此迁移到新模式的服务器
不会悄然停止报告。```bash
mcpsnoop check --fail-on deprecated session.jsonl

该列带有警告色，而绝不会是 ERR 列的红色，并且
mcpsnoop 仍然不会改变它转发的流量。

不会解析或获取任何内容。外部 `$ref` 仅凭其形式即可被识别，
它指向的 schema 永远不会被读取。

### 查看服务器在上下文中让你付出的代价

工具定义会在每次对话中进入模型的上下文，工具
结果则会在每次调用时进入。工具摘要（`s`）从你实际捕获的
会话中衡量这两者。

`definitions` 行是固定成本：在发出任何一次调用之前，该服务器的 `tools/list`
所占用的体量。`DEF` 列按工具细分，`RESULT` 则是每个工具的答案迄今为止
所花费的代价。表格保持按错误和延迟排序，因此查看 `DEF`
可找出昂贵的定义；导出按最重优先列出它们。表格下方的一行
会指出单个最重的结果，而总计会将其隐藏。

定义数字是去除了无关紧要空白的 JSON，因此一个美化输出其 `tools/list`
的服务器不会被计为比不这样做的服务器更昂贵，并且同一服务器
在不同捕获中的测量结果相同。`RESULT` 是到达时的字节数：
结果是一次性负载，而非值得规范化的契约。```bash
mcpsnoop export -T json | jq '.summary.definitions'

套接字位于远程端的状态目录下，解析顺序为 `MCPSNOOP_HOME`，
否则为 `XDG_STATE_HOME/mcpsnoop`，再否则为 `~/.local/state/mcpsnoop`。默认情况下，mcpsnoop
会根据你的 `user@host` 假定 Linux 主目录为 `/home/<user>`，并在回退到该假设时
向 stderr 打印一条提醒。如果远程端解析到其他位置，
请指定那个非默认的项。```bash
# a non-Linux or custom home, macOS is /Users/<user> and root is /root
mcpsnoop remote --remote-home /Users/remote-user remote-user@remote-host

# an explicit MCPSNOOP_HOME on the remote
mcpsnoop remote --remote-mcpsnoop-home /srv/mcpsnoop remote-user@remote-host

# an explicit XDG_STATE_HOME on the remote
mcpsnoop remote --remote-xdg-state-home /var/lib/state remote-user@remote-host

若想改为保留本地副本，请使用 scp 将日志复制到你的 sessions 目录中，然后按正常方式
运行 TUI。```bash
# copy the remote logs into your local sessions directory
mkdir -p ~/.local/state/mcpsnoop/sessions
scp remote-user@remote-host:'~/.local/state/mcpsnoop/sessions/*.jsonl' \
  ~/.local/state/mcpsnoop/sessions/

# open the TUI, it backfills the copied sessions
mcpsnoop

对于远程工作流，请使用 SSH 隧道或 SSH 文件传输，以便传输认证、加密、主机验证、密钥轮换和审计策略保留在您现有的 SSH 设置中。

## 贡献

欢迎提交 Issue 和拉取请求。详情请参阅 [CONTRIBUTING.md](https://github.com/kerlenton/mcpsnoop/blob/HEAD/CONTRIBUTING.md)。

## 许可证

[MIT](https://github.com/kerlenton/mcpsnoop/blob/HEAD/LICENSE)