Overview

Replay MCP gives AI agents a set of time-travel debugging tools to inspect Replay recordings. Agents can examine console output, read source code, inspect variables, analyze React components, profile performance, and much more — all through the MCP protocol.

What can agents do?

Replay MCP provides tools across several areas that give agents deep visibility into your application's runtime behavior:

• Source code & console — browse and search source files, read code with execution annotations, view console output, and see screenshots of visual state at any moment
• Code inspection — inspect variables, evaluate expressions, and examine call stacks at any point during execution. Set virtual breakpoints to observe how values change across multiple executions.
• Error detection — find uncaught exceptions and React-specific crashes that caused components to unmount
• Network & storage — inspect HTTP requests and responses, view localStorage operations
• React analysis — examine the component tree, analyze render behavior across the entire recording, trace what triggered specific re-renders, and identify wasted renders. This is one of Replay MCP's most powerful capabilities — agents can drill from a high-level render summary all the way down to why a specific component fiber re-rendered.
• Test analysis — inspect Playwright test steps, find where tests failed, and see the protocol commands executed during each step
• Performance profiling — profile JavaScript statement execution, analyze React render and effect costs, and find slow functions

For details on every available tool, see the Tools Reference.

Getting started

To use Replay MCP, you need two things:

1. Skills (recommended) — teach your agent how to use the tools effectively
2. MCP server connection — connect your agent to Replay's MCP endpoint

Skills

Replay Skills are instruction files that teach your agent how to use Replay tools effectively. The replay-mcp skill helps agents understand which tools to call and in what order when investigating a recording.

Add all Replay skills to your project:

Terminal
npx skills add https://github.com/replayio/skills --skill '*'

Or add just the MCP skill:

Terminal
npx skills add https://github.com/replayio/skills --skill 'replay-mcp'

MCP Server Connection

Replay provides two connection modes depending on whether you want your agent to work with any recording or a specific one.

Universal (any recording)

Connect to https://dispatch.replay.io/nut/mcp. All tools accept a recordingId parameter so the agent can inspect any recording it knows about.

• Claude Code
• Cursor / VS Code
• Config file

Terminal
claude --mcp-config '{"mcpServers":{"replay":{"type":"http","url":"https://dispatch.replay.io/nut/mcp"}}}'

With an API key for team recordings:

Terminal
claude --mcp-config '{
  "mcpServers": {
    "replay": {
      "type": "http",
      "url": "https://dispatch.replay.io/nut/mcp",
      "headers": {
        "Authorization": "YOUR_API_KEY"
      }
    }
  }
}'

Example prompt:

Use the Replay MCP server to debug this test failure in recording abc123:

Error: Timed out 15000ms waiting for
  expect(locator).toBeVisible()
    Locator: getByTestId('submit-button')

Per Recording

Connect to https://dispatch.replay.io/nut/recording/<recording-id>/mcp. Tools don't need a recordingId parameter since the recording is already specified in the URL. Simpler interface, but you need to know the recording ID upfront.

• Claude Code
• Cursor / VS Code
• Config file

Terminal
claude --mcp-config '{"mcpServers":{"replay":{"type":"http","url":"https://dispatch.replay.io/nut/recording/RECORDING_ID/mcp"}}}'

With an API key:

Terminal
claude --mcp-config '{
  "mcpServers": {
    "replay": {
      "type": "http",
      "url": "https://dispatch.replay.io/nut/recording/RECORDING_ID/mcp",
      "headers": {
        "Authorization": "YOUR_API_KEY"
      }
    }
  }
}'

Example prompt:

Use the Replay MCP server to debug this test failure:

Error: Timed out 15000ms waiting for
  expect(locator).toBeVisible()
    Locator: getByTestId('submit-button')

Tips

Use development builds or source maps

Recordings of minified production code are much harder for agents (and humans) to understand. Use development builds when recording, or ensure source maps are available. This lets agents read meaningful variable names, function names, and original source code.

Understand execution points

Many MCP tools work with execution points — opaque identifiers that represent a specific moment during the recording's execution. Some tools produce execution points (e.g., searching source code, viewing console messages, setting virtual breakpoints), and other tools consume them (e.g., inspecting variables, evaluating expressions, getting call stacks). Think of them as bookmarks to specific moments in time that agents pass between tools.

Some tools are recording-type specific

React analysis tools only work when the recording contains a React application, and test analysis tools only work with Playwright test recordings. The agent will get an error if it tries to use these on an incompatible recording — but it will recover and try other approaches.

Start broad, then drill down

A good investigation pattern is to start with broad tools — console output, exception detection, network requests — to get an overview, then use targeted tools like virtual breakpoints and expression evaluation to dig into specific issues. For React apps, the render analysis tools support progressive drill-down from a high-level summary all the way to individual fiber render causes.