Driving Replay QA from a coding agent

Use the Replay QA REST API or MCP server to let a coding agent create projects, read bug reports, and confirm fixes without opening the web app.

Everything you can do in the Replay QA web app is also available to scripts and coding agents. There are two interfaces:

  • REST API at https://qa.replay.io/api/v1. Use it from scripts, CI jobs, or an agent that can run curl.
  • MCP server at https://qa.replay.io/api/mcp. Use it from Claude Code, Cursor, Codex, or any MCP client so the agent can call Replay QA directly as tools.

Both expose the same projects, bugs, journeys, test runs, and explorations. Pick whichever fits how your agent works. This page covers the workflow, authentication, and setup. Replay QA API and MCP tools lists the endpoints and tools, and the OpenAPI spec is the complete endpoint reference.

Which credential?

Replay QA uses its own API token, which starts with lqa_. It is not the same as the app.replay.io API key used by the replayio CLI and Replay MCP. See API keys and tokens for the difference.

The continuous QA loop

The intended workflow for a coding agent keeping an app bug-free:

  1. Create a project for the running app. Pass its URL and a short note on the flows that matter most. Optionally include a design document describing what the app should do.
  2. Let QA run. Poll the project status until explorations and test runs finish. Replay QA drives exploration and testing itself; the agent does not need to start its own explorations or test runs.
  3. Read the bugs. List open bugs and fetch each one. Every bug report includes reproduction steps, expected versus actual behavior, a screenshot chronology, and a root-cause analysis traced through the Replay recording down to the responsible code. The agent does not need to debug; it reads the root cause and writes the fix.
  4. Mark each fix. Setting a bug to fixed automatically reruns the affected journey to confirm the fix. Use wontfix to dismiss a bug or invalid if it is not a real bug.
  5. Loop. Go back to polling status and keep going until no open bugs remain.

If the bug report is not enough, the agent can open the linked recording with Replay MCP and inspect the failure directly.

Get an API token

  1. Sign in at qa.replay.io and open Account settings.
  2. In the API section, enter a token name and click Create token. Create one token per script or agent so each can be revoked on its own; creating a token leaves existing tokens active.
  3. Copy the token. It starts with lqa_ and is shown once.

Pass it as a bearer token on every request:

Authorization: Bearer lqa_your_token_here

Connect an MCP client

The server supports OAuth sign-in, so you can add it by URL without a token. Your client opens a browser sign-in the first time, and the connection then covers every project you have access to.

Terminal
claude mcp add --transport http replay-qa https://qa.replay.io/api/mcp

The Settings page in Replay QA shows the same commands with your site URL filled in.

The server exposes tools for projects, bugs, test runs, journeys, explorations, and account settings. The full list is in Replay QA API and MCP tools.

Example prompt:

Use the Replay QA MCP server to create a project for https://staging.example.com,

focused on signup and checkout. Wait for it to finish, then read every open bug,

fix each one in this repo, and mark it fixed.

Use the REST API

The base URL is https://qa.replay.io/api/v1. All endpoints take the bearer token above and return JSON.

The endpoints behind the loop:

StepRequest
Create a projectPOST /projects with target_url, instructions, optional design_document, budget
Poll statusGET /projects/{project_id}/status
List open bugsGET /projects/{project_id}/bugs?status=open
Read a bugGET /bugs/{bug_id}
Mark a fixPATCH /bugs/{bug_id} with {"status": "fixed"}
Terminal
curl -X POST https://qa.replay.io/api/v1/projects \

  -H "Authorization: Bearer $REPLAY_QA_TOKEN" \

  -H "Content-Type: application/json" \

  -d '{

    "target_url": "https://staging.example.com",

    "instructions": "Focus on signup, login, and checkout."

  }'

The response includes the project ID and a link to the project dashboard. budget caps how many credits the project may spend; it defaults to 20, which is a thorough pass.

The other resources, and the full set of bug statuses, are listed in Replay QA API and MCP tools.

Apps only reachable from your machine

If the app runs on localhost or a private network, create the project with use_reverse_proxy: true (or the create_project tool's equivalent). The project starts gated and does not run tests until a tunnel is connected. Then run the Replay QA CLI on a machine that can reach the app:

Terminal
npx --yes replayqa proxy --project <project_id>

The create response includes a reverse_proxy_setup_url you can poll for tunnel status. Testing a localhost app explains the proxy in detail, and Testing a pull request build in GitHub Actions covers builds that only exist inside a CI job.

Next
Overview