mcpsnoop：MCP の呼び出し現場をターミナルで見る

MCP server をデバッグするとき、いちばん困るのはプロトコルそのものより、実際の現場が見えないことだ。

Claude Code、Codex、Cursor で tool が呼ばれない。理由は、capability が client に読まれていないのかもしれないし、モデルが選ばなかったのかもしれない。引数 schema が期待と違うのか、request は出たが server が止まっているのかもしれない。ログを開き、breakpoint を置き、MCP Inspector を動かすことはできる。ただ、それらは「テスト用 client」の挙動しか見ていなかったり、request が server に届いた後の状態しか見せてくれなかったりする。

今日メモしておきたい kerlenton/mcpsnoop は、このかなり具体的な問題を扱う。実際の MCP client と実際の MCP server の間に透明プロキシとして入り、JSON-RPC frame をコピーしてターミナル TUI に表示する。別のデバッグ client を起動するのではなく、Codex、Claude Code、Cursor などの実 client が server と何を話しているかを見るための道具だ。

2026-07-08 時点で GitHub repository page、README、release page、commits page、LICENSE、Git history から確認できる公開情報では、kerlenton/mcpsnoop は 226 stars、13 forks。主言語は Go で、GitHub の言語統計では Go が約 99.5%。ライセンスは MIT。初期化 commit は 2026-06-27 10:25:46 UTC、GitHub search result が示す最新 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、session export
Stars	226
Forks	13
主言語	Go
ライセンス	MIT
初期化 commit	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 が tool を選ぶ場面、引数を送る場面、capability を処理する場面、response を待つ場面にあるかもしれない。

mcpsnoop の使い方は、server command を一段包む形になる。

{
  "mcpServers": {
    "my-server": {
      "command": "mcpsnoop",
      "args": ["--", "node", "build/index.js"]
    }
  }
}

-- の後ろは、もともと server を起動していた command のままだ。実 client はいつも通りこの server を起動し、mcpsnoop はその間で byte を転送しながら JSON-RPC frame をローカルログと TUI にコピーする。streamable HTTP server には、mcpsnoop http --target http://localhost:3000/mcp --listen :7000 という reverse proxy mode もある。

この設計のよいところは、境界が分かりやすいことだ。server のコードを変える必要はないし、client に別のデバッグ protocol を使わせる必要もない。同じ client、同じ server、同じ data path の request と response を見る。

ログより MCP session を追いやすい

もちろん、普通のログでも問題は追える。ただ、MCP の失敗は一行の error だけでは説明しにくい。

tool list が client に正しく見えているか；
ある tools/call request がどんな引数を持っていたか；
server が stderr を出したか；
どの call が slow、pending、error になったか；
request id と response がどう対応しているか；
capability、sampling、roots のような双方向 request が出ているか。

mcpsnoop はこれらを TUI で扱えるようにする。README にある keybinding には、詳細表示、filter、列 sort、copy、pause、follow、capability 表示、call replay、session export が並ぶ。filter も実用寄りで、tool:、method:、id:、dir:、kind:、status: を組み合わせられる。たとえば method:tools/call status:error のように、失敗した tool call だけを見ることができる。

大量の JSON log に grep をかけるより、このほうがずっと楽だ。特に、agent がなぜ期待通りに tool を呼ばなかったのか、server がなぜ時々止まるのかを調べるときに効く。

export と remote debug も実用的

mcpsnoop は live stream を見るだけではない。session をローカルディスクに保存し、TUI は過去 session を backfill できる。捕捉した内容は json、html、text に export できる。bug report に secret を消した HTML を添付したり、JSON を script に渡してさらに分析したりできる。

README には remote workflow も用意されている。live view では SSH remote socket forwarding で、remote machine の mcpsnoop socket を手元に戻す。post-mortem では、remote の session JSONL を SSH 経由で mcpsnoop open - に pipe できる。この選択はかなり堅実だ。独自の remote transport を増やすのではなく、既存の SSH の認証、暗号化、host verification、audit 境界をそのまま使う。

最新 v0.4.0 もこの方向を進めている。release page では、よくある secret key の redaction preset と、stdin から直接 session を開く機能が追加されたことが分かる。デバッグツールでは、派手な画面よりこういう細部のほうが大事なことが多い。

向いている人

成熟した MCP server を一つ入れているだけなら、mcpsnoop を毎日開く必要はないかもしれない。

ただ、次のような人にはすぐ役に立つ。

MCP server を書いていて、実 client が正しい capability を見ているか確認したい人；
Codex、Claude Code、Cursor など複数 client で同じ server を試している人；
「モデルが tool を呼ぶはずなのに呼ばない」問題を追っている人；
遅い call、pending の call、error response の JSON-RPC 文脈を見たい人；
MCP の障害を同僚や issue に共有するため、session を export したい人。

Inspector を置き換えるというより、Inspector が見にくい層を補うツールだ。つまり、実 client の traffic である。

注意したいところ

第一に、プロジェクトはかなり新しい。初期化 commit は 2026-06-27 で、現在 release は v0.4.0 まで進んでいる。開発は速いが、API や UI は今後も変わる可能性がある。

第二に、mcpsnoop は本物の payload を捕捉する。MCP tool arguments、prompt 断片、tool result、error output には、key や内部情報が含まれることがある。README には --redact-secrets と --redact-key があるが、これは JSON key に基づく best-effort scrub であり、非 JSON や任意の文字列に含まれる秘密をすべて消してくれるわけではない。

第三に、透明プロキシもプロキシである。production に近い環境で使う前に、実行場所、log 保存先、file permission、チームのデータ取り扱いルールを確認したい。HTML や JSON を export するときは、通常のログ証跡と同じ慎重さが必要だ。

第四に、これは「MCP traffic を見えるようにする」道具であって、agent の振る舞いを自動で全部説明するものではない。モデルが tool を呼ばなかったことが分かったら、次は prompt、tool description、schema、権限、client 実装へ戻って原因を判断する必要がある。

まとめ

MCP エコシステムが大きくなるほど、デバッグツールは重要になる。プロトコルが理解不能だからではなく、実際の経路には client、model、server、tool description、JSON schema、permission、network state があり、どこか一つで tool call が消えたり形を変えたりするからだ。

mcpsnoop の考え方は素朴だ。まず本物の JSON-RPC 現場を見せる。小さな Go binary として stdio server を包み、HTTP server を proxy し、terminal TUI で live trace を見せ、session を export して復盤できる。MCP server を作っている人や AI coding client をよく使う開発者にとって、「結局、何を送って何を受け取ったのか」を取り戻すための実用的な道具になっている。