MCPデバッグで、「クライアントは確かにツールを呼んでいるはずなのに、なぜか結果が返らない」「引数は本当に正しく渡っているのか」と手が止まった経験はないだろうか。mcpsnoop は、その”見えない通信”をターミナルにそのまま映し出す、MCP専用のトラフィック可視化ツールだ。作者は自ら 「Wireshark for MCP(MCP版Wireshark)」 と表現している。
ネットワークエンジニアがパケットの流れを疑うときWiresharkを立ち上げるように、MCPエージェントの挙動を疑ったときに立ち上げるのがmcpsnoopだ。本記事では、MCPデバッグがなぜ難しいのか、mcpsnoopがどんな仕組みでその難しさを解くのか、そして実際の画面で何が見えるのかを、公式リポジトリの情報と実際のデモをもとに解説する。
MCPそのものの仕組みを先に押さえたい読者は、MCPサーバーの作り方2026年完全ガイド:TypeScript・Python両対応チュートリアル を先に読むと本記事の理解が速い。
- ・mcpsnoopとは:MCPサーバーとクライアント間のJSON-RPC通信を可視化する「MCP版Wireshark」。Go製シングルバイナリ・MIT。
- ・解決する課題:MCPのtool callはブラックボックス。失敗しても「何を送り何が返ったか」が見えない問題を解く。
- ・仕組み:観測用の別クライアントではなく、通信経路そのものに割り込む透過プロキシ。実クライアントの本物のトラフィックを覗く。
- ・見えるもの:tool call・引数・レスポンス・所要時間・遅い/ハングした呼び出し・壊れたフレームをTUIでライブ表示。
- ・公式Inspectorとの違い:Inspectorは自分でテスト呼び出しを発行する。mcpsnoopは実運用中の通信をそのまま捕捉する。
1. mcpsnoopとは何か——MCPデバッグのためのtool call可視化ツール
mcpsnoopは、MCP(Model Context Protocol)サーバーとAIクライアントの間を流れるJSON-RPCメッセージを、ターミナル上でそのまま観測できるデバッグツールだ。Go言語で書かれた単一バイナリで、ライセンスはMIT、リリースは2026年7月時点でv0.8.0まで進んでいる。
MCPは、Claude CodeやCursorといったAIツールが外部のツール・データに接続するための共通規格だ。その通信の実体はJSON-RPC 2.0のメッセージ交換だが、普段この中身は開発者の目に触れない。クライアントが tools/call を送り、サーバーが結果を返す——このやり取りは正常時なら意識する必要がないが、うまく動かないときに限って、その中身が見えないことが致命的な障害になる。
まずは実際の動きを見てほしい。以下はmcpsnoopのデモで、Claude CodeがMCPサーバーを叩くたびに、そのtool callがライブでターミナルに流れ込んでくる様子だ。
Wiresharkがネットワークパケットを可視化するのに対し、mcpsnoopが可視化するのはMCPのメッセージだ。この比喩は単なるキャッチコピーではなく、後述する「通信経路に割り込む」という設計思想そのものを言い当てている。
mcpsnoopが刺さる読者
mcpsnoopは、MCPに関わる二種類の開発者の両方に効く。
・MCPサーバーの実装者:自分のサーバーがクライアントに何を返しているか、遅いツールはどれか、壊れたフレームを吐いていないかを確認したい
・MCPの利用者・エージェント開発者:Claude CodeやCursorが実際にどのツールをどんな引数で呼んでいるか、なぜ結果が期待と違うのかを追いたい
どちらも「通信の実体を見たい」という一点で共通している。そしてmcpsnoopは、その一点にだけ集中したツールだ。
2. なぜMCPデバッグは難しいのか——tool callが透明な問題
MCPデバッグが難しい根本理由は、tool callが”透明”であることにある。ここでいう透明とは、見通しが良いという意味ではない。むしろ逆で、存在しているのに見えない——ガラスのように、そこにあるのに素通しになってしまう不透明さのことだ。
通常のMCPセットアップでは、クライアントとサーバーはstdio(標準入出力)でJSON-RPCメッセージをやり取りする。この通信はプロセス間のパイプの中で完結し、開発者のターミナルには何も表示されない。結果として、次のような状況で手掛かりが完全に失われる。
- ・沈黙する失敗:クライアントは「ツールを呼んだが応答がない」とだけ言い、サーバー側のログにも痕跡が残らない。
- ・引数のズレ:クライアントが送った引数と、サーバーが受け取ったと思っている引数が食い違っているが、突き合わせる手段がない。
- ・遅い呼び出し:全体が遅いのは分かるが、どのtool callが時間を食っているのか特定できない。
- ・壊れたストリーム:サーバーがstdoutに余計なログを混ぜてJSON-RPCフレームを破壊しているが、症状は「なぜか動かない」としか見えない。
こうした問題を、従来は print デバッグやサーバー側の手製ロギングで追うしかなかった。だがそれは「サーバーが記録しようと決めたことしか見えない」という致命的な限界を持つ。クライアントが実際に何を送ったかは、サーバー側のログには原理的に完全には映らない。
Claude Code / Cursor"] -->|"tools/call(見えない)"| BOX["stdio パイプ
ブラックボックス"] BOX -->|"response(見えない)"| C BOX -.->|"実体は素通し"| S["MCPサーバー"] S -.-> BOX DEV["開発者"] -.->|"何が起きているか観測できない"| BOX style BOX fill:#3a2a2a,stroke:#c0392b,color:#fff style DEV fill:#1f2933,stroke:#52606d,color:#fff
公式の MCP Inspector もこの問題に対する回答のひとつだが、アプローチが異なる。Inspectorは「サーバーに対してもう一つのクライアントとして接続し、自分でテスト用の呼び出しを発行して挙動を確かめる」ツールだ。これはサーバー単体の動作確認には有効だが、「Claude Codeが実運用で送っている、まさにその通信」を覗くことはできない。テスト環境で再現しない不具合ほど、この差が効いてくる。MCPの全体像は MCPとは何か?AIに手足を与えるプロトコルの仕組みと実践ガイド2026 に詳しい。
3. mcpsnoopの仕組み——通信経路に割り込む透過プロキシ
mcpsnoopが前節の問題を解けるのは、観測点を”横”ではなく”中”に置くからだ。Inspectorが通信を横から眺める別クライアントであるのに対し、mcpsnoopは実際のデータが流れるパイプの中に座り、通り抜けるバイト列をそのまま転送しながら記録する透過プロキシとして振る舞う。
この設計は二つのモードで実現されている。
・shim モード(mcpsnoop -- <server>):クライアントから起動される透過プロキシ。バイト列をサーバーへ素通しで転送しつつ、通過するフレームを捕捉する
・hub / UI モード(mcpsnoop 単体起動):捕捉されたトラフィックをTUI(ターミナルUI)で表示する
この二つは、既知のソケットとディスク上のログを介して通信する。そのため起動順序を気にする必要がない——TUIを先に開いてもいいし、後から開いてもいい。shimが記録したものはディスクに残るので、セッションを後で開き直すこともできる。
仕組みを図にすると、mcpsnoopがクライアントとサーバーの”あいだ”に割り込んでいることがはっきりする。
Claude Code / Cursor / Codex"] -->|"JSON-RPC"| SHIM["mcpsnoop shim
透過プロキシ"] SHIM -->|"素通しで転送"| S["MCPサーバー"] S -->|"response"| SHIM SHIM -->|"素通しで転送"| C SHIM -->|"フレームを記録"| LOG["ソケット と ディスクlog"] LOG --> UI["mcpsnoop TUI
ライブ表示"] style SHIM fill:#0c4339,stroke:#2dd4bf,color:#fff style UI fill:#1e3a5f,stroke:#60a5fa,color:#fff
「データパイプの横から観測するのではなく、パイプそのものに座る」——この一点が、mcpsnoopがクライアントとサーバーが実際にやり取りしている内容を、寸分違わず捕捉できる理由だ。Wiresharkがネットワークインターフェースを流れる本物のパケットを捉えるのと、発想は完全に同じである。
- ・shimは受け取ったバイト列を加工せずそのまま相手へ渡す。だからmcpsnoopを挟んでも通信の意味は変わらない。
- ・記録は転送とは別経路(ソケットとログ)で行うため、観測がクライアントとサーバーの会話を邪魔しない。
4. インストールと3つの使い方——shim・HTTP・demo
導入は、Go製シングルバイナリらしく素直だ。環境に合わせて次のいずれかを選べばいい。
# Go でインストール
go install github.com/kerlenton/mcpsnoop/cmd/mcpsnoop@latest
# macOS / Homebrew
brew install kerlenton/mcpsnoop/mcpsnoop
# もしくは GitHub Releases のビルド済みバイナリを配置
bash・zsh・fish・PowerShell向けのシェル補完も同梱されている。インストール後の使い方は、対象のトランスポートに応じて主に3通りだ。
(1) stdioサーバーを覗く(最頻出)。クライアントのMCP設定で、サーバー起動コマンドの前に mcpsnoop -- を挟むだけでいい。たとえばClaude CodeやCursorの設定ファイルはこうなる。
{
"mcpServers": {
"my-server": {
"command": "mcpsnoop",
"args": ["--", "node", "build/index.js"]
}
}
}
これまで node build/index.js を直接起動していたところに、mcpsnoop -- を前置しただけだ。クライアントから見ればサーバーの挙動は何も変わらない。だが以降、このサーバーへのtool callはすべてmcpsnoopのTUIに流れ込む。
(2) streamable-HTTPサーバーを覗く。リモートのHTTP型MCPサーバーが相手なら、リバースプロキシモードを使う。
# ローカルにプロキシを立て、--target のHTTPサーバーへ中継しながら記録
mcpsnoop http --target https://example.com/mcp
(3) とりあえず動きを見たい。実サーバーを用意する前に体験したいなら、スクリプト済みのセッションを再生する demo がある。
mcpsnoop # ライブTUIを開く
mcpsnoop demo # 収録済みセッションを再生して雰囲気をつかむ
このほか、リモートのUnixソケットをSSHトンネル経由で転送する mcpsnoop remote <user@host> もあり、手元のマシンからリモートサーバーの通信を覗くこともできる(Linux/macOS)。stdio・HTTP・SSHのいずれでも、観測結果は同じTUIに集約される。
- ・最小構成なら設定ファイルは不要。
mcpsnoop --を挟むだけで動く。 - ・細かい制御(ラベル・トレースファイル・秘密のマスキング)が必要になったら、後述の
.mcpsnoop.tomlを足せばよい。
5. TUIで何が見えるか——ストリーム・フィルタ・inspect・replay
mcpsnoopの真価は、捕捉したトラフィックをどう見せるかにある。tool callが流れ始めると、TUIは各フレームを時系列のストリームとして一覧表示する。次の画面が、実際に5回のツール呼び出しを捕捉した状態だ。
この一画面に、MCPデバッグで欲しい情報がほぼ全部載っている。各行は1つのJSON-RPCフレームで、→ が送信、← が応答を表す。
・METHOD・TOOL:initialize / tools/list / tools/call list_tasks のように、どのメソッド・どのツールが呼ばれたか
・DUR(所要時間):応答までの時間。上の画面では search_tasks が1.603秒かかり slow と赤くマークされている
・STATUS:ok / slow / bad。壊れたフレームや不正なRPCは bad として即座に浮かび上がる
・DETAIL:引数や返り値の中身。arguments に何が入っていたかがそのまま見える
画面下部には集計も出る。上の例では「5 calls・p50 2ms・p95 1.6s」「14 frames・3 bad・1 slow」と、パーセンタイル遅延と異常件数が要約されている。「どのtool callが遅く、どれが壊れているか」を、目視で数秒で把握できるわけだ。
操作系——絞り込み・深掘り・再実行
一覧を眺めるだけでなく、キーバインドで能動的に調べられる。主要な操作は画面下部のヒントに出ている(enter inspect / r replay / c caps / / filter / p pause / ? help)。
引数・返り値の全文を展開"] STREAM -->|"スラッシュキー"| FILTER["filter で絞り込み
tool: method: id: dir: kind: status:"] STREAM -->|"r"| REPLAY["replay で呼び出しを再実行"] STREAM -->|"c"| CAPS["capabilities を確認"] STREAM -->|"e"| EXPORT["export でセッション書き出し"] style STREAM fill:#0c4339,stroke:#2dd4bf,color:#fff style INSPECT fill:#1e3a5f,stroke:#60a5fa,color:#fff
とくに強力なのがフィルタとreplayだ。フィルタはスペース区切りのトークンを組み合わせる方式で、tool:・method:・id:・dir:(方向)・kind:・status: を掛け合わせられる。たとえば「tools/call で、かつ status が bad のものだけ」を一発で抽出できる。
replayは、捕捉した呼び出しをそのまま再実行する機能だ。「さっきの失敗した呼び出しを、条件を変えずにもう一度」——バグの再現に何度も同じ操作を繰り返す必要がなくなる。この「捕捉→絞り込み→再実行」の流れは、まさにWiresharkでパケットをフィルタし、フローを追う体験のMCP版だ。
実際のデバッグの流れ——「遅い・壊れた」を切り分ける
具体的なトラブルシュートの手順に落とすと、mcpsnoopの使いどころが分かりやすい。たとえば「エージェントの応答が体感で遅い」という漠然とした症状を追うケースを考える。
- まず全体を眺め、画面下部の集計(
p50/p95)で遅延の分布を確認する。p95が跳ねていれば、一部の呼び出しだけが極端に遅い status:slowでフィルタし、slowとマークされた行だけを抽出する- 該当行で
enterを押してinspectし、どのツール・どんな引数のときに遅いのかDETAILを読む - 原因の仮説が立ったら、サーバー側を修正し、
r(replay)で同じ呼び出しを再実行して改善を確認する
「壊れている(bad)」症状も同じ要領だ。status:bad で絞ると、不正なJSON-RPCフレームや、stdoutに混ざった余計な出力が原因の破損が浮かび上がる。MCPサーバーがうっかり console.log をstdoutに出してストリームを壊すのは典型的な初歩ミスだが、症状は「なぜか動かない」としか見えないため原因特定が難しい。mcpsnoopなら、その混入したバイト列がフレーム破損として直接見える。
- ・stdioトランスポートでは、stdoutはJSON-RPC専用。ログは必ずstderrへ出す。
- ・stdoutに1バイトでも余計な出力を混ぜると、フレームが壊れてクライアントが黙って失敗する。mcpsnoopはこの混入を
badとして可視化する。
何を「見えないもの」として捕捉するか
mcpsnoopが診断してくれる異常は、大きく4種類に整理できる。いずれも従来は「動かない」の一言に丸められていたものだ。
・遅い呼び出し:p50/p95とDUR列で、時間を食っているツールを特定
・ハングした呼び出し:応答が返らないまま止まっているフレームを検出
・ストリーム破損:stdout混入などで壊れたフレームを検出
・不正なJSON-RPC:プロトコル非準拠のメッセージを検出
6. Claude Code × MCP × mcpsnoop の実運用フロー
ここまでの機能を、実際のワークフローに落とし込んでみよう。mcpsnoopのセッション一覧画面には、どのクライアントが接続しているかも表示される。次の画面では、接続元が claude-code v2.1.207 であることがはっきり見える。
claude-code v2.1.207、REQ/RESP/ERR件数と直近アクティビティが並ぶ。enterで開き、eでエクスポートできるClaude CodeでMCPサーバーを開発・利用しているなら、導入は次の3ステップで完結する。
- Claude Codeの
.mcp.json(またはプロジェクト設定)で、対象サーバーのcommandをmcpsnoop、argsの先頭を["--", ...]に書き換える - 別ターミナルで
mcpsnoopを起動してTUIを開く(順序は不問) - Claude Codeで普段どおりエージェントを走らせる——
tools/callがライブでTUIに流れ込む
この構成の価値は、「エージェントが実際に何をしているか」を、推測ではなく実データで確認できる点にある。「Claude Codeがこのツールを呼んでいるはず」という思い込みを、mcpsnoopは肯定も否定もしてくれる。引数が想定と違えばDETAIL列に現れるし、応答が遅ければDUR列に出る。
なお、Claude Code経由のMCP通信は攻撃対象にもなりうる。実際に Claude CodeのMCP通信ハイジャックでOAuthトークンが窃取される攻撃|検知・対応・防御の手順 のような事例も報告されており、通信を可視化する習慣は、デバッグだけでなくセキュリティの観点からも意味を持つ。
7. redaction・CI・エクスポート——本番で使うための機能
通信を丸ごと覗くツールである以上、秘密情報の扱いは避けて通れない。tool callの引数にはAPIキーやパスワードが含まれることがあり、それをそのまま記録・共有するのは危険だ。mcpsnoopはこの点に3層のredaction(マスキング)を用意している。
・key-based:JSONオブジェクトの特定キー名に一致する値を伏せる
・path-based:JSONPath式で狙ったフィールドだけをピンポイントで伏せる
・value-based:トークン状の文字列を正規表現で検出して伏せる
これらは作業ディレクトリの .mcpsnoop.toml で設定する。コマンドラインフラグは設定ファイルの値を上書きするので、既定はファイルに書き、その場だけの変更はフラグで、という使い分けができる。
label = "filesystem"
trace-file = "trace.jsonl"
redact-secrets = true
redact-key = "token,authorization"
redact-path = "$.params.arguments.password"
no-trace = false
- ・チームで共有するエクスポートを作る前に、
redact-secretsとredact-keyを必ず設定する。 - ・リモート観測はSSHトンネル経由でトランスポートの機密性と監査ポリシーを保つ設計。生のポートを直接開かない。
CIゲートとしての check
mcpsnoopは対話デバッグだけのツールではない。check コマンドは、捕捉したセッションを検査してCIパイプラインのゲートにできる。
# セッションにエラー・ストリーム破損・遅い呼び出しがないか検証(しきい値設定可)
mcpsnoop check
エラー・ストリーム破損・警告・遅い呼び出し・未応答の有無をしきい値付きで判定し、条件を満たせば失敗を返す。「MCPサーバーの回帰テストで、遅延やフレーム破損を自動検出する」といった使い方ができる。
エクスポート——共有・トレース連携
調査結果は複数形式で書き出せる。
# セッションを json / html / text / OTLP に書き出し
mcpsnoop export
・JSON:呼び出しの対応関係と所要時間を構造化して保持
・HTML:検索機能つきの自己完結ファイル。ブラウザで開くだけで共有できる
・text:プレーンなダンプ
・OTLP:OpenTelemetryのトレースとして、既存の分散トレーシング基盤へ流し込める
とくにOTLP出力は、MCPの挙動を既存のオブザーバビリティ基盤に統合したいチームにとって実用的だ。単発のデバッグから継続的な監視まで、同じツールで橋渡しできる。
8. MCP Inspector など類似ツールとの比較
MCPのデバッグ手段は複数あるが、それぞれ立ち位置が違う。mcpsnoopと公式MCP Inspector、そして従来のログ手法を並べると、mcpsnoopの独自性がはっきりする。
| 観点 | mcpsnoop | 公式 MCP Inspector | 手製ログ(printデバッグ) |
|---|---|---|---|
| 観測方式 | 通信経路に割り込む透過プロキシ | 別クライアントとして接続 | サーバー内に記録処理を埋め込む |
| 見えるトラフィック | 実クライアントの本物の通信 | 自分で発行したテスト呼び出し | サーバーが記録すると決めたものだけ |
| 遅い/ハングした呼び出し検出 | あり(DUR・slow表示) | 限定的 | 自前実装が必要 |
| 壊れたフレーム検出 | あり(bad表示) | なし | 気づきにくい |
| フィルタ・inspect・replay | TUIで対応 | 一部 | なし |
| エクスポート | JSON/HTML/text/OTLP | 限定的 | ログ形式次第 |
| CIゲート | check で対応 |
なし | 自前実装が必要 |
| 導入の手軽さ | 単一バイナリ・ゼロコンフィグ | ブラウザ起動 | コード改変が必要 |
要点は、Inspectorが「サーバーを能動的にテストする」ツールなのに対し、mcpsnoopは「実運用の通信を受動的に観測する」ツールだという役割の違いだ。両者は排他ではなく補完関係にある。サーバー単体の仕様確認にはInspector、実際のエージェント挙動の調査にはmcpsnoop、という使い分けが自然だ。
- ・新しいサーバーの動作確認・ツール一覧の検証 → MCP Inspector で能動的に叩く。
- ・「実運用でなぜか失敗する」の調査 → mcpsnoop で本物の通信を覗く。
- ・回帰テスト・継続監視 → mcpsnoop の
checkとexport(OTLP)。
自作MCPサーバーの品質を上げたい段階なら、MCPサーバーとは|仕組み・代表的なサーバー一覧・自作手順を2026年最新で解説 で全体像を押さえたうえで、mcpsnoopで実通信を検証する流れが効率的だ。
使う前に知っておきたいこと
万能ではない。導入前に踏まえておくと良い点を挙げる。
・ターミナル前提のツール:TUIベースなので、GUIでリッチに眺めたい用途にはInspectorのブラウザUIの方が向く場面もある
・プロキシを一段挟む:透過とはいえ経路にプロセスが増える。極端にレイテンシに敏感な計測では、その存在を意識しておく
・SSHトンネルはLinux/macOS向け:リモート観測のUnixソケット転送はプラットフォームに依存する
・まだ若いプロジェクト:2026年7月時点でv0.8.0。★も258と伸び盛りで、仕様は今後も動きうる。バージョンを固定して使うと安定する
とはいえ、これらは「通信の実体が見える」という中核価値を損なうものではない。まず本物のトラフィックを1度見る——その一手のコストを劇的に下げるのがmcpsnoopの本質で、上記は運用上の留意点にすぎない。
まとめ
- ・mcpsnoopは、MCPサーバーとクライアント間のtool callを可視化する「MCP版Wireshark」。Go製シングルバイナリ・MITライセンス。
- ・核心は通信経路に割り込む透過プロキシ。観測用の別クライアントではなく、実クライアントの本物の通信をそのまま捕捉する。
- ・TUIで、tool call・引数・レスポンス・所要時間・遅い/壊れたフレームをライブ表示。フィルタ・inspect・replayで能動的に調べられる。
- ・redaction(3層)・CIゲート(
check)・エクスポート(JSON/HTML/text/OTLP)で、対話デバッグから継続監視まで対応。 - ・公式Inspectorが能動的テスト、mcpsnoopが受動的観測。両者は補完関係にある。
MCPエージェントの「なぜこう動くのか分からない」は、通信の実体が見えないことに起因することが多い。mcpsnoopは、その実体を安価に、しかも本物のトラフィックとして映し出す。MCPサーバーを実装する人にも、Claude CodeでMCPを使い倒す人にも、「困ったらとりあえず立ち上げる」一本として手元に置く価値がある。
まずは mcpsnoop demo で雰囲気をつかみ、次に手元のサーバーに mcpsnoop -- を一行挟んでみてほしい。見えなかったものが見えるようになる感覚は、Wiresharkを初めて使ったときのそれによく似ている。
参照ソース
・kerlenton/mcpsnoop — GitHub リポジトリ(README・CLIリファレンス・アーキテクチャ)
・kerlenton/mcpsnoop — Releases(v0.8.0 ほかバージョン履歴)
・Model Context Protocol 公式ドキュメント