実際に使用するには、サーバーをクライアントのMCP設定に組み込んでください。```json
{
  "mcpServers": {
    "my-server": {
      "command": "mcpsnoop",
      "args": ["--", "node", "build/index.js"]
    }
  }
}

`wrap` は `claude_desktop_config.json` を見つけ、初回に
`claude_desktop_config.json.mcpsnoop.bak` へコピーし、その1つの
サーバーのエントリだけを書き換えます。あなたの書式設定と他のすべてのサーバーはそのまま残ります。
書き換えられたエントリ内では、キーはアルファベット順に戻ります。`unwrap`
はファイルを復元し、どのサーバーもラップされなくなった時点でバックアップを削除します。
どちらを行った後も Claude Desktop を再起動してください。MCP サーバーは起動時に
一度だけ起動されるためです。

その後はいつもどおりクライアントを使用し、UI を開いてください。```bash
mcpsnoop

すべてのレスポンスのHTTPステータスはストリームに表示されるため、JSON-RPCメッセージを独自に持たないレスポンスでも、何も表示されないのではなく、可視のフレームとして表示されます：401チャレンジ、拒否されたOriginに対する403、通知を受け付けたことを示す202、ターゲットにまったく到達できない場合の502です。401の`WWW-Authenticate`ヘッダーは、認証スキームと次に進むリソースメタデータを示すため、そのまま保持され、インスペクタに表示されます。TUIで`status:401`を使うとステータスでフィルタリングでき、`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 の duration を受け付けます。ツールのベースラインはそのまま残されます。ベースラインはセッションではなくサーバーラベルでキー付けされるためです。

実際のパイプの中に存在し、Inspector のように脇に置かれるわけではないため、実際のクライアントとサーバーが互いにやり取りする内容を、サーバーがどの言語で書かれているかに関係なく、正確に確認できます。

## キーバインド

| Key | Action | | Key | Action |
|---|---|---|---|---|
| `enter` | 検査 / ドリルダウン | | `/` | フィルタ |
| `esc` | 戻る | | `:` | コマンド |
| `j` / `k` | 移動 | | `r` | 呼び出しを再生 |
| `g` / `G` | 先頭 / 末尾 | | `c` | ケイパビリティ |
| `ctrl-f` / `ctrl-b` | ページ | | `s` | ツール概要 |
| `p` | 一時停止 | | `y` | コピー |
| `shift`+`<key>` | 列でソート | | `e` | エクスポート |
| `ctrl-d` | セッションを削除 | | `f` | フォロー |
| `?` | ヘルプ | | | |

アプリ内で `?` を押すと、完全なリストが表示されます。

## ストリームのフィルタリング

セッション内で `/` を押し、スペース区切りのトークンをAND条件で組み合わせます。プレーンテキストはメソッド、ツール、ID、ペイロードに一致します。

| Token | Filters by | 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)

| Format | 内容 |
|---|---|
| `json` | 相関付けられた呼び出し、ツールごとの件数と p50/p95/p99 レイテンシ、最も遅い呼び出し、ケイパビリティ、および生フレーム |
| `html` | 検索と折りたたみ可能な JSON を備えた自己完結型のブラウザファイル |
| `text` | 整形済みプレーンテキストのダンプ |
| `har` | 相関付けられた各呼び出しにつき 1 エントリ。ブラウザの開発者ツールや HAR を読み取れるその他のツールで開くことができます |
| `otlp` | 相関付けられた各呼び出しに 1 スパンを持つ OTLP JSON。W3C トレースコンテキストが呼び出し元のトレースを接続し、それ以外の場合はセッションごとに 1 つのトレースが使用されます |

MCP は HTTP ではないため、HAR エントリの URL、ステータスコード、およびタイミングは、
各呼び出しを意図的にマッピングしたものであり、ワイヤートランスクリプトではありません。

OTLP の場合、リクエストの `_meta.traceparent` はその呼び出しのトレース ID と親
スパン ID を提供し、`_meta.tracestate` はスパンに付随して伝搬されます。traceparent が
存在しないか無効な場合、mcpsnoop はセッション由来のトレースを維持し、ステートを保持しません。
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` は入力と同じファイルを出力に指定することを拒否し、一時ファイルを介して書き込み、その後にリネームして所定の場所に配置するため、失敗した実行では以前のファイルが完全な状態で残ります。

