Replay MCP

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. 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 MCP tools reference.

Get started

The fastest path is to install the Replay skills, connect your agent to the MCP server, and then ask the agent to record your app and investigate.

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

Terminal
claude mcp add replay\
 --transport http https://dispatch.replay.io/nut/mcp\
 --header "Authorization: YOUR_API_KEY"

Please help me debug issues on my application.
Use the replay-cli skill to record my application running on localhost:3000.
Then use Replay MCP to debug the recording.

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')

Connection modes

The universal endpoint above works with any recording. Every tool accepts a recordingId parameter, so one server connection lets the agent move between recordings.

There is also a per-recording endpoint at https://dispatch.replay.io/nut/recording/<recording-id>/mcp. Tools on this endpoint do not take a recordingId, because the recording is fixed by the URL. Use it when a script or CI job hands the agent a single recording and you want a smaller tool surface. The configuration is the same as above with the URL swapped.

Agent skills

Skills are Markdown instruction files your agent loads on demand. Replay publishes them at github.com/replayio/skills, and npx skills add https://github.com/replayio/skills --skill '<name>' installs one at a time.

The same files are served from this site at /.well-known/agent-skills/index.json for agents that discover skills automatically.

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.