Skip to content
Back to search

mcpsnoop

Wireshark for MCP. A transparent proxy that shows every real tool call between your AI client and your MCP servers, live in your terminal.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kerlenton--mcpsnoop/badge.svg)](/listings/kerlenton--mcpsnoop)

HTML

<a href="/listings/kerlenton--mcpsnoop"><img src="/api/listings/kerlenton--mcpsnoop/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

See it right away, with nothing to set up.

mcpsnoop demo

To use it for real, wrap your server in your client's MCP config.

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

Everything after `--` is the command that normally launches your server. Swap in whatever you already use, like `python server.py`, `npx -y @scope/server`, or a compiled binary.

On Claude Desktop you don't have to make that edit by hand.

mcpsnoop wrap my-server     # route my-server through mcpsnoop
mcpsnoop unwrap my-server   # put it back

`wrap` finds `claude_desktop_config.json`, copies it to `claude_desktop_config.json.mcpsnoop.bak` the first time, and rewrites only that one server's entry, so your formatting and every other server are left alone. Inside the rewritten entry the keys come back in alphabetical order. `unwrap` restores the file, and removes the backup once no server is wrapped any more. Restart Claude Desktop after either, since MCP servers are launched once at startup.

Then use your client as usual and open the UI.

mcpsnoop

No flags, no socket paths, no startup order to remember. The shim and the UI find each other on their own, and the UI backfills past sessions from disk.

For a streamable-HTTP server, run mcpsnoop as a reverse proxy.

mcpsnoop http --target http://localhost:3000/mcp --listen :7000

The HTTP status of every response shows in the stream, so a response that carries no JSON-RPC message of its own is still a visible frame rather than nothing. That covers the 401 challenge, the 403 on a rejected Origin, the 202 that acknowledges a notification, and the 502 when the target cannot be reached at all. A 401's `WWW-Authenticate` header is kept verbatim and shown in the inspector, since it names the auth scheme and the resource metadata to go to next. Filter by status with `status:401` in the TUI, or by any failure with `status:err`. A 4xx or 5xx counts as an error, so a default `mcpsnoop check` run fails on it.

