ScreenshotNeo
Sign in Get a free key

BlogAI agents

How to Connect an AI Agent to a Live Cypress Test Session

Connect an AI agent to a live Cypress browser with Chrome DevTools MCP, or use Cypress’s cypress tap CLI to inspect local test failures and DOM context.

By the ScreenshotNeo team4 October 20267 min read

To let an AI agent inspect a live Cypress test, connect its browser tooling to the same Chrome remote debugging port that Cypress uses. Launch Cypress open mode with CYPRESS_REMOTE_DEBUGGING_PORT set to that port, then configure Chrome DevTools MCP to attach to the existing Chrome instance on the identical port. For Cypress-specific test results and DOM context, Cypress also provides cypress tap, which can work with a running open-mode session.

This guide covers both local workflows, their prerequisites, common setup failures, and how they differ from Cypress Cloud MCP, which reads recorded Cloud run data.

1. Connect Chrome DevTools MCP to Cypress’s live Chrome

The essential detail is that Cypress and the MCP browser tool must use one matching remote debugging port. If the MCP client starts a separate browser, that browser will not have the Cypress session’s page, runner, or application state.

  1. Choose a port. Cypress’s example uses 59210. Treat it as an example value, not a required port.
  2. Configure Chrome DevTools MCP. In your MCP client’s server configuration, set the Chrome DevTools MCP connection to attach to the existing Chrome instance at the chosen remote debugging port. The exact configuration fields depend on the client and MCP server version; follow their current setup instructions.
  3. Launch Cypress with the same port. From your project directory, run:
CYPRESS_REMOTE_DEBUGGING_PORT=59210 cypress open --e2e --browser=chrome
  1. In the Cypress app, select or open the spec you want to investigate. Keep this open-mode session running.
  2. Ask the connected agent to inspect the current browser page, Cypress runner, or application DOM around the failure. Give it the failing test name and the specific behavior to investigate.

On Windows shells, set the environment variable using that shell’s syntax before running cypress open. For example, in PowerShell: $env:CYPRESS_REMOTE_DEBUGGING_PORT = "59210"; cypress open --e2e --browser=chrome. Keep the port value identical in both configurations.

This approach gives a general browser-level tool access to the live browser state. Cypress’s source article illustrates investigating a failed to-do deletion test with the page state available at the time of failure; that is an example, not a guarantee that an agent will diagnose any given failure correctly. [Cypress’s port-matching walkthrough]

2. Use Cypress tap for Cypress-specific context

cypress tap is a Cypress CLI extension for interacting with an open-mode session. It can run a spec, report its status, and expose Cypress reporter, Command Log, error, and application-under-test DOM context. Its output can be requested as JSON for agent and script workflows. Cypress currently labels the feature beta, so command details and output may change. [Cypress tap documentation]

Prerequisites

  • Use a Cypress version that includes the CLI extension. The Cypress AI Skills guide says the cypress-tap skill requires Cypress 15.21.0 or later. [Cypress AI Skills prerequisites]
  • For live session inspection, start cypress open and select a test type and browser.
  • Interactive inspection generally requires a Chromium-family browser in that session: Chrome, Chromium, Edge, or Electron.
  • cypress tap does not attach to a headless cypress run session. Some commands, including status, specs, and run, can be used without an open browser, but live inspection needs the open-mode session.

Basic agent workflow

  1. In one terminal, start Cypress open mode from the project.
  2. In another terminal, ask the agent to use cypress tap to list specs or run the target spec, requesting JSON output if the agent needs structured results.
  3. Poll the run status until it finishes.
  4. If it fails, retrieve the reporter and Command Log context, the error, and the application DOM for the relevant command or test.
  5. Give the agent a focused task: explain the failure using the captured evidence, identify whether the assertion or app behavior is inconsistent, and suggest a minimal next change.

Use the installed CLI’s help output to confirm the exact syntax for your Cypress release, since this feature is beta. Cypress says the CLI ships with the Cypress App and does not require an extra installation or a Cypress Cloud account. [cypress tap command reference]

3. Choose the right Cypress workflow

