How to Set Up Replay MCP with Codex in Under 10 Minutes

Codex runs in your terminal, works autonomously across your codebase, and hands you a diff when it's done. That workflow breaks down when the bug is a race condition, a hydration mismatch, or a flaky test - the kind of thing that doesn't leave enough in a stack trace to act on. Replay gives Codex the missing layer: a full browser recording it can query for DOM state, variable values, network timing, and React component trees at any point during execution.

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

Before You Start

You'll need Node.js, Codex installed and running in your terminal, and a free Replay account. Codex CLI is the assumed setup here - the config file approach also works in the IDE extension, but the TUI commands referenced below are CLI-specific. 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. Skills will be installed, by default, in a location that Codex will use for skills.

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

This adds prompt context that helps Codex 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

Codex stores MCP configuration in ~/.codex/config.toml. You can also scope it to a single project by placing a config.toml in .codex/ at your project root (trusted projects only). Add the following:

[mcp_servers.replay]

url = "<https://dispatch.replay.io/nut/mcp>"

[mcp_servers.replay.http_headers]

Authorization = "YOUR_API_KEY"

Your API key is under Settings > API Keys in the Replay dashboard.

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

If Replay doesn't appear as an active server after restarting Codex, run /mcp in the Codex TUI to check which servers are registered. If it's missing, confirm you edited the right config file - project-scoped config only applies in trusted projects.

💡 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

Start a Codex session in your project directory, then give it the recording ID and the error:

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

At this point Codex 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, Codex 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.