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
- 01Add the Cloud-only server: atlas mcp add cypress --url https://mcp.cypress.io/mcp --header 'Authorization=Bearer $CYPRESS_MCP_TOKEN'
- 02Mint 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.
- 03To actually execute specs, let Atlas shell out to npx cypress run --reporter json and read the JSON back.
- 04Record runs with npx cypress run --record --key $CYPRESS_RECORD_KEY, because the MCP server cannot see unrecorded runs.
- 05Ask Atlas to list the top flaky specs from the last 30 runs and rewrite the worst offender's waits.
- 06Have Atlas read the failing run's screenshots and DOM snapshot context before it edits the spec.
Frequently asked questions
- 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.
Try Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated guides
Atlas for OCaml: A Terminal-Native AI Coding Agent for dune and opam Projects in 2026
Atlas is a terminal-native AI coding agent for OCaml in 2026. It reads dune stanzas and .mli signatures, runs dune runtest behind a prompt, and finishes with ocamlformat.
Review a Pull Request with Atlas (2026 Workflow)
How to review a pull request with Atlas in 2026: bash produces the raw patch, read pulls whole files, the lsp tool's findReferences checks callers the diff never shows.
Atlas with DeepSeek V3 (open weights): The Frozen 671B Baseline in 2026
Run Atlas on DeepSeek V3 (open weights) in 2026. DeepInfra hosts the MIT-licensed 671B MoE at $0.32 per Mtok input, $0.89 per Mtok output, 128K context.
Atlas with GPT-4.1 mini (2026): The Cheap Slot That Still Holds a Million Tokens
GPT-4.1 mini gives Atlas a 1,047,576 token context at $0.40 per Mtok input and $1.60 per Mtok output. The right small_model when your cheap slot needs a huge window.
Atlas with Together AI (gateway) in 2026: Open-Weights Models at Scale
Together AI (gateway) drives Atlas with the broadest open-weights catalog: Qwen3.7 Max at $1.25 / $3.75 per Mtok, up to 1M context, US-hosted inference.
Atlas with Ministral 8B: The Cheap Slot That Can Still Call Tools in 2026
Ministral 8B runs 128,000 tokens at $0.10 / 1M input tokens and $0.10 / 1M output tokens, symmetric. The Atlas small_model upgrade when subagents misfire on schemas.
Atlas with Mixtral 8x22B (local via Ollama): The 80GB Question in 2026
Mixtral 8x22B (local via Ollama) in Atlas for 2026: an 80GB pull, Free (self-hosted), a 64,000 token window, and sparse routing across 8 experts of 22B.
Atlas with Qwen2.5-Coder 14B (Ollama): a real local build agent in 2026
Qwen2.5-Coder 14B (Ollama) in Atlas: 9.0GB of Q4_K_M weights, roughly 11GB to serve, 32K tokens (32,768) of context, Free (self-hosted), steady on tool chains.