Workflow Where the context lives Best fit Key requirement
Chrome DevTools MCP with matching port The local Chrome instance controlled by Cypress open mode General browser inspection of the runner, page, and app state Configure both sides to use the same remote debugging port
cypress tap Live local Cypress session and Cypress test context Running specs and retrieving reporter, Command Log, errors, and DOM evidence Open-mode session for live inspection; supported Chromium-family browser
Cypress Cloud MCP Recorded Cypress Cloud runs Inspecting run status, failures, and Test Replay information from Cloud Cypress Cloud run data and an MCP client configured for Cloud MCP

Cloud MCP is for recorded Cloud run context; it does not attach an agent to the local live browser. Cypress documents Cloud MCP as generally available since May 20, 2026, on every Cypress Cloud plan at no additional cost. Check the current documentation for availability and setup details. [Cypress Cloud MCP documentation]

Also distinguish agent debugging from AI-assisted test authoring. Cypress’s AI overview covers capabilities such as Studio and cy.prompt; those help create or work with tests, while the workflows above provide context to a coding agent. [Cypress AI overview]

4. Troubleshooting

Symptom Likely cause What to do
The agent opens a new browser with no test page The MCP client is launching a fresh browser instead of attaching to Cypress’s Chrome, or the port differs. Configure the MCP server to attach to the existing browser and use exactly the value passed through CYPRESS_REMOTE_DEBUGGING_PORT.
The agent cannot reach Chrome’s debugging endpoint Cypress did not launch Chrome with the expected port, the session has closed, or another process is using the port. Restart Cypress with the environment variable set, verify the MCP port setting, and choose another available port consistently on both sides if needed.
cypress tap cannot inspect the live page There is no open-mode session, or the session uses an unsupported browser for interactive inspection. Start cypress open and use Chrome, Chromium, Edge, or Electron.
The session is a headless CI run cypress tap live inspection is intended for open mode, not attachment to headless cypress run. Use a local open-mode session for live inspection, or use Cloud MCP for supported recorded Cypress Cloud run context.
Commands or JSON fields do not match examples cypress tap is beta and may change; the Cypress version or MCP client configuration may also differ. Check the documentation and local CLI help for the installed version, and check the MCP client’s current server configuration guide.
The agent sees the page but misses the failure evidence Browser-level access may show current DOM and browser state without the Cypress-specific reporter or command history the question needs. Use cypress tap to provide test and Command Log context, then ask the agent to inspect the relevant failure.

5. Reliability, performance, and cost considerations

  • Keep the session alive. A live browser connection only helps while the Cypress open-mode session and browser remain available. If either exits, reopen Cypress and reconnect.
  • Capture evidence close to the failure. DOM and app state can change as the test continues. Have the agent inspect the relevant command context promptly, or use Cypress’s captured reporter and Command Log details.
  • Limit ambiguity. Point the agent to one spec, one failing test, and a concrete symptom. This reduces irrelevant browser inspection and makes its reasoning easier to review.
  • Account for local resource use. Running Cypress, Chrome, an MCP server, and an AI client together consumes local CPU and memory. Close unrelated browser sessions and avoid repeatedly rerunning a long spec when a focused reproduction is enough.
  • Separate local and Cloud costs. Cypress documents cypress tap as free and not requiring Cloud. Cloud MCP is tied to Cloud run data; consult Cypress’s current plan documentation for account and run costs. Do not assume a local debugging workflow includes Cloud artifacts.

6. Or skip the browser setup

If you need a screenshot of a live website rather than Cypress’s interactive test history, ScreenshotNeo is a website screenshot API and MCP server. One GET request returns an image or PDF. For a screenshot of the Stripe homepage:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const bytes = new Uint8Array(await res.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', bytes));

See the ScreenshotNeo API documentation for the API and its options. Cookie banners, popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots.

Sign up free for 1,000 screenshots a month, with no card required.

7. Frequently asked questions

Can an agent inspect the Cypress runner as well as the application?

With Chrome DevTools MCP attached to Cypress’s Chrome, the agent can inspect the live browser context. Use cypress tap when you specifically need Cypress test reporter, Command Log, or DOM context.

Does this require Cypress Cloud?

No. The matching-port setup and local cypress tap workflow use a local open-mode session. Cloud MCP is a separate route for recorded Cloud runs.

Can I use a different port from 59210?

Yes. That number is an example. Choose an available port and configure Cypress and the MCP connection with the same value.

Can an agent run tests and inspect results without a browser?

Some cypress tap commands, such as status, specs, and run, can be used without an open browser; live session inspection requires an appropriate open-mode session.

Sources

Keep reading