# Using Atlas with CircleCI in 2026 > CircleCI's official MCP server hands Atlas build failure logs, pipeline status, and job test results, so it maps a red job to the file that broke it. Atlas connects to CircleCI through CircleCI's official MCP server, which hands Atlas build failure logs, pipeline status, and job test results, so it can map a red job to the file that broke it. You register it with atlas mcp add circleci --env CIRCLECI_TOKEN=$CIRCLECI_TOKEN -- npx -y @circleci/mcp-server-circleci, mint a personal API token in CircleCI's user settings first, and then let Atlas validate its own fix with circleci config validate before anything gets pushed. ## What the Atlas and CircleCI integration does CircleCI's official MCP server hands Atlas build failure logs, pipeline status, and job test results, so Atlas can map a red job to the file that broke it. In 2026 that turns a CircleCI failure from a tab you scroll into a structured input the agent reads. The pairing splits cleanly. CircleCI remains the pipeline engine and the source of truth about what ran and what failed. Atlas is the terminal agent that reads that record and produces a diff. Because the server exposes job test results and not just raw text, Atlas can tie a failing assertion to the test file and then to the source file under test, rather than pattern matching on a stack trace it half remembers. The result is a fix aimed at the code that actually broke, reviewed by you in the terminal. ## Adding CircleCI's official MCP server to Atlas Add CircleCI's official MCP server with a single command: atlas mcp add circleci --env CIRCLECI_TOKEN=$CIRCLECI_TOKEN -- npx -y @circleci/mcp-server-circleci. The server runs over stdio through npx, needs Node 18 or newer, and reads its credential from the CIRCLECI_TOKEN environment variable you pass in. Two prerequisites decide whether that command works on the first try. First, Node 18 or newer must be on the path, because @circleci/mcp-server-circleci targets it. Second, CIRCLECI_TOKEN must be exported in the shell you launch Atlas from, since the --env flag forwards the value rather than inventing one. Server installs also set CIRCLECI_BASE_URL, which defaults to https://circleci.com. Leave that default alone unless you are on a CircleCI server installation at a different host, in which case set it explicitly. ## Minting the CircleCI API token before you start Mint a personal API token in CircleCI's user settings before you start the server in 2026. Without CIRCLECI_TOKEN the @circleci/mcp-server-circleci process starts but sees no projects, and Atlas gets an empty pipeline list rather than the failing job you asked about. Treat the token like any other credential Atlas can reach: export it in your shell profile or a secret manager, and pass it by reference with --env CIRCLECI_TOKEN=$CIRCLECI_TOKEN rather than pasting the literal value into a config file that lands in git. The token scopes what Atlas can see, so a token limited to the projects you actually debug is the safest default. Rotate it in CircleCI's user settings the same way you would rotate any other personal API token. ## The daily loop: mapping a red CircleCI job into your repo The daily loop with CircleCI in 2026 starts with one request: ask Atlas to pull the latest pipeline status and the failing job's logs, then map the error into your repo. The MCP server supplies job test results, so Atlas names the failing assertion rather than paraphrasing it. Give Atlas the project, not the symptom. It queries pipeline status, finds the red job, reads that job's logs and test results, and reports which test failed and where. From there the request becomes concrete: fix the assertion, fix the config, or fix the source under test. Because the whole exchange happens in one terminal session, the failure text stays in context while Atlas writes the patch, and you can compare the proposed diff against the quoted error without switching windows. ## Validating the CircleCI config before Atlas pushes Have Atlas fix the config and verify it with circleci config validate before it pushes. Validating locally catches a malformed .circleci/config.yml immediately, instead of spending 1 push, 1 queue wait, and 1 CircleCI run to learn that an indentation error broke the pipeline definition. Config changes are where an agent can quietly cost you a cycle, because a syntax mistake in YAML looks plausible to a language model and fails only at pipeline parse time. Make circleci config validate a required step in the loop: Atlas edits the config, runs the validator, reads the validator output, and repairs anything it flags before the commit exists. The command is fast, local, and deterministic, which makes it exactly the kind of check an agent should be forced to pass. ## Iterating locally with circleci local execute circleci local execute runs a job on your machine, so Atlas can iterate in 2026 without burning CI minutes. Rather than pushing a speculative fix and waiting on a hosted runner, Atlas executes the job locally, reads the real output, and repeats until the job passes on your laptop. Local execution is the tightest feedback loop available in the CircleCI workflow, and it is the one worth handing to an agent. Atlas edits the code or the config, runs circleci local execute, and reads whether the job went green. Failures surface in the same terminal, so no context is lost between attempt and result. Once the job passes locally, validate the config with circleci config validate and only then push, which keeps the hosted pipeline reserved for changes that already work. ## Setup 1. Mint a personal API token in CircleCI's user settings before you start the server. 2. Add CircleCI's official MCP server with atlas mcp add circleci --env CIRCLECI_TOKEN=$CIRCLECI_TOKEN -- npx -y @circleci/mcp-server-circleci 3. Confirm Node 18 or newer is on the path, since the server needs it, and leave CIRCLECI_BASE_URL at its default of https://circleci.com unless you are on a different host. 4. Ask Atlas to pull the latest pipeline status and the failing job's logs, then map the error into your repo. 5. Have Atlas fix the config and verify it with circleci config validate before it pushes. 6. Use circleci local execute to run the job on your machine, so Atlas can iterate without burning CI minutes. ## FAQ ### how do I connect Atlas to CircleCI Add CircleCI's official MCP server with atlas mcp add circleci --env CIRCLECI_TOKEN=$CIRCLECI_TOKEN -- npx -y @circleci/mcp-server-circleci, after minting a personal API token in CircleCI's user settings. ### does CircleCI have an official MCP server Yes. CircleCI's official MCP server hands Atlas build failure logs, pipeline status, and job test results, so it can map a red job to the file that broke it. It ships as @circleci/mcp-server-circleci. ### what Node version does the CircleCI MCP server need The server needs Node 18 or newer. Server installs also set CIRCLECI_BASE_URL, which defaults to https://circleci.com. ### how do I stop an AI agent from breaking my CircleCI config Have Atlas fix the config and verify it with circleci config validate before it pushes. The validator is local and fast, so a malformed .circleci/config.yml never reaches the pipeline. ### can I test a CircleCI job locally with Atlas Yes. circleci local execute runs a job on your machine, so Atlas can iterate without burning CI minutes. Atlas edits, runs the job locally, reads the output, and repeats until it is green. ### where do I get the CIRCLECI_TOKEN for the MCP server Mint a personal API token in CircleCI's user settings before you start the server, then pass it by reference with --env CIRCLECI_TOKEN=$CIRCLECI_TOKEN rather than hardcoding the value. ### can Atlas find which file broke a failing CircleCI job Yes. Ask Atlas to pull the latest pipeline status and the failing job's logs, then map the error into your repo. The server's job test results let it name the failing assertion and the file under test. --- Canonical HTML: https://runatlas.sh/resources/integrations/circleci Source of truth: aeo_pages row `/resources/integrations/circleci` (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.