`tools/list` の結果で公開されるツールの `inputSchema` と `outputSchema` は、`--redact-key` と `--redact-secrets` の対象外です。スキーマ内の名前は値ではなく型宣言であり、名前自体はいずれにしてもログに残ります。また、`token` というプロパティ配下のサブスキーマをスクラブすると、ツール自身のチェックも一緒に取り除いてしまいます。対象外となるのはその位置だけです。したがって、たまたま `inputSchema` という名前の引数は他の引数と同様にスクラブされ、また、構造ではなくデータを保持する `default`、`const`、`examples`、`enum` で処理は停止します。スキーマ内の何かを指定するには `--redact-path` を使用し、テキストがどこにあっても一致させるには `--redact-value` を使用します。ただし、mcpsnoop が解析する2つのキーワード、`type` と `x-mcp-header` は除きます。

各フラグが到達する範囲は異なるため、推測せずに結果を確認してください。4つすべてがJSON-RPCペイロードをスクラブし、`--redact-key`、`--redact-path`、`--redact-secrets` はそれらのみに到達します。stderr、その他の非JSONテキスト、文字列の内部もスクラブするのは、`--redact-value` だけです。`Mcp-Param-*` ヘッダーは、ミラーするボディ値とともにスクラブされます。その他のエンベロープメタデータ（サーバーラベル、`Mcp-Name`、`Mcp-Method`、HTTPステータス）は、取得されたまま残されます。リダクションはベストエフォートです。したがって、別の出力パスを使用し、共有する前に結果を確認してください。

### 完了した呼び出しをOTLPコレクターへストリーム送信

プロキシをOTLP/HTTP JSONトレースエンドポイントに向けることで、プロキシ実行中にスパンを送信します。コレクターの認証ヘッダーまたはテナントヘッダーには、`--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

The report shows tools that were added or removed, description and `inputSchema`
changes, matching tool calls whose status changed, and notable duration shifts. Calls
are matched by tool name and arguments, so reordered calls still compare correctly.
By default, duration changes must differ by at least 100 ms and 2x; use
`--duration-threshold` and `--duration-ratio` to adjust those cutoffs.

Pass `--exit-code` to gate CI on regressions: it exits non-zero when the after
session drops a tool, changes a tool description, title, input schema, output
schema or annotations, has a call whose status got worse, or slows down.
Improvements (added tools, fixed calls, speedups) still exit zero, and so does an
icon change, which alters how a tool looks without changing what it does.

## Checking sessions in CI

Gate a recorded agent run on errors, stream corruption, protocol warnings,
routing-header mismatches, calls that never got a response, dropped frames that
leave the capture incomplete, tool-definition drift, or use of deprecated
protocol features.

---

レポートには、追加または削除されたツール、説明と `inputSchema` の変更、ステータスが変化した一致するツール呼び出し、および顕著な所要時間の変化が示されます。呼び出しはツール名と引数で照合されるため、呼び出しの順序が変わっても正しく比較されます。デフォルトでは、所要時間の変化は少なくとも100ミリ秒かつ2倍の差が必要です。これらの閾値は `--duration-threshold` と `--duration-ratio` で調整できます。

`--exit-code` を渡すと、回帰に基づいてCIをゲートできます。afterセッションでツールが削除された場合、ツールの説明・タイトル・入力スキーマ・出力スキーマ・注釈が変更された場合、ステータスが悪化した呼び出しがある場合、または動作が遅くなった場合に、非ゼロの終了コードで終了します。改善（ツールの追加、呼び出しの修正、高速化）は引き続きゼロで終了し、ツールの見た目は変えるが動作は変えないアイコンの変更も同様にゼロで終了します。

## 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` は、シグナルとセッションごとに1つの `<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` に基づいてルーティングする一方、サーバーはボディを読み取ります。したがって、ボディと一致しないヘッダーは、両者が2つの異なるリクエストを見ていることを意味します。`mismatch` シグナルは、そのようなケース、つまりバッチに付随しているが宛先にできないヘッダー、および必須ヘッダーが完全に欠落しているケースを対象とします。

2026-07-28 リビジョンでは、ルーティングヘッダーの欠落は検証エラーとなり、準拠したサーバーは `400` と `-32020` でリクエストを拒否します。mcpsnoop は、セッションがそのリビジョン以降を話すと判明した場合にのみこれを発報します。それ以前のリビジョンではこれらのヘッダーがまったく定義されておらず、そこで省略するのは正しいからです。サーバー自身の `-32020` 拒否も同じシグナルとして扱われます。

HTTP のフィールド値に収まらない名前またはリソース URI は、`=?base64?…?=` センチネル内の Base64 で送信され、比較前にデコードされるため、正しくエンコードするクライアントが誤ってフラグされることはありません。

