Cypress CloudFree Trial

Cloud MCP: Agentic Debugging

Cypress Cloud's Model Context Protocol (MCP) server connects your AI coding assistants directly to Cypress Cloud, giving them a window into your application's health and stability.

By eliminating the context gap between CI and your editor, you remove the manual triage that makes testing a bottleneck. Cloud MCP gives your AI agent real-time access to your test results. It allows agents to query run statuses, identify flaky tests, and retrieve failure details—including Test Replay links—directly within your agentic workflow.

note

Cloud MCP reached general availability on May 20, 2026. It is included on every Cypress Cloud plan at no additional cost.

How it Works

The Model Context Protocol (MCP) is an open standard that enables AI models to safely access external data and tools.

Think of MCP as the "USB port" for AI. Just as a USB port allows any peripheral to connect to any computer, MCP allows your AI assistant (the Host) to plug into Cypress Cloud (the Server) to fetch real-time context.

1. The Host: Your AI client (like Cursor, Claude Desktop, or VS Code).
2. The Server: A remote service hosted by Cypress that retrieves Cloud data for the AI.
3. The Connection: A secure pipe authenticated via OAuth (recommended) or a personal access token.

Configuring the Cloud MCP

To use the Cloud MCP:

1. Enable integration: An admin will need to enable the integration for your organization
2. Authenticate: Each user authenticates with Cypress Cloud — via OAuth (recommended) or a personal access token
3. Configure AI: Each user will need to add the remote MCP configuration to their preferred AI client

Enable for Organization

Enable the Cloud MCP integration for your organization from the Integrations page for your organization.

Each user who wants to use Cloud MCP must then authenticate — using OAuth or a personal access token.

Authenticate

There are two options for authenticating the Cloud MCP server with your Cloud account: oauth (recommended) and a personal access token (PAT).

OAuth (Recommended)

OAuth is the recommended authentication method for Cloud MCP. It uses a browser-based sign-in flow, so no manual token generation or rotation is needed — your AI client manages the session automatically.

When you configure your AI client with the Cloud MCP server URL (https://mcp.cypress.io/mcp) and your client supports OAuth, it will:

1. Detect that the server requires authentication via OAuth discovery.
2. Open a browser window and redirect you to the Cypress Cloud sign-in page.
3. After you sign in, the client stores the session securely and reconnects automatically for 30 days.

OAuth sessions are scoped to your Cypress Cloud user account and respect your existing role and permissions in each MCP-enabled organization. No token expiry management is required on your part.

Your active OAuth sessions are visible on your Manage Profile page. You can revoke any session from there at any time.

If your AI client does not support OAuth, use a personal access token instead.

Personal Access Token

A personal access token (PAT) can used to securely connect with Cypress Cloud through the Cloud MCP server. You create and manage your PAT from your Cypress Cloud profile.

1. Sign in to Cypress Cloud.
2. In the upper-left corner of any page, click your organization picture.
3. Select Manage Profile.
4. Under MCP personal access token, click Generate token.
5. Select an expiration for the token and click Continue.
6. Your token is generated. Copy it immediately — it is only shown once.

The token access is scoped to your role and permissions in each MCP-enabled organization. Use your PAT in place of OAuth when your AI client does not support browser-based authentication flows.

Configure AI Assistant

Configure your agent or AI client to connect to Cloud MCP. Cloud MCP is a remote server hosted by Cypress, so your client must support tools and remote server (HTTP) connections.

The remote URL is: https://mcp.cypress.io/mcp. Clients that support OAuth will handle authentication automatically via a browser sign-in. For clients that do not support OAuth, set the authorization header with Bearer YOUR_MCP_TOKEN using your personal access token.

Antigravity

OAuth (Recommended)

1. Open the MCP store via the "..." dropdown at the top of the editor's agent panel.
2. Click on Manage MCP Servers
3. Click on View raw config
4. Modify the mcp_config.json with your custom MCP server configuration.

   {
     "mcpServers": {
       "cypress-cloud": {
         "serverUrl": "https://mcp.cypress.io/mcp"
       }
     }
   }

5. Save mcp_config.json and click Refresh. Antigravity will prompt you to sign in to Cypress Cloud via your browser.

Personal Access Token (Alternative)

1. Follow steps 1–3 above.
2. Modify the mcp_config.json to include your token:

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

3. Replace YOUR_MCP_TOKEN with your personal access token.
4. Save mcp_config.json and click Refresh.

See Antigravity's documentation for more details.

Claude Desktop

OAuth (Recommended)

1. Open Claude Desktop.
2. Click Customize
3. Click Connectors
4. Click the + icon and select 'Add custom connector'
5. Add the connector name, i.e cypress-cloud
6. Add remote MCP url https://mcp.cypress.io/mcp
7. Click add
8. Click connect to authn

Personal Access Token (Alternative)

1. Open Claude Desktop.
2. Go to Settings > Developer > Edit Config.
3. Add the following to your 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"
         }
       }
     }
   }

