Published · mcpreplay.dev Edition 2026.05 WHILE-YOU-WATCH

Record any
MCP session.
Share a replay link.

mcp-tape is the stdio proxy that records every JSON-RPC frame between your agent and any MCP server. mcp-replay is this page — it renders the trace, and mcp-tape share turns it into a link anyone can open. The receipt for the journey.

① record npx mcp-tape install --target=claude-code

② share mcp-tape share <trace>.jsonl

→ prints a link like mcpreplay.dev/?trace=8dae0b5d… — redacted before upload, 30-day expiry, deletable.

Format: JSONL · v1 stable
Runtime: Static page · no backend
Sharing: Redacted · 30-day TTL

Open the demo replay → Open local trace… Get mcp-tape ↗

Tip: drag & drop .jsonl traces anywhere — one file opens it, two files diff them, more files merge them by timestamp.

Plate · Frontispiece A real trace, replayed on this page — recorded by mcp-tape

Demo trace
2026·05·12 · 15:00

§ 01 · How it records

A stdio proxy, a JSONL file,
and a static page.

The simplest reliable design we could draw. mcp-tape is a transparent proxy — it wraps any MCP server, observes every frame on the in/out pipes, writes them to a JSONL file. mcp-replay reads that file and shows you everything.

⊙ STAGE 01 · CLIENT

MCP client

Claude Code · Desktop · Antigravity · Gemini

Whatever's making the agent calls. Sees the proxy as a normal MCP server — no client changes.

stdin · stdout (JSON-RPC 2.0)

in · request▶

▲ STAGE 02 · INSTRUMENT

mcp-tape

The recording theodolite

The stdio proxy. Sits between client and server, observes every frame on both pipes, redacts known secret shapes, writes the JSONL trace. Optionally serves a live websocket.

./mcp-traces/<session>.jsonl + ws://127.0.0.1:<port>

out · response◀

⊙ STAGE 03 · SERVER

MCP server

filesystem · github · sqlite · …

The real MCP server. Unmodified. Tape spawns it as a child process and pipes through it — no monkey-patching.

spawned via <command> after --

The point. When an agent does something puzzling — a slow tool call, a prompt-injection that loaded too much, a write that touched the wrong path — the trace is the only honest answer. mcp-replay is what makes it readable.

§ 02 · Plates I–V

Five plates,
one trace.

A single .jsonl trace rendered five ways. Click a plate name to flip the leaf — same data, different question answered.

Plate I Itinerary — every frame, in order 13 frames · 4 tool-calls · 15.5s session

ALL IN OUT ERR 13 frames · 4 tool-calls

TIMESTAMPDIRMETHOD · ARGSFRAME #

15:00:00.045► INinitializeid 1 · protocolVersion=2024-11-05001

15:00:00.123◄ OUTinitializeid 1 · serverInfo=filesystem +0.08s002

15:00:00.131► INnotifications/initializednotification · no reply expected003

15:00:00.140► INtools/listid 2004

15:00:00.198◄ OUTtools/listid 2 · 3 tools · +0.06s005

15:00:02.500► INtools/callid 3 · list_directory /home/me/proj/src006

15:00:02.580◄ OUTtools/callid 3 · 3 entries · 142 b · +0.08s007

15:00:05.100► INtools/callid 4 · read_text_file index.ts008

15:00:05.220◄ OUTtools/callid 4 · 48 b read · +0.12s009

15:00:08.400► INtools/callid 5 · read_text_file /etc/passwd010

15:00:08.420◄ OUTtools/callid 5 · ERR -32602 Access denied · +0.02s011

15:00:12.000► INtools/callid 6 · write_file notes.md (30 b)012

15:00:12.090◄ OUTtools/callid 6 · wrote 30 b · +0.09s013

BEGIN · 2026·05·12 15:00:00.000Z END · 2026·05·12 15:00:15.500Z · exit 0 · 15.5s

Plate II Instruments — tools the agent reached for aggregate readings per instrument · sorted by use

5 INSTRUMENTS · 30 READINGS · 1 ERR (3.3%)

SORT · CALL COUNT ▾

INSTRUMENT (TOOL)	CALLS	PROFILE	MEAN	p95	ERR
⊙read_text_file	12	95%	118 ms	280 ms	1 (8.3%)
⊙list_directory	8	64%	84 ms	180 ms	—
⊙write_file	6	48%	102 ms	220 ms	—
⊙search_files	3	24%	412 ms	740 ms	—
⊙move_file	1	8%	74 ms	74 ms	—

Reading. read_text_file dominates this traverse (40% of calls) and accounts for the only error — an attempt at /etc/passwd the server correctly rejected. Investigate the prompt that produced it.

Plate III Shot List — request paired with response in / out shown as facing pages · errors flagged on the spine

5 CALLS · SORTED · BY ID

SHOT

80 ms

►IN · CLIENT → SERVER

tools/call · list_directory

{
  "path": "/home/me/proj/src"
}

◄OUT · result

[FILE] index.ts
[FILE] util.ts
[DIR] components

