A flight recorder
for MCP servers.
When an agent does something odd with your MCP server, you usually can't see what it sent, what came back, or how long it took. Put mcp-blackbox in front of any stdio server to watch every call in a live viewer, keep logs with secrets hidden, and replay real sessions as regression tests in CI. It works with any client and any server, in any language, with no code changes.
Live: the official filesystem server, recorded
Shared session · everyone's calls appearThis is the real viewer that ships in the package (--ui). Click any call to see the exact request and response, with timings. Filter with the search box.
Replay real sessions in CI
Record a session once, then run it against every new build. mcp-blackbox re-sends exactly what the client sent and compares every answer. JSON inside text results is compared field by field, so the diff points at the exact value that changed.
# 1. use your server through the recorder npx @tirthlabs/mcp-blackbox --out tests/search.jsonl \ -- node dist/server.js # 2. in CI, against the new build npx @tirthlabs/mcp-blackbox replay tests/search.jsonl \ --ignore timestamp,requestId -- node dist/server.js
✔ initialize 2289ms (was 25451ms) ✔ tools/list 28ms (was 36ms) ✖ tools/call read_text_file 13ms (was 11ms) result.content[0].text: "hello from blackbox\n" → "changed\n" ✔ tools/call list_directory 4ms (was 4ms) ✔ tools/call read_text_file 3ms (was 4ms) 4 passed, 1 failed # exit code 1
What it does
Drop-in
Put npx -y @tirthlabs/mcp-blackbox --ui -- in front of the command in your Claude Desktop, Cursor or Claude Code config. Bytes pass through unchanged.
Live viewer
Requests paired with responses, errors highlighted, p50 and p95 latency, filter by method, tool or text. Server stderr is included for startup problems.
Secrets stay out
Passwords, tokens, API keys, JWTs, Bearer headers and private keys are hidden in recordings. The client and server still see the real values.
Stats per tool
mcp-blackbox stats latest prints calls, errors and p50/p95/max per tool, ready for a quick check or --json for dashboards.
Regression tests for free
Real sessions become tests. Server-to-client requests (roots, sampling) are answered from the recording, so replays run unattended.
Plain JSON Lines
Sessions are one message per line, easy to grep, diff, ship to a log store or share in a bug report.