4. Replace YOUR_MCP_TOKEN with your personal access token.
5. Restart Claude Desktop after saving. You should see a tools indicator in the chat input.

See Claude's documentation for more details. Note: mcp-remote requires Node.js v20+ in the path to run successfully.

Claude Code (CLI)

OAuth (Recommended)

1. Add the Cloud MCP server:

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

2. Start claude session claude

3. Prompt mcp cypress

4. Claude Code will open a browser window to sign in to Cypress Cloud

Personal Access Token (Alternative)

1. Add the Cloud MCP server with your token:

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

2. Replace YOUR_MCP_TOKEN with your personal access token.

Note: CLI Scope options are

• --scope user — available across all projects (recommended)
• --scope local — current project only (default)
• --scope project — shared via .mcp.json in project root

See Claude Code's documentation for more details.

Cursor

OAuth (Recommended)

1. Open Cursor
2. Open the "Settings" menu and select "Cursor Settings"
3. Select "Tools & MCPs"
4. Select "New MCP Server"
5. Add the following to your ~/.cursor/mcp.json:

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

6. Save the file and restart Cursor. Cursor will open a browser window to sign in to Cypress Cloud on first use.

Personal Access Token (Alternative)

1. Follow steps 1–4 above.
2. Add the following to your ~/.cursor/mcp.json:

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

3. Replace YOUR_MCP_TOKEN with your personal access token.
4. Save the file and restart Cursor.

See Cursor's documentation for more details.

GitHub Copilot in VS Code

You can install the Cloud MCP server in your user profile or a specific workspace. See VS Code's MCP installation options.

OAuth (Recommended)

1. Add the following to your .vscode/mcp.json:

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

2. VS Code will handle authentication via a browser-based Cypress Cloud sign-in when the server is first used.

Personal Access Token (Alternative)

1. Add the following to your .vscode/mcp.json:

   {
     "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
       }
     ]
   }

2. VS Code will prompt for your PAT via the CYPRESS_MCP_TOKEN input when connecting.

See VS Code's documentation for more details.

GitHub Copilot CLI

GitHub Copilot CLI uses a personal access token for Cloud MCP authentication.

1. Add the following to your global config (~/.copilot/mcp-config.json) or project config (.copilot/mcp-config.json):

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

2. Set the environment variable before launching the CLI, replacing YOUR_MCP_TOKEN with your personal access token.
   • macOS/Linux: export CYPRESS_MCP_TOKEN=YOUR_MCP_TOKEN
   • Windows (Powershell): $env:CYPRESS_MCP_TOKEN="YOUR_MCP_TOKEN"
3. Verify the connection. Run /mcp show inside the Copilot CLI to confirm the server is loaded and the variable is resolved.

See GitHub Copilot's documentation for more details.

OpenAI Codex CLI

Codex stores MCP configuration in ~/.codex/config.toml, which is shared between the CLI and Codex IDE extension.

OAuth (Recommended)

1. Add the Cloud MCP server:

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

2. Start the OAuth flow:

   codex mcp login cypress-cloud

