Cypress CloudFree Trial

Cloud MCP: Agentic Debugging Beta

Cypress Cloud Model Context Protocol (MCP) server gives AI coding assistants a direct window into your application’s health and stability by connect it directly to Cypress Cloud.

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.

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.

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

Configuring the Cloud MCP

To use the Cloud MCP:

Enable integration: An admin will need to enable the integration for your organization
Generate personal access token: Each user will need to create a personal access token to authenticate with Cloud MCP
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.

Enable Cloud MPC organization integration

Each user who wants to use Cloud MCP must then generate a personal access token to authenticate.

Generate personal access token

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

Sign in to Cypress Cloud.
In the upper-left corner of any page, click your organization picture.
Select Manage Profile.
Under MCP personal access token, click Generate token.
Select an expiration for the token and click Continue.
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

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. Set the authorization header with Bearer CYPRESS_MCP_PAT.

Antigravity

Open the MCP store via the "..." dropdown at the top of the editor's agent panel.
Click on Manage MCP Servers
Click on View raw config

Modify the mcp_config.json with your custom MCP server configuration.

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

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

See Antigravity's documentation for more details.

Claude Desktop

Open Claude Desktop.
Go to Settings > Developer > Edit Config.

Add the following to your claude_desktop_config.json:

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

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

See Claude's documentation for more details.

Claude Code (CLI)

Add the Cloud MCP like:

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

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

Open Cursor
Open the "Settings" menu and select "Cursor Settings"
Select "Tools & MCPs"
Select "New MCP Sever"

Add the following to your ~/.cursor/mcp.json:

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

Replace YOUR_MCP_TOKEN with your personal access token.
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.

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

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

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

Set the Environment Variable: Before launching the CLI, ensure the token is exported in your terminal, 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"
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

Add the following to ~/.codex/config.toml (shared between CLI and Codex IDE extension):

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

Set your token in your environment:
- 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.

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_test_details`	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_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

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?"

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.

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 the AI.

Connection errors:

Verify your PAT hasn't expired (check Manage Profile).
Check firewall and proxy settings to ensure https://mcp.cypress.io is allowlisted.

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 required to get started.

Usage Limits

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

Cloud MCP data available 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

Read-Only Access: The Cloud MCP server is designed for data retrieval and debugging. It cannot modify your test code or delete runs.
User-Scoped: The AI only sees the projects and data that your specific Cypress Cloud user has permission to access. Whether you're part of a specific team or just have access to certain projects, your AI assistant stays within those same boundaries.
Local Control: You control exactly when the server is active by managing the configuration in your local AI client.

Remove the integration

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

Disabling immediately prevents any users who have previously generated a PAT from accessing data for that organization.

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.

Cloud MCP: Agentic Debugging Beta

How it Works

Configuring the Cloud MCP

Enable for Organization

Generate personal access token

Configure AI Assistant

Available tools

Writing effective prompts

Example Prompts

The Health Check

The Deep Debug

The Flake Audit

FAQs

Troubleshooting

Pricing & Availability

Usage Limits

Security & Privacy

Remove the integration

Send feedback

Also See

Contents

How it Works​

Configuring the Cloud MCP​

Enable for Organization​

Generate personal access token​

Configure AI Assistant​

Available tools​

Writing effective prompts​

Example Prompts​

The Health Check​

The Deep Debug​

The Flake Audit​

FAQs​

Troubleshooting​

Pricing & Availability​

Usage Limits​

Security & Privacy​

Remove the integration​

Send feedback​

Also See​

Contents

How it Works

Configuring the Cloud MCP

Enable for Organization

Generate personal access token

Configure AI Assistant

Available tools

Writing effective prompts

Example Prompts

The Health Check

The Deep Debug

The Flake Audit

FAQs

Troubleshooting

Pricing & Availability

Usage Limits

Security & Privacy

Remove the integration

Send feedback

Also See