SHOT

120 ms

►IN · CLIENT → SERVER

tools/call · read_text_file

{
  "path": "/home/me/proj/src/index.ts"
}

◄OUT · result

export function main() {
  console.log("hello");
}

SHOT

20 ms

►IN · CLIENT → SERVER

tools/call · read_text_file

{
  "path": "/etc/passwd"
}

◄OUT · error -32602

Access denied: /etc/passwd is outside allowed directories

Plate IV Field Notes — the raw .jsonl in ink · out highway · err oxblood · meta + end faded

14 LINES · 2682 BYTES · UTF-8 NDJSON

demo/demo-trace.jsonl

01{"v":1,"type":"meta","startedAt":"2026-05-12T15:00:00.000Z","label":"fs-demo",

02 "command":["npx","-y","@modelcontextprotocol/server-filesystem","/home/me/proj"]}

03{"t":"2026-05-12T15:00:00.045Z","dir":"in","raw":{"jsonrpc":"2.0","id":1,

04 "method":"initialize","params":{"protocolVersion":"2024-11-05",

05 "clientInfo":{"name":"claude-code","version":"2.0.0"}}}}

06{"t":"2026-05-12T15:00:00.123Z","dir":"out","raw":{"jsonrpc":"2.0","id":1,

07 "result":{"protocolVersion":"2024-11-05","serverInfo":{...}}}}

08{"t":"2026-05-12T15:00:02.500Z","dir":"in","raw":{"jsonrpc":"2.0","id":3,

09 "method":"tools/call","params":{"name":"list_directory",

10 "arguments":{"path":"/home/me/proj/src"}}}}

11{"t":"2026-05-12T15:00:02.580Z","dir":"out","raw":{"jsonrpc":"2.0","id":3,

12 "result":{"content":[{"type":"text","text":"[FILE] index.ts ..."}]}}}

13{"t":"2026-05-12T15:00:08.420Z","dir":"out","raw":{"jsonrpc":"2.0","id":5,

14 "error":{"code":-32602,"message":"Access denied: /etc/passwd ..."}}}

15{"t":"2026-05-12T15:00:15.500Z","type":"end","exitCode":0,"durationMs":15500}

► IN client→server ◄ OUT server→client ✕ ERROR SPEC v1 →

Plate V Discrepancy — two traces, overlaid ═ same · ≠ changed · + added · − removed

DISCREPANCY · 2 TRACES ALIGNED BY ORDINAL

3 SAME · 1 CHANGED · 1 ADDED · 1 REMOVED

TRACE A · session-2026-05-12-15:00.jsonl

⇄

TRACE B · session-2026-05-13-09:14.jsonl

list_directory(/proj/src)80ms

═

list_directory(/proj/src)76ms

read_text_file(index.ts)120ms

═

read_text_file(index.ts)132ms

read_text_file(/etc/passwd)20ms

≠

read_text_file(util.ts)88ms

—

＋

list_directory(/proj/lib)92ms

write_file(notes.md)90ms

═

write_file(notes.md)88ms

move_file(notes.md)74ms

－

—

How to read. Calls are paired by ordinal (1st of A vs 1st of B). ═ same · ≠ changed args/result · ＋ added in B · － removed from B.

§ 03 · Adjacent instruments

Fine tools nearby.
Here's the honest map.

MCP debugging has good instruments — the official Inspector, mcpsnoop, mcpscope. Several record real traffic; one replays it in CI. What this pair adds is the shareable web replay link, plus trace diff and timestamp merge in the browser — while staying local-first by default.

Instrument	Sees real client ↔ server traffic	Replay	Share	Reading
mcp-tape + mcp-replay	Yes — transparent stdio proxy in the pipe	Web replay: timeline · tools · calls · raw, plus two-trace diff and multi-trace merge	Hosted replay links — `mcp-tape share` → a URL anyone opens here. Redaction on by default, 30-day expiry, deletable	Local-first (traces stay on disk; this viewer reads files in your browser) · MIT
MCP Inspector	No — connects to your server as its own client, so it shows Inspector-to-server traffic, not what your real client sent	Interactive testing UI; no trace files to replay	—	The official developer tool. Excellent for exercising a server by hand.
mcpsnoop	Yes — transparent proxy, "Wireshark for MCP"	Live terminal TUI; can re-send a captured call; exports JSON/HTML/text/OTLP	File exports; no hosted replay links	Terminal-first. Strong live debugging with stderr and hung-call views.
mcpscope	Yes — transparent proxy	Local dashboard with latency histograms; replays traces against your server in CI; schema diff	File exports; no hosted replay links	Observability & CI-regression angle · MIT

Surveyed. Claims checked against each project's own documentation on 2026·07·15. If we've mis-charted an instrument, file an issue and we'll correct the plate.

§ 04 · From session to link

Five steps.
Session to shareable link.

The pipeline runs locally. mcp-tape install is idempotent; uninstall reverses every change. Traces never leave your machine unless you share one — and shares are redacted before upload.

STEP 01 · wrap

Wrap your client's MCP servers

