ReplayMCP

A proxy MCP server that records every MCP call your AI agent makes and lets you browse them in a clean web UI.

Think Loom, but for AI agent tool calls.

What it does

AI Agent (OpenCode / Claude / Cursor)
        ↓
    ReplayMCP  ← intercepts + records every MCP call
        ↓
Real MCP Server (Playwright, Atlassian, Cortex, Miro, etc.)

Every MCP call is recorded — tool calls, resource reads, and prompt gets:

• Call name / URI / prompt name
• Input (what the agent sent)
• Output (what came back)
• Duration, timestamp, errors

Browse everything at http://localhost:4242.

Quick start

Install globally (once, ever)

npm install -g replay-mcp

📦 View on npm →

Configure your AI agent

In ~/.config/opencode/opencode.json, add *-recorded entries:

{
  "mcp": {
    "atlassian-recorded": {
      "type": "local",
      "command": ["replay-mcp", "--target-url", "https://mcp.atlassian.com/v1/mcp"],
      "enabled": true
    },
    "playwright-recorded": {
      "type": "local",
      "command": ["replay-mcp", "--target", "/usr/local/bin/playwright-mcp"],
      "enabled": true
    }
  }
}

Works with any spec-compliant MCP server. Just replace the --target-url with your server's URL.

Use your agent normally

That's it. When your agent makes its first MCP call:

1. replay-mcp proxy spawns automatically
2. The UI dashboard auto-starts at http://localhost:4242 — no manual command needed
3. Every call is recorded and visible live in the UI

Replay any session

replay-mcp-replay --list                           # list all sessions
replay-mcp-replay --session session_abc123         # replay (re-uses original target)
replay-mcp-replay --session session_abc123 --smart # ignore timestamps/IDs in diff

Update

npm update -g replay-mcp

Development (from source)

git clone https://github.com/saurabhsinha/replay-mcp
cd replay-mcp
npm install

export REPLAY_TRACES_DIR=./traces  # optional — defaults to ~/.replay-mcp/traces/

npm run ui      # Start UI at http://localhost:4242
npm start -- --target-url https://mcp.example.com/mcp

Authentication (remote MCP servers)

ReplayMCP automatically reads tokens from OpenCode's auth store — the same file OpenCode uses after you authenticate.

Token file locations (checked in order):

• Linux / macOS: ~/.local/share/opencode/mcp-auth.json
• macOS fallback: ~/Library/Application Support/opencode/mcp-auth.json
• Windows: %APPDATA%\opencode\mcp-auth.json

What happens automatically:

1. Matches --target-url to the right entry in mcp-auth.json
2. If valid → uses it
3. If expired → auto-refreshes via OAuth refresh_token grant
4. If refresh fails → logs a message telling you which server to reconnect

Supported auth methods:

• Bearer tokens (OAuth 2.0 access tokens stored by OpenCode)
• Auto-refresh via OpenID Connect token endpoint discovery
• Manual override via --env-token or --header

Auth override flags

REPLAY_MCP_TOKEN=mytoken replay-mcp --target-url https://example.com/mcp --env-token
replay-mcp --target-url https://example.com/mcp --header "X-Api-Key: abc123"
replay-mcp --target-url https://public.mcp.example.com --no-auto-auth

How the UI works

The UI server (replay-mcp-ui) runs on port 4242 and watches ~/.replay-mcp/traces/ via fs.watch, pushing live updates over Server-Sent Events (SSE).

Securing the dashboard (optional)

REPLAY_UI_TOKEN=mysecret replay-mcp-ui
# → http://localhost:4242/?token=mysecret

Session detail — two-panel dashboard

Left panel:

• Stats bar — calls, errors, avg duration, session span, thinking time, output size + token estimate, est. cost (Claude Sonnet pricing)
• Toolbar — search bar, filter chips (All / Errors only / Slow / Blocked), Export + Delete + Copy replay cmd
• Waterfall timeline — horizontal bars per call; zoom slider for dense sessions
• Tool frequency chart — bar chart of most-called tools
• Trace list — sequence, OK/ERR badge, tool name, input summary, duration

Right panel (sticky):

• Syntax-highlighted JSON input + smart-rendered output
• 🚫 Block / ✅ Unblock per tool — blocks at the proxy level

Dashboard features:

• Search, clear all, per-session delete, export .jsonl, compare two sessions at /compare

Project structure

replay-mcp/
├── src/
│   ├── server.ts      # CLI entry point
│   ├── proxy.ts       # MCP proxy — records all calls
│   ├── recorder.ts    # Writes traces to .jsonl files
│   ├── replayer.ts    # Replay engine
│   ├── auth.ts        # Token resolution from OpenCode
│   └── ui/
│       └── server.ts  # Express web UI
├── src/cli/
│   └── replay.ts      # replay-mcp-replay CLI
└── docs/
    └── BACKLOG.md

Trace format

{"type":"session_start","id":"session_abc123","started_at":"2026-06-23T10:00:00Z","target":"https://mcp.example.com [streamable-http]"}
{"type":"trace","id":"trace_xyz","session_id":"session_abc123","tool":"getPage",
 "input":{...},"output":{...},"duration_ms":342,"timestamp":"...",
 "sequence":1,"thinking_ms":1200,"output_size_bytes":4096,"isError":false}

CLI reference

replay-mcp --target <cmd> [args...]     Wrap a local stdio MCP server
replay-mcp --target-url <url>           Wrap a remote HTTP/SSE MCP server

Options:
  --header "Key: Value"  Custom HTTP header (repeatable)
  --env-token            Use REPLAY_MCP_TOKEN env var as Bearer token
  --no-auto-auth         Disable automatic token resolution
  --no-auto-ui           Disable auto-starting the UI dashboard

replay-mcp-ui                           Start the web dashboard
  REPLAY_UI_PORT=4243 replay-mcp-ui     Custom port

replay-mcp-replay --list                List all sessions
replay-mcp-replay --session <id>        Replay a session
replay-mcp-replay --session <id> --target-url <url>  Override target
replay-mcp-replay --session <id> --timing   Respect original timing
replay-mcp-replay --session <id> --smart    Ignore timestamps/IDs

Environment variables:
  REPLAY_TRACES_DIR      Override traces location (~/.replay-mcp/traces/)
  REPLAY_UI_PORT         Override UI port (4242)
  REPLAY_UI_TOKEN        Token to gate the dashboard (optional)
  REPLAY_MCP_TOKEN       Bearer token for --env-token flag