3. Sign in to Cypress Cloud in the browser window that opens.

4. Start a new Codex session. In the CLI, run /mcp to confirm the cypress-cloud server is connected.

You can also add the server manually to ~/.codex/config.toml and then run codex mcp login cypress-cloud:

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

Personal Access Token (Alternative)

1. Add the following to ~/.codex/config.toml:

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

2. Set your token in your environment, replacing YOUR_MCP_TOKEN with your personal access token:
   • macOS/Linux: export CYPRESS_MCP_TOKEN=YOUR_MCP_TOKEN
   • Windows (Powershell): $env:CYPRESS_MCP_TOKEN="YOUR_MCP_TOKEN"

See Codex's documentation for more details.

If you use an AI client not listed here, refer to its documentation for configuring a remote MCP connection.

Available tools

Once connected, your AI agent can autonomously use the following tools. You don't call these manually; the agent selects them based on your prompt.

Each time the Cloud MCP connection is established, any new tools become immediately available.

Some tools are relevant for all Cypress Cloud plans (including free), but some others are for plan-specific data like flaky test reporting, or product-specific data like Cypress Accessibility violation details. These are only available if your organization has subscriptions for the plans and products that would provide the underlying data.

Tool	Capability	Best Use Case
cypress_get_projects	Lists all projects in your Org.	Helping the agent find the correct projectId for subsequent queries.
cypress_get_runs	Returns run summaries for a project, run URL, or git branch. Summaries include project name, run number, status, run URL, tags, and test status counts.	"Check the status of the last CI run on main"
cypress_get_failed_tests	Retrieves attempt details: test name, spec, attempt error and stack trace, and a Test Replay link for quick debugging. Does not return test artifacts.	"Analyze why the checkout test failed in the latest run."
cypress_get_flaky_tests	Identifies the flaky tests in a run.	"Are these failures regressions or known flakiness?"
cypress_get_accessibility_report	Returns a high-level accessibility report for a run: violation counts by severity, failing rules with element counts, and the top 5 views sorted by failure count.	"Summarize accessibility violations for the latest run on this branch."
cypress_get_accessibility_views	Returns paginated views from an accessibility report, sorted by number of failing rules. Use to browse all views beyond the top 5 in the report summary.	"Which pages have the most accessibility failures in this run?"
cypress_get_accessibility_rule_failures	Returns paginated failing DOM elements for a specific accessibility rule, with CSS selector, view, and failure message. Optionally scope to a specific view.	"Show me all color-contrast failures on the checkout page."
cypress_get_ui_coverage_report	Returns a high-level UI Coverage report for a run: overall coverage score, tested and untested element and link counts, and the top 5 riskiest views sorted by most untested interactive elements.	"Summarize UI Coverage for the latest run on this branch."
cypress_get_ui_coverage_views	Returns paginated views from a UI Coverage report, sorted by most untested elements and links. Use to browse all views beyond the top 5 in the report summary.	"Which pages have the most untested elements in this run?"
cypress_get_ui_coverage_elements	Returns paginated interactive elements for a run. Filter by tested or untested, and optionally scope to a specific view by name.	"Show me the untested elements on the checkout page in this run."
cypress_feedback	Shares feedback with Cypress directly from your agentic environment.	"Report a bug or request a new MCP feature."

Writing effective prompts

To get the most out of Cloud MCP, follow these three principles:

• Trigger Explicitly: Use the phrase "Cypress Cloud" to ensure the agent looks for the correct MCP tools.
• Provide Context: Mention "this branch," "this commit," or paste a Run URL directly.
• Define the Workflow: Don't just ask what failed; ask the agent to fix it.

Example Prompts

note

Pro-Tip: If you find a workflow that works well, save it as a Custom Instruction or Skill in your AI client to standardize debugging for your entire team.

The Health Check

"Check Cypress Cloud for the latest run on this branch. Give me a high-level summary of any failures."

The Deep Debug

"Find the failing tests for [Run URL]. For each failure, look at the stack trace, check my local code, and propose a fix to stop the regression."

The Flake Audit

