How to Connect an AI Assistant to Cypress Test Runs with MCP

Cypress Cloud MCP connects a compatible AI coding assistant to test runs recorded in Cypress Cloud. To set it up, an organization administrator enables the integration, each user authenticates with Cypress Cloud (OAuth is recommended), and the user adds Cypress’s remote MCP server to their AI client: https://mcp.cypress.io/mcp. Follow your client’s own setup instructions because configuration formats and authentication support vary. Cypress Cloud MCP documentation

This connection gives an assistant access to recorded Cloud run data for investigation. It does not connect the assistant to a live local Cypress browser session. For local-session agent workflows, Cypress documents cypress tap and a Chrome DevTools MCP approach. Cypress tap documentation · Cypress live-session guide

What you need before setup

• A Cypress Cloud organization with the project and recorded runs you want to inspect.
• An organization administrator who can enable Cloud MCP in the organization’s Integrations page.
• An AI client that supports remote MCP connections over HTTP. The server URL is https://mcp.cypress.io/mcp.
• A Cypress Cloud user account with permission to see the relevant projects and run data.

Cypress says Cloud MCP is included on all Cypress Cloud plans, including Starter, at no additional cost, and no minimum Cypress App version is required. The service reached general availability on May 20, 2026. These are current product details; check the documentation for changes before relying on them. Cypress general availability announcement

Connect Cypress Cloud MCP in three steps

1. Enable the organization integration. An administrator opens the organization’s Integrations page in Cypress Cloud and enables Cloud MCP. Users cannot connect successfully until the organization has enabled it.
2. Choose an authentication method. Use OAuth when the client supports browser-based authorization. Use a personal access token (PAT) when the client needs a bearer token.
3. Add the remote server to the AI client. Configure the exact endpoint https://mcp.cypress.io/mcp, then complete OAuth or supply the PAT using the client’s secure secret mechanism. Reconnect or restart as the client requires and confirm that Cypress tools appear.

OAuth: recommended

OAuth avoids manually creating and rotating a token. Add the remote server URL to a client that supports MCP OAuth; when it connects, the client should open Cypress Cloud sign-in in a browser. Sign in as the Cypress Cloud user who should make queries. Cypress documents OAuth sessions as user-scoped, permission-aware, and automatically reconnecting for 30 days. Active sessions can be reviewed or revoked from the Cypress Cloud profile page. Authentication details from Cypress

PAT: for clients that need a bearer token

1. Sign in to Cypress Cloud, open your profile, and go to the MCP personal access token section.
2. Generate a token, select its expiration, and copy it immediately. Cypress displays the token only once.
3. Pass it as Authorization: Bearer YOUR_MCP_TOKEN using a secret or environment variable supported by your client.

A PAT follows the user’s Cypress Cloud role and permissions. Treat it as a credential: do not commit it to a repository, paste it into prompts, or share a config file containing the literal token. If you suspect exposure, revoke or replace it from your profile.

Client configuration examples

These examples use Cypress’s documented formats. Choose the one for your client; the config schema is not universal across MCP clients. OAuth is shown first where supported. For other clients, look for their instructions for remote HTTP MCP servers and use the Cypress endpoint and authentication behavior above.

Cursor

In Cursor Settings, open Tools & MCPs and add a server. The user configuration file is ~/.cursor/mcp.json.

{
  "mcpServers": {
    "cypress": {
      "url": "https://mcp.cypress.io/mcp"
    }
  }
}

Save the file and restart Cursor if needed. On first use, complete the Cypress Cloud browser sign-in. For a PAT-capable setup, use the documented headers form and store the token as a secret rather than checking it into a shared config:

