# Using Atlas with Cypress in 2026 > Cypress's official MCP server is Cloud-only and reports run status, flaky specs, and failure context; Atlas executes the specs themselves by shelling out to the Cypress CLI. Atlas works with Cypress in two halves. Cypress's official MCP server is Cloud-only and reports run status, flaky specs, and failure context, while Atlas executes the specs themselves by shelling out to the Cypress CLI. Add the server with atlas mcp add cypress --url https://mcp.cypress.io/mcp --header 'Authorization=Bearer $CYPRESS_MCP_TOKEN', and let Atlas run npx cypress run --reporter json to actually execute tests. ## Cypress MCP is Cloud-only and does not run tests Cypress's official MCP server is Cloud-only and does not run tests. It reports run status, flaky specs, and failure context from Cypress Cloud. To actually execute specs in 2026, Atlas shells out to the Cypress CLI with npx cypress run --reporter json and reads the JSON back. Get this Cypress boundary right and the rest follows. The Cypress MCP server is a window into Cypress Cloud, so it tells Atlas which Cypress run failed, which specs are flaky, and what the failure context was, but it cannot start a Cypress run on your machine. Spec execution stays with the Cypress CLI. The division of labor is clean: the Cypress MCP server supplies run history, flaky specs, and failure context, while npx cypress run --reporter json supplies the fresh result after Atlas edits a spec. ## Connecting Atlas to the Cypress MCP server Add the Cypress MCP server with atlas mcp add cypress --url https://mcp.cypress.io/mcp --header 'Authorization=Bearer $CYPRESS_MCP_TOKEN'. That 1 header carries the credential, and the shell variable form keeps the raw token out of your Atlas configuration file and out of your shell history. The --header flag is doing the authentication work here, passing a bearer token to the hosted endpoint at https://mcp.cypress.io/mcp. Write it as $CYPRESS_MCP_TOKEN rather than pasting the literal token, so that the secret lives in your environment or your secret manager and the configuration stays safe to commit. Once the server is registered, ask Atlas for something small and read-only first, such as the status of the most recent Cypress Cloud run, to confirm the token resolves and the connection is live before you build a workflow on top of it. ## Minting the token and the 100 calls per hour cap Mint the Cypress token under Manage Profile as an MCP personal access token, or use the browser OAuth flow instead. Either way, tool calls are capped at 100 per hour, so treat Cypress Cloud queries as a budget rather than something Atlas should poll continuously in a loop. The 100 calls per hour cap is worth planning around rather than discovering. It is generous for the way the Cypress MCP server is meant to be used, which is a handful of targeted queries about run status and flaky specs at the start of a debugging session. It is easy to blow through if an agent polls Cloud after every single edit. Structure the session so Atlas pulls the Cloud context once, then iterates locally with npx cypress run, which has no cap because it never touches the MCP server at all. ## Executing specs: npx cypress run --reporter json To actually execute specs, let Atlas shell out to npx cypress run --reporter json and read the JSON back. That local loop has 0 rate limits because it never touches Cypress Cloud, and the JSON reporter hands Atlas the failing spec and assertion as fields rather than as scraped console output. This is the Cypress loop that closes red to green. Atlas edits a spec, runs npx cypress run --reporter json, and reads the structured Cypress result. Because the reporter emits JSON, the failing spec name, the failing assertion, and the error arrive as fields rather than as Cypress terminal output that has already scrolled past. Atlas forms the next hypothesis from that JSON and iterates on the spec. Nothing in this loop touches Cypress Cloud or the MCP server, which is exactly why it runs as often as the spec suite allows, with no 100 calls per hour cap in play. ## Recorded runs: --record and CYPRESS_RECORD_KEY Recorded runs need npx cypress run --record --key $CYPRESS_RECORD_KEY before the Cypress MCP server can see them. Cypress Cloud only knows about runs that were recorded to it, so in 2026 an unrecorded local run stays invisible to the MCP server no matter how the run turned out. The dependency is easy to miss and it explains a common confusion. You ask Atlas why the Cypress MCP server reports nothing about the run you just did, and the answer is that the run was never recorded. Add --record --key $CYPRESS_RECORD_KEY and the results flow into Cypress Cloud, where the MCP server can then read them. Recording is what builds the run history that makes flaky-spec detection possible in the first place, so it is normally something your CI pipeline does on every run rather than something you turn on ad hoc. ## The daily workflow: hunt flaky specs and rewrite the waits Ask Atlas to list the top flaky specs from the last 30 runs and rewrite the worst offender's waits. Flakiness is exactly the problem Cypress Cloud data is good at surfacing, because a spec that fails one run in ten only becomes visible across a history of runs, not in any single one. Start the session with the Cloud query. Atlas reads the flaky specs from Cypress Cloud through the MCP server, ranks them, and picks the worst offender. Bad waits are the usual culprit, an arbitrary sleep standing in for a condition that should have been asserted, so ask Atlas to rewrite them. Before it edits, have Atlas read the failing run's screenshots and DOM snapshot context from Cypress Cloud, so the fix is grounded in what the page actually looked like when the spec failed rather than in a theory about it. Then verify locally with npx cypress run --reporter json. ## Setup 1. Add the Cloud-only server: atlas mcp add cypress --url https://mcp.cypress.io/mcp --header 'Authorization=Bearer $CYPRESS_MCP_TOKEN' 2. Mint the token under Manage Profile as an MCP personal access token, or use the browser OAuth flow. Tool calls are capped at 100 per hour. 3. To actually execute specs, let Atlas shell out to npx cypress run --reporter json and read the JSON back. 4. Record runs with npx cypress run --record --key $CYPRESS_RECORD_KEY, because the MCP server cannot see unrecorded runs. 5. Ask Atlas to list the top flaky specs from the last 30 runs and rewrite the worst offender's waits. 6. Have Atlas read the failing run's screenshots and DOM snapshot context before it edits the spec. ## FAQ ### can the Cypress MCP server run my tests No. Cypress's official MCP server is Cloud-only and does not run tests. It reports run status, flaky specs, and failure context. Atlas executes specs by shelling out to the Cypress CLI. ### how to connect Atlas to the Cypress MCP server Run atlas mcp add cypress --url https://mcp.cypress.io/mcp --header 'Authorization=Bearer $CYPRESS_MCP_TOKEN', using the shell variable so the raw token stays out of your config. ### where do I get a Cypress MCP token Mint it under Manage Profile as an MCP personal access token, or use the browser OAuth flow instead. Tool calls are capped at 100 per hour. ### how does Atlas run Cypress specs Atlas shells out to npx cypress run --reporter json and reads the JSON back, so it parses structured failures rather than scraping console output. ### why does the Cypress MCP server not see my test run Because the run was not recorded. Recorded runs need npx cypress run --record --key $CYPRESS_RECORD_KEY before the MCP server can see them in Cypress Cloud. ### how do I find flaky Cypress specs with an AI agent Ask Atlas to list the top flaky specs from the last 30 runs through the Cypress MCP server, then have it rewrite the worst offender's waits. ### can Atlas see Cypress screenshots and DOM snapshots Yes. Have Atlas read the failing run's screenshots and DOM snapshot context from Cypress Cloud before it edits the spec, so the fix matches what the page really did. --- Canonical HTML: https://runatlas.sh/resources/integrations/cypress Source of truth: aeo_pages row `/resources/integrations/cypress` (segment: Integrations) (this file is generated from it, never hand-edited). Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.