Overview

AI Agents can use MCP to inspect a Replay recording. This provides a set of debugging tools that the agent uses to inspect every detail of what happened within a recording.

Traditionally, to debug your app, you need to first record it with the Replay CLI and then you can start debugging the recording using the Replay DevTools.

In agentic workflow, you can achieve this by using Skills to handle the recording, and then use the Replay MCP server to provide your A.I. agent with proper debugging metadata. Read more what Replay actually does to get achieve this.

We recommend to load the Replay MCP Skill into your agent to teach it how to use these tools.

You can also add Replay Skills to your project using the npx skills add command.

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

An MCP server able to inspect any recording is at https://dispatch.replay.io/nut/mcp. All tools take a recording ID parameter in addition to any other parameters.

In order to access recordings protected by an API key, use that API key as the value of the Authorization header.

Examples of launching Claude Code with the MCP servers for any recording:

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

With an API key:

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

When launched this way Claude Code will connect to the MCP server and use it to inspect any recordings whose ID it knows. For example:

use the replay MCP server you have access to and debug this test failure in recording <recording-id>:

Error: Timed out 15000ms waiting for
      expect(locator).toBeVisible()
        Locator: getByTestId('products-table-action-edit-00000000-0000-4000-8000-000000000007')
        Expected: visible
        Received: <element(s) not found>

MCP servers specific to particular recordings can be used as well. Tool calls on this server do not need to specify the recording ID, simplifying the interface, but the recording ID needs to be known ahead of time to compute the server URL.

The MCP server for a given recording can be accessed at https://dispatch.replay.io/nut/recording/<recording-id>/mcp. When recordings are protected by an API key, use that API key as the value of the Authorization header.

Examples of launching Claude Code with the MCP servers for specific recordings:

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": API_KEY
      }
    }
  }
}'

When launched this way Claude Code will connect to the MCP server and use it to debug the specific recording according to any instructions you give it. For example:

use the replay MCP server you have access to and debug this test failure:

Error: Timed out 15000ms waiting for
      expect(locator).toBeVisible()
        Locator: getByTestId('products-table-action-edit-00000000-0000-4000-8000-000000000007')
        Expected: visible
        Received: <element(s) not found>

Make sure recordings you examine either use development builds or have source maps available to make it easier for the agent to understand what the app's code is doing.