How to Set Up Replay MCP with Claude Code in Under 10 Minutes

Claude Code is a conversational coding agent - you describe the problem, it investigates, asks follow-up questions, and proposes fixes. That loop works well until the bug is something a stack trace can't explain: a race condition, a hydration mismatch, a test that fails one in ten runs. Replay gives Claude Code the runtime context it needs to break out of that loop - every DOM state, variable value, and network request from the moment of failure, queryable without reproducing the bug.

This guide gets you from zero to a working MCP session in one sitting. If you're using Codex instead, there's a separate guide for that.

Before You Start

You'll need Node.js, Claude Code installed and working, and a free Replay account. If you have a project with a known bug handy, great. If not, Replay provides a demo recording (Overboard) you can use to get through the whole setup without recording anything yourself.

Install the Replay CLI

Open your terminal and install the Replay CLI:

npm install -g replayio

replayio login

This opens a browser auth flow. Once you're through it, you're authenticated for both recording and upload.

Get a Recording

If you want to record your own bug:

replayio record

This opens the Replay Browser. Reproduce the bug, then close the browser. You'll be prompted to upload the recording - say yes, and it shows up in your dashboard at app.replay.io.

If the upload fails, check that port 443 is open outbound. If you're behind a corporate proxy, set REPLAY_UPLOAD_ENDPOINT to route through it.

If you'd rather skip this for now and use the Overboard demo recording, log into the dashboard and open it from your library. Either way, you need the recording ID - it's in the URL: app.replay.io/recording/<recording-id>. Copy the full UUID (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx), not a shortened share link.

Install Replay Skills

Run the following command to install the Replay MCP agent skills. When prompted for which agents to install the skills for, make sure to include Claude Code.

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

This adds prompt context that helps Claude Code use Replay's MCP tools correctly. Without it the agent will still connect, but it'll take longer to reach for the right tools.

Add Replay to Your MCP Config

Pass the config inline when launching Claude Code:

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

This connects to Replay's universal endpoint. Every tool accepts a recordingId parameter, so you can point the agent at any recording mid-conversation without changing the config.

Your API key is under Settings > API Keys in the Replay dashboard. If you prefer a config file over the inline flag, add the same JSON to ~/.claude/mcp_config.json or .claude/mcp_config.json in your project root.

If Replay doesn't appear in Claude Code's available tools after restarting, run claude mcp list to confirm the server is registered. If it's missing, check which config file Claude Code is actually reading - the path depends on whether you're in a project-scoped or global config.

💡 Note: Replay also has a per-recording mode that bakes a specific recording ID into the connection URL, which simplifies prompts slightly. This guide focuses on universal mode since it works for any recording without reconfiguration. See the MCP overview for details.

If you want to get a taste of what debugging with replay’s MCP feels like, check out these two posts:

Run Your First Investigation

Restart Claude Code so it picks up the new config, then start a session:

Use the Replay MCP server to debug this test failure in recording : Error: Timed out 15000ms waiting for expect(locator).toBeVisible() Locator: getByTestId('submit-button')

At this point Claude Code has access to the exact DOM state at any frame, the React component tree and props, network request timing, console output, and the full event sequence leading to the failure. It can also set retroactive breakpoints on lines that had no logging when the failure happened.

If you're getting "check your state management"-style answers rather than a specific root cause, the skills install is probably what's missing. Without that prompt context, the agent can connect to Replay but won't know to reach for tools like getConsoleMessages, getReactComponents, or getNetworkRequests.

What to Try Next

Once the first session is working, the Playwright integration is worth setting up: add @replayio/playwright to your test config and any CI failure will automatically produce a recording and post an agent diagnosis as a GitHub PR comment, without anyone opening DevTools.

If your app uses Redux or TanStack Query, Replay has dedicated MCP tools for action history and cache state that go well beyond what the generic runtime analysis provides.

And if you're debugging a specific recording, switch the agent to per-recording mode to scope the session to that one file. Universal mode is better for open-ended investigation across your full recording library.