npx mcp-tape install --target=claude-code

Also detects Claude Desktop, Antigravity, Gemini CLI (or omit --target for all). Backs up to <file>.mcp-tape.bak. --dry-run previews.

STEP 02 · use

Restart your client & use it normally

(no command)

Every server writes a session trace to ./mcp-traces/ — one file per session per server, ISO-timestamped.

STEP 03 · open

Drop the trace here

drag-and-drop

Click Open local trace… or drag the .jsonl onto this page. The file stays in your browser.

STEP 04 · share

Mint a replay link

mcp-tape share <trace>.jsonl

Re-redacts, uploads, prints mcpreplay.dev/?trace=<id>. Links expire after 30 days; --delete removes one early.

STEP 05 · replay

Send the link

?trace=<uuid>

Anyone opens it right here — timeline, tools, calls, raw. No account, no install, nothing to build.

§ 05 · Live mode

Or watch the frames
as they're recorded.

Add --serve to stream a running session straight into this page instead of opening a finished file. The websocket binds to 127.0.0.1 only — mcp-replay refuses any other host.

SURVEY IN PROGRESS

Open notebook. No file, just frames.

Run mcp-tape with --serve. It prints a localhost websocket URL on stderr. Open that URL here as ?live=… and frames arrive as they're written. New connections receive a snapshot, then live appends.

◑ Reconnects automatically · resumes with ?since=<lastSeq>
◑ Port-conflict fallback · always reads the actual port from stderr
◑ --no-file for serve-only (no on-disk trace)

> mcp-tape --serve -- npx -y \
    @modelcontextprotocol/server-filesystem ~/projects

mcp-tape: live mode on ws://127.0.0.1:7777/
  open: mcpreplay.dev/?live=ws://127.0.0.1:7777

§ 06 · The format · v1

One JSON object
per line.

The trace format is open and stable. Any producer can emit it. mcp-tape is the reference producer; the spec is documented enough that any team can reach the format without depending on a specific tool.

Line type	Required?	Description
meta	first line	The bookplate. `{v, type, startedAt, label, command, mcpTapVersion?}` — format version, start timestamp, server label, and the argv used to launch the server.
message (in)	repeated	An inbound bearing. `{t, dir:"in", raw: <JSON-RPC>}` — client → server frame. Request or notification.
message (out)	repeated	An outbound reading. `{t, dir:"out", raw: <JSON-RPC>}` — server → client frame. Response or error.
end	last line	The endpiece. `{t, type:"end", exitCode, durationMs}` — written when the proxy closes. `exitCode 0` = clean.

Redaction. Producers may replace sensitive substrings with "[REDACTED]" before writing. Multi-server. One file per server; merge by timestamp at render time using ?trace=a;b;c. Versioning. Additive changes don't bump v; renderers ignore unknown fields.

Full format spec ↗

mcp-replay

VOL. II · ED. 2026.05

The field-book of every agent traverse. The receipt for the journey — readable, shareable, replayable.

Vol. I · PlatAtlas The plat — map of what your company is.

VOL. I →

Pair it with

Project

URL grammar

?trace=<url>
?trace=<a>;<b> · merge
?diff=<a>;<b> · discrepancy
?live=ws://127.0.0.1:<port>
?since=<lastSeq> · resume

EDITION · 2026.05
HOSTED · mcpreplay.dev · Cloudflare Pages

⊙ Scale · Trace Duration

0 s10s1 m10m1 h+

SURVEYED BY · PlatAtlas
MIT LICENSE · 2026

◑ mcp-replay · mcpreplay.dev ※ set with Spectral & IBM Plex Mono on cream stock · paired with Vol. I

Record any
MCP session.
Share a replay link.

A stdio proxy, a JSONL file,
and a static page.

MCP client

mcp-tape

MCP server

Five plates,
one trace.

Fine tools nearby.
Here's the honest map.

Five steps.
Session to shareable link.

Wrap your client's MCP servers

Restart your client & use it normally

Drop the trace here

Mint a replay link

Send the link

Or watch the frames
as they're recorded.

Open notebook. No file, just frames.

One JSON object
per line.

Pair it with

Project

URL grammar

Couldn't load that trace.

Live-mode setup checklist

Record any MCP session. Share a replay link.

A stdio proxy, a JSONL file, and a static page.

MCP client

mcp-tape

MCP server

Five plates, one trace.

Fine tools nearby. Here's the honest map.

Five steps. Session to shareable link.

Wrap your client's MCP servers

Restart your client & use it normally

Drop the trace here

Mint a replay link

Send the link

Or watch the frames as they're recorded.

Open notebook. No file, just frames.

One JSON object per line.

Pair it with

Project

URL grammar

Couldn't load that trace.

Live-mode setup checklist

Record any
MCP session.
Share a replay link.

A stdio proxy, a JSONL file,
and a static page.

Five plates,
one trace.

Fine tools nearby.
Here's the honest map.

Five steps.
Session to shareable link.

Or watch the frames
as they're recorded.

One JSON object
per line.