No server of your own? [Try it for real](docs/TRY_IT.md) against a published test server, driven by your own client. To inspect a session after it happened, see [review past sessions from logs](docs/POST_MORTEM.md).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 351 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="assets/png/mcpsnoop-lockup.png" alt="mcpsnoop" width="440">
  3. </p>
  4. **Wireshark for MCP.** mcpsnoop sits between your AI client and your MCP server
  5. and records every JSON-RPC frame they exchange, with no change to either side.
  6. Watch it live in your terminal, fail CI on what it finds, or send it to your
  7. tracing backend as OpenTelemetry spans.
  8. [![CI](https://github.com/kerlenton/mcpsnoop/actions/workflows/ci.yml/badge.svg)](https://github.com/kerlenton/mcpsnoop/actions/workflows/ci.yml)
  9. [![Go Reference](https://pkg.go.dev/badge/github.com/kerlenton/mcpsnoop.svg)](https://pkg.go.dev/github.com/kerlenton/mcpsnoop)
  10. [![MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
  11. [![Marketplace](https://img.shields.io/badge/marketplace-mcpsnoop-blue?logo=github)](https://github.com/marketplace/actions/mcpsnoop)
  12. <p align="center">
  13. <img src="docs/demo.gif" alt="mcpsnoop demo">
  14. </p>
  15. ## The problem
  16. The official [MCP Inspector](https://github.com/modelcontextprotocol/inspector)
  17. connects as its own client, so it never sees what *your* client (Cursor, Claude
  18. Code, Codex) actually sends your server. And anything that waits for a request
  19. to arrive can't show the call the model never made, or made with the wrong
  20. arguments. When a tool silently isn't called, capabilities don't line up, or a
  21. call just hangs, you're left digging through logs and guessing.
  22. **mcpsnoop sits in the real data path instead.** Wrap your server command with
  23. it and watch every JSON-RPC frame live, as your real client and server talk.
  24. ## In CI
  25. This page is also the listing for the [mcpsnoop GitHub Action](https://github.com/marketplace/actions/mcpsnoop),
  26. so here is the whole of it. It checks a captured session, files every finding as
  27. a code scanning alert, and fails the job on what you gated on.
  28. ```yaml
  29. permissions:
  30. security-events: write
  31. contents: read
  32. steps:
  33. - uses: kerlenton/mcpsnoop@v0.28.0
  34. with:
  35. session: artifacts/session.jsonl
  36. ```
  37. No capture to hand? Record one session with your own client once, commit it,
  38. and let the action replay it against every build. No model and no API key run
  39. in CI. The replay is checked like any capture, and the job also fails when the
  40. server got worse than in the recording. A server reached over Streamable HTTP
  41. gets `target` with its endpoint, and a recording replays over either transport.
  42. ```yaml
  43. steps:
  44. - uses: kerlenton/mcpsnoop@v0.28.0
  45. with:
  46. replay: tests/mcp/claude-code-session.jsonl
  47. server: node dist/index.js
  48. ```
  49. Pin whichever release you want. The newest is on the
  50. [releases page](https://github.com/kerlenton/mcpsnoop/releases). Every input and
  51. output is in [The GitHub Action](#the-github-action) further down, and every
  52. signal the check can fail on is in [docs/CI.md](docs/CI.md).
  53. ## OpenTelemetry
  54. MCP revision 2026-07-28 deprecates protocol-level Logging and tells
  55. implementations to move to `stderr` on stdio, or to OpenTelemetry for structured
  56. observability. mcpsnoop covers both without touching the client or the server.
  57. A stdio server's `stderr` lines show up in the stream beside its frames, and
  58. every request becomes a span that follows the
  59. [OpenTelemetry semantic conventions for MCP](https://github.com/open-telemetry/semantic-conventions-genai/tree/main/model/mcp).
  60. ```bash
  61. mcpsnoop export -T otlp -o trace.json # spans from a capture
  62. mcpsnoop --otlp-endpoint http://localhost:4318/v1/traces -- node build/index.js # spans as calls complete
  63. ```
  64. A tool call arrives as a span named `tools/call search`, carrying
  65. `mcp.method.name`, `gen_ai.tool.name` and `error.type`, so it lands in a
  66. dashboard built for MCP rather than one built for mcpsnoop. Live tool metrics for
  67. Prometheus are one flag away. Both are in
  68. [docs/OPENTELEMETRY.md](docs/OPENTELEMETRY.md).
  69. ## Quick start
  70. See it right away, with nothing to set up.
  71. ```bash
  72. mcpsnoop demo
  73. ```
  74. To use it for real, wrap your server in your client's MCP config.
  75. ```json
  76. {
  77. "mcpServers": {
  78. "my-server": {
  79. "command": "mcpsnoop",
  80. "args": ["--", "node", "build/index.js"]
  81. }
  82. }
  83. }
  84. ```
  85. Everything after `--` is the command that normally launches your server. Swap in
  86. whatever you already use, like `python server.py`, `npx -y @scope/server`, or a
  87. compiled binary.
  88. On Claude Desktop you don't have to make that edit by hand.
  89. ```bash
  90. mcpsnoop wrap my-server # route my-server through mcpsnoop
  91. mcpsnoop unwrap my-server # put it back
  92. ```
  93. `wrap` finds `claude_desktop_config.json`, copies it to
  94. `claude_desktop_config.json.mcpsnoop.bak` the first time, and rewrites only that
  95. one server's entry, so your formatting and every other server are left alone.
  96. Inside the rewritten entry the keys come back in alphabetical order. `unwrap`
  97. restores the file, and removes the backup once no server is wrapped any more.
  98. Restart Claude Desktop after either, since MCP servers are launched once at
  99. startup.
  100. Then use your client as usual and open the UI.
  101. ```bash
  102. mcpsnoop
  103. ```
  104. No flags, no socket paths, no startup order to remember. The shim and the UI find
  105. each other on their own, and the UI backfills past sessions from disk.
  106. For a streamable-HTTP server, run mcpsnoop as a reverse proxy.
  107. ```bash
  108. mcpsnoop http --target http://localhost:3000/mcp --listen :7000
  109. ```
  110. The HTTP status of every response shows in the stream, so a response that carries
  111. no JSON-RPC message of its own is still a visible frame rather than nothing. That
  112. covers the 401 challenge, the 403 on a rejected Origin, the 202 that acknowledges
  113. a notification, and the 502 when the target cannot be reached at all. A 401's
  114. `WWW-Authenticate` header is kept verbatim and shown in the inspector, since it
  115. names the auth scheme and the resource metadata to go to next. Filter by status
  116. with `status:401` in the TUI, or by any failure with `status:err`. A 4xx or 5xx
  117. counts as an error, so a default `mcpsnoop check` run fails on it, and the call it
  118. answered reads as failed rather than as one still waiting.
  119. No server of your own? [Try it for real](docs/TRY_IT.md) against a published
  120. test server, driven by your own client. To inspect a session after it happened,
  121. see [review past sessions from logs](docs/POST_MORTEM.md).
  122. ## Install
  123. ### npm
  124. No Go toolchain needed. Most MCP servers are written in Node or Python, so this
  125. is the shortest way in.
  126. ```bash
  127. npx mcpsnoop -- node build/index.js
  128. ```
  129. The npm package ships no code of its own. Six platform packages each carry one
  130. build, and npm installs the single one that matches your machine, so there is
  131. nothing to download at install time and nothing to unblock in a proxy. To keep it
  132. around rather than fetching it each run, `npm i -g mcpsnoop`.
  133. ### Homebrew
  134. ```bash
  135. brew install mcpsnoop
  136. ```
  137. ### Go
  138. ```bash
  139. go install github.com/kerlenton/mcpsnoop/cmd/mcpsnoop@latest
  140. ```
  141. Prebuilt binaries for every platform are on the [Releases](https://github.com/kerlenton/mcpsnoop/releases) page.
  142. mcpsnoop ships completions for bash, zsh, fish, and PowerShell. Run
  143. `mcpsnoop completion <shell> --help` for the setup steps, which cover enabling
  144. completion and the install path for your OS.
  145. ## Commands
  146. | Command | What it does |
  147. |---|---|
  148. | `mcpsnoop -- <server>` | wrap a stdio server as a transparent shim |
  149. | `mcpsnoop` | open the live TUI |
  150. | `mcpsnoop --metrics-listen <addr>` | run a headless hub and expose live Prometheus metrics |
  151. | `mcpsnoop http --target <url>` | proxy a streamable-HTTP server |
  152. | `mcpsnoop export` | render a session to json, html, text, har, or otlp |
  153. | `mcpsnoop check` | fail CI on errors, invalid frames, warnings such as a tool result breaking its own outputSchema, routing mismatches, hung calls, late results, calls that may have run twice, tool drift, annotations that loosened or say nothing, or a latency budget |
  154. | `mcpsnoop baseline` | inspect, accept, or reset trusted tool definitions |
  155. | `mcpsnoop diff` | compare tools and calls across two captured sessions |
  156. | `mcpsnoop open` | open a saved session in the TUI |
  157. | `mcpsnoop mock <session>` | serve a captured session back as a stdio MCP server |
  158. | `mcpsnoop replay <session> -- <server>` | drive a server, over stdio or Streamable HTTP, with the client side of a recorded session, and compare the result with the recording |
  159. | `mcpsnoop inventory` | list every server that has run through mcpsnoop on this machine |
  160. | `mcpsnoop stats` | fold every stored capture into one row per server and tool |
  161. | `mcpsnoop clients` | show what each MCP client actually did on the wire, by name and version |
  162. | `mcpsnoop prune` | delete saved session logs older than a cutoff |
  163. | `mcpsnoop wrap <server>` | route one of Claude Desktop's servers through mcpsnoop |
  164. | `mcpsnoop unwrap <server>` | put that server's entry back the way it was |
  165. | `mcpsnoop remote <user@host>` | print the SSH tunnel command |
  166. | `mcpsnoop demo` | play a scripted session |
  167. Run `mcpsnoop help` for the full list, or `mcpsnoop help <command>` for the flags of one.
  168. ## How it compares
  169. Each of these answers a different question, and where a tool sits decides which
  170. questions it can answer.
  171. | Tool | Where it sits | What it is for |
  172. |---|---|---|
  173. | [MCP Inspector](https://github.com/modelcontextprotocol/inspector) | its own client, connected to your server | trying a server by hand, in a browser or from a scriptable CLI |
  174. | [Snyk Agent Scan](https://github.com/snyk/agent-scan) | its own client, launching or connecting to the servers in your configs to read their tools | scanning agents, MCP servers and skills on your machine for prompt injection and vulnerabilities |
  175. | [MCP Observatory](https://github.com/KryptosAI/mcp-observatory) | its own client, launching your server to test, record and verify it | security and regression testing in CI, with attack simulation, schema drift, and record, replay and verify |
  176. | [mcprec](https://github.com/erphq/mcprec) | on the wire, between client and server | recording a session once and replaying it as a test fixture without the network |
  177. | mcpsnoop | on the wire, between client and server | watching what your real client and server say, replaying a real client's session against each build, failing CI on it, and exporting it as OpenTelemetry |
  178. A tool that is its own client sees the calls it makes, not the ones your client
  179. makes, so it cannot show the call your model never made or made with the wrong
  180. arguments. A scanner reads a definition before you trust it. mcpsnoop watches
  181. what happens once you have, including whether the definition changes later.
  182. ## How it works
  183. <p align="center">
  184. <picture>
  185. <source media="(prefers-color-scheme: dark)" srcset="assets/architecture-dark.svg">
  186. <img alt="mcpsnoop sits in the pipe between your AI client and your MCP servers, copying every JSON-RPC frame to a live terminal UI" src="assets/architecture-light.svg" width="760">
  187. </picture>
  188. </p>
  189. mcpsnoop is two roles in one binary. `mcpsnoop -- <server>` is the transparent
  190. shim your client spawns, forwarding bytes verbatim while shipping a copy of every
  191. frame to the hub. `mcpsnoop` with no arguments is that hub and its live TUI. They
  192. pair through a well-known socket and on-disk logs, so neither has to start first.
  193. Because it sits in the actual pipe, not off to the side like the Inspector, it
  194. sees exactly what your real client and server say to each other, whatever the
  195. server is written in. What bounds its memory and its disk is in
  196. [docs/HOW_IT_WORKS.md](docs/HOW_IT_WORKS.md).
  197. ## The GitHub Action
  198. Everything below is what the action does for you. It installs mcpsnoop, checks
  199. the capture, files the findings in the Security tab, and fails the job on what
  200. you gated on.
  201. ```yaml
  202. permissions:
  203. security-events: write
  204. contents: read
  205. steps:
  206. - uses: kerlenton/mcpsnoop@v0.28.0
  207. with:
  208. session: artifacts/session.jsonl
  209. ```
  210. Pin a release, whichever one you want. The newest is on the
  211. [releases page](https://github.com/kerlenton/mcpsnoop/releases). There is no
  212. floating `v1`, deliberately. The pinned release is also the binary the action
  213. installs, so the two can never disagree and there is no version default to go
  214. stale.
  215. | Input | |
  216. |---|---|
  217. | `session` | the `.jsonl` capture to check, or a directory of them, relative to the repository root. Give this or `replay` |
  218. | `replay` | a committed recording to replay against `server` or `target`, which then has its capture checked and fails the job on a regression too |
  219. | `server` | the command that starts the server under test, quoted as on a command line. Required with `replay` for a stdio server. With `target` it starts an HTTP server first, and can be left out when one is already running |
  220. | `target` | the Streamable HTTP endpoint to replay against, such as `http://localhost:3000/mcp`. A credential goes in `replay-args` as `--header`, and the step log shows its value hidden |
  221. | `replay-args` | any other `replay` flags, such as `--read-only`. `--out` is refused, since the action decides where the capture goes |
  222. | `fail-on` | as `--fail-on`, defaulting to what the CLI defaults to |
  223. | `args` | any other `check` flags, quoted as on a command line. `--format` is refused, since the action reads the report |
  224. | `upload-sarif` | send the report to code scanning. `true` |
  225. | `category` | the code scanning namespace. `mcpsnoop`. Vary it per leg of a matrix, or the legs overwrite each other |
  226. | `fail-on-findings` | fail the job on a finding. `true`. Set `false` to file the alerts and let code scanning's required check decide |
  227. | `version` | which mcpsnoop to install. Defaults to the release you pinned |
  228. | `install` | `false` when mcpsnoop is already on PATH, which is the way in on a platform no release is built for |
  229. Outputs are `outcome`, `sarif`, `exit-code` and `capture`, the path of the
  230. capture that was checked, which with `replay` is the one the replay wrote and
  231. worth keeping as an artifact. `outcome` is `passed`,
  232. `findings`, or `error`, and the third is worth handling separately. It means
  233. nothing was checked, which is not the same as nothing being found. **A run that
  234. could not check fails the job whatever `fail-on-findings` says**, because a
  235. pipeline that goes green having verified nothing is worse than one that fails.
  236. The job needs `security-events: write`, or the upload answers 403. Set
  237. `upload-sarif: false` in a repository without code scanning. Running the same
  238. check without the action, the signals it can fail on and the exit codes are in
  239. [docs/CI.md](docs/CI.md).
  240. ## Documentation
  241. | Page | What is in it |
  242. |---|---|
  243. | [Checking sessions in CI](docs/CI.md) | replaying a recording against every build, every signal `check` can fail on, exit codes, assertions, JUnit and SARIF reports, comparing two sessions, and wiring it up without the action |
  244. | [OpenTelemetry and Prometheus](docs/OPENTELEMETRY.md) | the spans and what they carry, streaming them to a collector, and live tool metrics |
  245. | [Using mcpsnoop](docs/USING.md) | keys, filtering, export formats, replay, what a server asked your user for, cost in context, stats across captures, what each client actually sends, the server inventory, remote machines and the config file |
  246. | [Redaction](docs/REDACTION.md) | scrubbing secrets, during capture or from a capture you already have |
  247. | [How it works](docs/HOW_IT_WORKS.md) | memory bounds, the history limit, and pruning old logs |
  248. | [Try it for real](docs/TRY_IT.md) | a published test server, driven by your own client |
  249. | [Review past sessions](docs/POST_MORTEM.md) | where session logs live and how to open one after the fact |
  250. | [The capture format](docs/CAPTURE_FORMAT.md) | what each line of a session log holds and what will never change about it, with a JSON Schema for tools that read captures |
  251. ## Security
  252. mcpsnoop runs the server command you wrap, so only wrap servers you trust, and
  253. run untrusted ones in a container. It never executes anything you didn't put in
  254. your client config.
  255. For remote workflows, use SSH tunnelling or SSH file transfer so transport auth,
  256. encryption, host verification, key rotation, and audit policy stay in your
  257. existing SSH setup.
  258. ### What a capture can do to your terminal
  259. A capture is data the other side chose. Frames and stderr lines can carry
  260. terminal escape sequences, and a terminal acts on whatever it is handed, which
  261. runs from a scrambled display through OSC 52 writing your system clipboard.
  262. mcpsnoop keeps only the colour sequences it generates itself and drops every
  263. other escape before a frame reaches your terminal. Table cells quote control
  264. characters so you can see they were there, the inspector spells them out in
  265. full, and the clipboard copy carries the escaped form, so nothing is hidden
  266. from you and nothing runs.
  267. ### What a capture holds
  268. Captured frames can include prompts, tool arguments, credentials, and tool
  269. results. [docs/REDACTION.md](docs/REDACTION.md) covers scrubbing them, while you
  270. capture or afterwards. To report a vulnerability, see [SECURITY.md](SECURITY.md).
  271. ## Contributing
  272. Issues and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for
  273. the details.
  274. ## License
  275. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.