Session replay over MCP: let your agent read real user sessions

Your coding agent can read your codebase, your git history, and your test output. It cannot see the one thing that would tell it whether any of that is working: what actually happened when a real person used the software.

That gap is the reason “the user says checkout is broken” still turns into an afternoon of guesswork. The agent has the code. It does not have the session.

Model Context Protocol closes that gap. This post covers what a session replay MCP server exposes, how to connect one, and where the approach genuinely does not help.

What MCP is, briefly

Model Context Protocol is an open standard for connecting AI clients to external tools and data. A client — Claude Code, Claude Desktop, Cursor, or something you wrote — connects to an MCP server, discovers the tools it exposes, and calls them during a conversation.

The important property is that it is a protocol, not an integration. You do not write glue code for each agent. The server describes its own tools, and any compliant client can use them.

For session replay this matters because the alternative is bad. Without MCP, getting session data into an agent means exporting something, pasting it into a prompt, and hoping the format survives. With MCP, the agent queries sessions the way it queries a database.

The problem with replay as video

Session replay has existed for over a decade. The format has always been video: a pixel-accurate reconstruction of the user’s screen, scrubbed by a human.

Video is the right format for a human. It is a terrible format for a model. Sessions run to hundreds of kilobytes of serialized DOM events. Nothing in that stream is meaningful to a language model without being rendered first, and rendering it produces pixels, which is worse.

So the useful thing is not “give the model the recording.” It is: derive a text transcript of what happened, and let the model read that instead.

A UserTapes transcript looks like this:

# Tape 3e7128f8
- URL: https://example.com/checkout
- Duration: 1:02

## Transcript
- 0:00 session start · https://example.com/ · viewport 1440×900
- 0:04 click button "Apply coupon"
- ⚠ 0:18 dead click button "Pay now" — nothing on the page responded
- ⚠ 0:19 rage click ×4 · button "Pay now"
- ⚠ 0:21 POST https://example.com/api/pay · 502
- ⚠ 0:30 typed into a form but left without submitting (heuristic)
- 1:02 session end · total 1:02

That is a few kilobytes instead of a few hundred. Lines prefixed ⚠ are the ones worth attention. Timestamps are offsets from session start and map exactly to the human player’s timeline, so the model can cite a moment and you can go watch it.

The recording and the transcript are derived from the same stored events, which means they cannot disagree. The transcript is not a summary written after the fact — it is the same data in a different projection.

What a session replay MCP server exposes

UserTapes exposes eight tools:

Tool	What it does
list_sites	The account’s sites
list_tapes	Sessions for a site, newest first, with filters
read_transcript	One session as markdown
get_stats	Aggregate counts over N days
site_digest	One-call briefing of the last N days
list_alerts / create_alert / delete_alert	Saved watches over sessions

list_tapes is the one that does the work. It filters on has_errors, has_rage_clicks, url_contains, min_duration_seconds, and date range, and each result carries a one-line derived summary — often enough for the agent to pick the right session without reading a full transcript at all.

That detail matters more than it sounds. The naive version of this integration burns an enormous amount of context reading transcripts to find the interesting one. Returning a summary per tape means the agent reads one transcript, not forty.

Connecting it

The server is one HTTP endpoint speaking stateless JSON-RPC 2.0 over Streamable HTTP (protocol revision 2025-06-18). Authentication is a bearer token.

{
  "mcpServers": {
    "usertapes": {
      "url": "https://usertapes.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_MCP_TOKEN" }
    }
  }
}

The token is a per-account read credential from the Agent access page. It is deliberately distinct from a site’s tracking token, which is ingest-only and sits in public page source. A leaked tracking token lets someone send you junk recordings; it does not let them read anything.

The only write surface on the MCP token is alerts. An agent can set a standing watch — “tell me when a session hits an error on /checkout” — and cannot delete a recording, change a site, or touch billing.

What this actually looks like in use

The workflow that justifies the whole thing:

$ claude "users say coupons are broken — find it and fix it"

▸ usertapes list_tapes(has_errors: true)
  ← 14 tapes · rage clicks on "Apply coupon"
▸ usertapes read_transcript(3e7128f8)
  ← 0:19 click button "Apply coupon"
    0:20 ⚠ POST /api/coupon · 422
    0:23 ⚠ rage click ×4 · same button
▸ diagnosis: checkout.js swallows 422s — no error shown, button stays live
▸ editing checkout.js +14 −3

The agent went from a vague complaint to a specific line of code without a human watching a single video. That is the point. Not “AI summarizes your analytics” — the agent doing the watching, then fixing what it found, because it already has the repository open.

Where this does not help

Some honesty, because the failure modes are predictable:

It is not a replacement for error monitoring. If you want a stack trace and a release-tagged regression, use Sentry. UserTapes keeps error messages but deliberately drops stack traces, because stacks routinely contain URLs with tokens in them. Replay tells you what the user was doing when it broke. Error monitoring tells you where in the code it broke. Those are different questions and you want both.

It is not product analytics. If your question is “what is the conversion rate of this funnel across 40,000 users”, you want an analytics tool with a proper query engine. Session replay answers questions about individual sessions, and aggregates only shallowly.

It cannot see what it did not record. Inputs are masked at the source, so if your bug depends on the exact string a user typed, the transcript will tell you a field was filled and nothing more. That is a deliberate trade and it is occasionally the wrong one for debugging.

Transcripts are untrusted input. Click labels, error messages, and URLs in a transcript come from end-user browsers. A hostile visitor can put text in a button label. Treat transcript content as data, never as instructions to the agent — this applies to any tool that feeds user-generated content to a model, and it is worth being deliberate about.

Getting started

UserTapes gives every plan unlimited MCP access, including the free tier — 100 sessions, no card, no expiry. Reads cost storage lookups, not inference, so there is no reason to meter them.

Setup is one script tag on your site and one entry in your agent’s MCP config.

If you are weighing whether replay is the right tool at all, the more general case is in session replay for developers. If you are here because you are staring at a bug report you cannot reproduce, start with how to reproduce a bug a user reported.