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
- 01Mint a personal API token in CircleCI's user settings before you start the server.
- 02Add CircleCI's official MCP server with atlas mcp add circleci --env CIRCLECI_TOKEN=$CIRCLECI_TOKEN -- npx -y @circleci/mcp-server-circleci
- 03Confirm 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.
- 04Ask Atlas to pull the latest pipeline status and the failing job's logs, then map the error into your repo.
- 05Have Atlas fix the config and verify it with circleci config validate before it pushes.
- 06Use circleci local execute to run the job on your machine, so Atlas can iterate without burning CI minutes.
Frequently asked questions
- 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.
Try Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated guides
Atlas with Gemini 3 Flash (2026): The $0.5 Default for All Day Agent Loops
Gemini 3 Flash gives Atlas a 1,048,576 token context and 65,536 token output at $0.5 per Mtok input and $3 per Mtok output. The economical default for agent loops.
Atlas with Qwen2.5-Coder 1.5B (Ollama): the 986MB small_model slot in 2026
Qwen2.5-Coder 1.5B (Ollama) in Atlas: a 986MB Q4_K_M pull with 32K tokens (32,768) of context, Free (self-hosted), sized for titles and summaries, not refactors.
Atlas for Fortran: fpm.toml, Explicit Interfaces, and fprettify in 2026
Atlas is a terminal-native AI coding agent for Fortran in 2026. It reads modules, explicit interfaces, and intent declarations, runs fpm test behind a prompt, and runs fprettify.
Atlas with Claude Haiku 4.5: The Cheap Slot in 2026
Claude Haiku 4.5 runs Atlas's small_model slot at $1 / $5 per Mtok with a 200K window. Titles, commit summaries, and cheap subagent fan-out, priced honestly for 2026.
Atlas for Groovy: A Terminal-Native AI Coding Agent for Gradle, Spock, and Jenkins in 2026
Atlas is a terminal-native AI coding agent for Groovy in 2026. It reads build.gradle closures and Jenkinsfiles, writes Spock specs, runs ./gradlew test, and applies Spotless.
Atlas with Amazon Nova Micro in 2026: The Cheapest Model on Bedrock
Amazon Nova Micro costs $0.035 per Mtok input, the lowest price in the Bedrock catalog, with a 128K token context. Use it as Atlas's small_model, never as the build loop.
Atlas vs Augment Code: Choosing a Terminal AI Coding Agent in 2026
In 2026, Atlas offers a free, terminal-native AI agent with local embeddings and robust safety. Augment Code's Cosmos platform provides shared memory for teams at $100/month.
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.