HTTP の `tools/call` リクエストでは、mcpsnoop は各 `Mcp-Param-{Name}` ヘッダーも表示し、一致するアドバタイズ済みツール定義が判明している場合は、それを注釈付き引数パスと比較します。ネストされたプロパティ、Base64 センチネル、ブール値、数値的に等価な安全な整数は、文字列比較による誤検知なしに処理されます。不明なパラメータヘッダーや、一致するツール定義がないセッションは、観察のみに留まります。キーおよび値ベースの redaction は、キャプチャされたパラメータヘッダー値がシンクに到達する前に適用され、mcpsnoop 自身がスクラブした値が不一致として報告されることはありません。

### ツール定義のドリフトを検出する

サーバーラベルについて最初に観測された完全な `tools/list` が、その信頼できるベースラインになります。以降のセッションは、そのベースラインをフィールドごとに比較します。説明、タイトル、入力および出力スキーマ、annotations とアイコン、さらに追加または削除されたツールも対象です。annotations が最も重要です。`readOnlyHint` 付きで承認されたツールが後になって破壊的であると宣言するのは、このチェックが存在するまさにその「手のひら返し」であり、仕様はクライアントに対して annotations を信頼しないよう指示しているからです。title とアイコンはユーザーが見るものであるため追跡され、仕様ではツールの `title` が `annotations.title` とその名前よりも上位にランク付けされます。sessions テーブルとツールサマリーは、MCP トラフィックをブロックしたり変更したりせずにドリフトをフラグします。

annotations は仕様のデフォルトを通して比較されるため、以前から暗黙的に依存していたヒントを明示的に記述し始めたサーバーは報告されません。mcpsnoop がフィールドを追跡する前に記録されたベースラインは、記録されたフィールドについては引き続き機能し、回答できないフィールドを明示します。現在の定義を信頼できるようになったら、`mcpsnoop baseline --accept` で再記録してください。

redaction が記録する内容を変更すると、ドリフトが比較する内容も変わります。`--redact-value` なしで取得したベースラインを、`--redact-value` 付きで取得したキャプチャと照合すると、スクラブされたフィールドが変更されたものとして報告されます。これは正しい動作です。記録された定義が実際に変更されたからです。redaction 設定を変更した後は、`--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 を非推奨にします。これらは少なくとも 1 年間は動作し続けるため、mcpsnoop はそれらをエラーとして扱うのではなくマークします。ストリーム、ケイパビリティインスペクタ、エクスポートはすべてそれらにフラグを付け、各マーカーは置き換え先を示します。

3 つのうち 2 つは、現在、マルチラウンドトリップリクエスト経由でのみ到達可能で、メソッド名はフレーム自体ではなくサーバーの `inputRequests` マップ内に配置されます。これらにもフラグが付けられるため、新しいパターンに移行したサーバーが黙ってレポートを停止することはありません。```bash
mcpsnoop check --fail-on deprecated session.jsonl

その列は警告色を帯び、ERR列の赤になることはありません。また、mcpsnoopは転送するトラフィックについて何も変更しません。

何も解決・取得されません。外部の`$ref`はその形だけで認識され、それが指し示すスキーマが読み込まれることはありません。

### コンテキスト内でサーバーがどれだけのコストになるかを確認する

ツール定義は会話のたびにモデルのコンテキストに入り、ツールの結果は呼び出しのたびに入ります。ツールサマリー（`s`）は、実際に取得したセッションから両方を計測します。

`definitions` 行は固定コストです。つまり、1回の呼び出しが行われる前に、このサーバーの `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 へ注意書きを出力します。リモートが別の場所に解決される場合は、デフォルト以外のその1つの要素を指定してください。```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

For remote workflows, use SSH tunnelling or SSH file transfer so transport auth,
encryption, host verification, key rotation, and audit policy stay in your
existing SSH setup.

リモートワークフローの場合は、SSHトンネリングまたはSSHファイル転送を使用して、トランスポート認証、
暗号化、ホスト検証、鍵ローテーション、監査ポリシーが、
既存のSSHセットアップに維持されるようにします。

## Contributing

Issues and pull requests are welcome. See [CONTRIBUTING.md](https://github.com/kerlenton/mcpsnoop/blob/HEAD/CONTRIBUTING.md) for
the details.

## コントリビューティング

Issueとプルリクエストを歓迎します。詳細は [CONTRIBUTING.md](https://github.com/kerlenton/mcpsnoop/blob/HEAD/CONTRIBUTING.md) を参照してください。

## License

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

## ライセンス

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