"List all flaky tests from the last 5 runs in Cypress Cloud. Are there any common patterns in the error messages?"

The Accessibility Triage

"Pull the Cypress Cloud Accessibility report for the latest run on this branch. List any critical or serious violations grouped by rule, and tell me which views are most impacted."

For a deeper exploration of working with Cloud MCP's accessibility tools, read our guide Cypress Accessibility - Work with AI agents.

The UI Coverage Triage

"Using Cypress Cloud, pull the UI Coverage report for the latest run on this branch. Tell me the overall coverage score, list the views with the most untested elements, and show me the specific untested elements on the riskiest view."

For more patterns, example prompts, and governance ideas when using UI Coverage with agents, read Cypress UI Coverage - Work with AI agents.

FAQs

Troubleshooting

Agent can't find your run:

• Verify the organization has the Cloud MCP integration enabled in Cypress Cloud.
• Ensure your Git branch name in CI matches the branch name you're telling agent.

Connection errors:

• If using OAuth: ensure your browser can reach https://cloud.cypress.io to complete sign-in. If the browser window doesn't open, try removing and re-adding the server config in your AI client.
• If using a personal access token: verify your PAT hasn't expired (check Manage Profile).
• Check firewall and proxy settings to ensure https://mcp.cypress.io is allowlisted.

Switching from a personal access token to OAuth:

If you previously configured Cloud MCP with a PAT and want to switch to OAuth:

1. Remove the Authorization header (or token environment variable) from your AI client's MCP config.
2. Save the config and reconnect. Your client will detect that no token is present and trigger the OAuth browser sign-in flow automatically.

Pricing & Availability

Cloud MCP is available for free to all Cypress Cloud plans, including the Starter plan. We believe AI-assisted debugging should be accessible to every developer building with Cypress.

No minimum Cypress App version is required to get started.

Cloud MCP reached generally available on May 20th, 2026.

Usage Limits

Current limits include 100 tool requests per hour for all plans.

Cloud MCP data availability matches existing test recording limits and data retention policies for your plan.

If you need to increase your limits, contact support at [email protected].

Security & Privacy

Cloud MCP is an API for AI agents. When your AI assistant needs information about your Cypress test runs, it calls Cloud MCP the same way any application calls an API — it sends a request, and Cypress returns data.

What Cypress can and cannot see:

• Cypress cannot see your AI conversation: Cypress has no access to your AI assistant's context window, chat history, or anything it generates. The only thing Cypress receives are the inputs to a tool call — for example, getRuns(projectId: 100, runNumber: 45, limit: 10).
• Cypress does not train on your data: Test results, stack traces, and replay links returned through Cloud MCP are used only to fulfill the request. Your data is never used to train or improve any LLM.
• You control the connection: Cloud MCP is opt-in. Enabling it means your AI assistant can request Cypress data and enabling the integration does not give Cypress any visibility into your AI's context, conversation, or outputs.

How access is controlled:

• Read-only: Cloud MCP is designed for data retrieval and debugging. It cannot modify your test code or delete runs.
• User-scoped: Your AI assistant can only access the projects and data your Cypress Cloud user has permission to see. It operates within the same access boundaries as you do.
• Locally managed: You control when the server is active by managing the configuration in your local AI client.

Cloud MCP implements the standard MCP authorization specification with OAuth 2.0 and uses streamable HTTP transport. It falls under our AI security practices →

Remove the integration

Remove the Cloud MCP integration at any time by going to the Integrations page for your organization and selecting Disable in the Cypress MCP section.

Disabling the integration immediately revokes access for all users in that organization, regardless of whether they authenticated via OAuth or a personal access token.

Send feedback

You can share feedback directly through your agent:

"Send Cypress the following feedback: [Your message here]"

Alternatively, use this feedback form to share any feedback, use cases, or issues encountered with your prompts and queries.

Also See

• Recording Cloud Runs
• Cypress AI
• cy.prompt()
• Cypress Accessibility - Work with AI agents
• Cypress UI Coverage - Work with AI agents