{
  "mcpServers": {
    "cypress": {
      "url": "https://mcp.cypress.io/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}

GitHub Copilot in VS Code

Add a server to .vscode/mcp.json. This OAuth configuration uses VS Code’s servers schema:

{
  "servers": {
    "cypress": {
      "type": "http",
      "url": "https://mcp.cypress.io/mcp"
    }
  }
}

VS Code handles browser-based authentication when the server is first used. For PAT authentication, use a password prompt input so the token is not written directly into the JSON file:

{
  "servers": {
    "cypress": {
      "type": "http",
      "url": "https://mcp.cypress.io/mcp",
      "headers": {
        "Authorization": "Bearer ${input:CYPRESS_MCP_TOKEN}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "CYPRESS_MCP_TOKEN",
      "description": "Enter your Cypress MCP personal access token",
      "password": true
    }
  ]
}

GitHub Copilot CLI

Use the global config at ~/.copilot/mcp-config.json or a project config at .copilot/mcp-config.json. Copilot CLI uses a PAT in this documented configuration:

{
  "mcpServers": {
    "Cypress Cloud": {
      "type": "http",
      "url": "https://mcp.cypress.io/mcp",
      "headers": {
        "Authorization": "Bearer ${CYPRESS_MCP_TOKEN}"
      }
    }
  }
}

Set the environment variable before starting the CLI:

# macOS or Linux
export CYPRESS_MCP_TOKEN=YOUR_MCP_TOKEN

# Windows PowerShell
$env:CYPRESS_MCP_TOKEN="YOUR_MCP_TOKEN"

Run /mcp show inside Copilot CLI to verify the server is loaded and the variable resolved.

OpenAI Codex CLI

Codex CLI and its IDE extension share MCP settings in ~/.codex/config.toml. Add the server, then start OAuth login:

codex mcp add cypress-cloud --url https://mcp.cypress.io/mcp
codex mcp login cypress-cloud

Complete sign-in in the browser, start a new Codex session, and run /mcp to confirm the connection. The equivalent manual OAuth config is:

[mcp_servers.cypress-cloud]
url = "https://mcp.cypress.io/mcp"

For a PAT, configure an environment variable reference rather than embedding the token:

[mcp_servers.cypress-cloud]
url = "https://mcp.cypress.io/mcp"
bearer_token_env_var = "CYPRESS_MCP_TOKEN"

# macOS or Linux
export CYPRESS_MCP_TOKEN=YOUR_MCP_TOKEN

# Windows PowerShell
$env:CYPRESS_MCP_TOKEN="YOUR_MCP_TOKEN"

Claude Code

Claude Code supports the remote HTTP transport in its documented CLI setup. For OAuth:

claude mcp add cypress-cloud \
  https://mcp.cypress.io/mcp \
  --transport http

Start a Claude Code session and prompt it to use Cypress MCP; it should open the browser sign-in flow. To use a PAT instead:

claude mcp add cypress-cloud \
  https://mcp.cypress.io/mcp \
  --transport http \
  --header "Authorization: Bearer YOUR_MCP_TOKEN"

Claude Code supports user, local, and project scopes for server configuration. The default is local to the current project; choose the scope that matches whether this connection should be personal, project-specific, or shared. Avoid putting a live PAT into a project-shared config.

Claude Desktop

For OAuth, use Claude Desktop’s Connectors interface to add a custom connector with the remote URL https://mcp.cypress.io/mcp, then connect and authenticate in the browser. The PAT alternative documented by Cypress uses mcp-remote in claude_desktop_config.json:

{
  "mcpServers": {
    "Cypress Cloud": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://mcp.cypress.io/mcp",
        "--header",
        "Authorization: Bearer ${CYPRESS_MCP_TOKEN}"
      ],
      "env": {
        "CYPRESS_MCP_TOKEN": "YOUR_MCP_TOKEN"
      }
    }
  }
}

Restart Claude Desktop after saving. Cypress’s instructions note that mcp-remote requires Node.js v22 or later available on the path. Because this example uses a local process to bridge to the remote server, check both the Node installation and the client’s MCP tools indicator if it does not connect.

What the assistant can query

Once connected, the assistant chooses Cypress tools based on the request. Available data includes project discovery; run summaries; per-spec and per-test results; failure attempts with errors and stack traces; flaky-test details; and Test Replay links. Cypress also documents tools for accessibility reports and UI Coverage. Those data sources depend on the organization having the corresponding plan or product subscription. The available run data is also constrained by the organization’s Cypress Cloud data retention and recording limits. Tool list and plan dependencies

Question	Useful context to include
What failed in CI?	Say “Cypress Cloud,” name the branch or paste a run URL, and ask for failures with a concise summary.
Is this failure flaky?	Specify the run or recent run window and ask for per-attempt patterns.
Which tests are slow?	Give the run URL and ask for spec durations, then test-level detail for the slowest spec.
What accessibility issues are present?	Ask for the Cypress Accessibility report, and scope by run or branch and severity if useful.
What is untested?	Ask for UI Coverage for a run, then request the riskiest view or its untested elements.

Example prompt: In Cypress Cloud, summarize failures from the latest run on main. Include the failing test names, the key error from each stack trace, and a Test Replay link where available. An assistant can use returned evidence to explain or propose a fix; the MCP connection itself does not establish that a code change has been made or validated.

Confirm the connection and access

1. Reconnect or restart the client according to its setup flow.
2. Use that client’s own MCP status view or command. For example, Cypress documents /mcp for Copilot CLI and a new-session check for Codex; these checks are client-specific.
3. Ask a narrow query such as “List my Cypress Cloud projects” or “Show the latest Cypress Cloud run for this branch.”
4. If no expected project or run appears, check the authenticated user’s organization membership and permissions as well as the server connection.

Security, privacy, limits, and cost

• Read-only access: Cypress describes Cloud MCP as read-only. It retrieves Cloud data; it cannot edit test code or delete runs.
• User-scoped access: the authenticated user can query only projects and run data that user can already access.
• Conversation privacy: Cypress says it receives inputs to MCP tool calls, not the assistant’s full chat history or context, and says returned data is not used to train or improve an LLM. Review Cypress’s current documentation and your organization’s data policies for details.
• Rate limit: Cypress documentation currently lists 100 tool requests per hour for all plans. A broad prompt may require multiple tool calls; make requests specific and ask for deeper detail only where needed.
• Data availability: the assistant can only inspect runs that were recorded and remain available under the organization’s plan and retention settings.
• Price: Cypress states Cloud MCP is included on all Cypress Cloud plans at no additional charge.

For team use, prefer OAuth where supported, use individual accounts, and avoid distributing a shared PAT. If using a PAT, set an expiration and keep it out of source control, logs, and copied prompts. Cypress security and limit details

Troubleshooting

Symptom	Likely cause	Fix
The client cannot connect to the server.	The organization has not enabled Cloud MCP, the URL is wrong, or a firewall/proxy blocks the endpoint.	Ask an organization admin to enable the integration, use exactly https://mcp.cypress.io/mcp, and allowlist mcp.cypress.io in the relevant network policy.
OAuth does not open or finish.	The browser cannot reach Cypress Cloud, the client has stale server state, or the user signed into the wrong account.	Confirm access to https://cloud.cypress.io, remove and re-add the server if necessary, then complete sign-in with the account that has project access.
Authentication fails with a PAT.	The token may have expired, been copied incorrectly, or the Authorization header is malformed.	Check the token in Manage Profile, generate a replacement if expired, and ensure the header is exactly Authorization: Bearer TOKEN. Keep the token value out of committed files.
The client shows no Cypress tools.	The client may not support remote HTTP MCP, configuration may use the wrong schema, or it has not reloaded the config.	Use the client-specific format from its documentation, confirm the endpoint, then reconnect or restart. Do not copy a servers schema into a client expecting mcpServers.
The assistant cannot find a run.	The branch name may differ from the CI branch, the integration may be disabled, the run may not have been recorded, or the user lacks project access.	Check organization enablement and permissions. Query by exact branch, commit, run number, or Run URL. A failed CI job can still have a recorded Cypress run.
The assistant finds a run but not the requested accessibility or coverage data.	The organization may not subscribe to the product or plan that supplies that data, or the data was not recorded for that run.	Check the applicable Cypress subscription and run configuration; request basic run or failure details to confirm the connection works.
Claude Desktop’s PAT bridge fails.	mcp-remote cannot find a supported Node.js runtime.	Ensure Node.js v22 or later is on the PATH visible to Claude Desktop, then restart the app.

Or skip the browser setup

If your task is to capture a webpage as an image or PDF while investigating a test failure, ScreenshotNeo is a separate website screenshot API and MCP server for developers. It does not connect to Cypress test runs. One GET request captures a URL; see the ScreenshotNeo API documentation for options and response details.

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

ScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, and failed loads are never billed; an MCP server lets AI agents take screenshots; and 1,000 screenshots per month are free with no card, with paid plans starting at $5 for 3,000. Learn about ScreenshotNeo and sign up for 1,000 free screenshots a month.

FAQ

Does this work with an unrecorded local Cypress run?

No. Cypress Cloud MCP queries data available in Cypress Cloud. Use Cypress’s local live-session tooling when an agent needs context from a running local browser.

Can an AI assistant change my tests through Cloud MCP?

No. Cypress describes the Cloud MCP tools as read-only. An assistant may separately suggest edits through its coding environment, but Cloud MCP does not apply them.

Do all MCP clients use the same config file?

No. The endpoint is consistent, but clients differ in configuration schema, file location, OAuth support, and how they store secrets. Use the relevant client example and its current setup guide.

Does every Cypress Cloud organization get accessibility and UI Coverage queries?

Not necessarily. Cypress says access to some tools depends on the plan or product subscription that provides the underlying data.

Primary sources

• Cypress Cloud MCP documentation — setup, clients, tools, privacy, limits, and troubleshooting.
• Cypress Cloud MCP general availability announcement — release date and availability.
• Cypress tap documentation — local-session tooling.
• Connect an AI agent to a live Cypress test session — local live-session context.