Use AI to resolve CI test failures with zero guesswork

Test failures are inevitable. A broken condition, a missed edge case, or a last-minute refactor can trip up even the most careful changes. That’s part of shipping software. What shouldn’t be part of the job is spending half your afternoon parsing logs and chasing down the root cause.

Now, there’s a faster way.

This guide shows how to use the CircleCI MCP server to identify, understand, and resolve failing tests in a CI/CD build without ever leaving your editor. It’s a smarter feedback loop that brings your CI signal straight into your coding environment, so you can go from failure to fix without breaking focus.

Why focus on test failures?

Test output is helpful, but raw logs don’t tell the whole story. Developers still spend time bouncing between build logs, source files, and docs trying to understand what went wrong. That context switching adds up.

Test failures slow teams down and cost businesses money. When they interrupt flow, they create delays that ripple into lead time, deployment frequency, and overall delivery performance.

The CircleCI MCP Server runs inside your IDE and helps with this exact problem. When your test suite fails in CircleCI, the agent can:

• Pull failure logs through the CircleCI API
• Identify which test failed and why
• Locate the relevant code in your project
• Propose a fix that aligns with the test’s intent

Instead of pausing to investigate, you ask the agent to take a look. It brings back the failure, pinpoints the issue, and suggests a fix, all within your editor. That way you can get back on track quickly and focus on delivering value to your users.

Set up the example project

To demonstrate how the CircleCI MCP server works, we’ll walk through a small project that includes a failing test by design. This makes it easy to see how the agent responds to real CI output and applies a fix based on what the test expects.

Prerequisites

To follow along, you’ll need:

• A free CircleCI account
• A GitHub account
• Node.js 18+
• Any IDE with MCP support (such as Cursor)

Prepare your environment

Before your assistant can access your CircleCI data, you’ll need to authorize it with an API token.

Go to your CircleCI User Settings and create a new personal API token. Be sure to copy and store it somewhere safe. You’ll need it during setup.

Next, you’ll need to configure your IDE to use the MCP server using the API token you just created.

This step links the assistant to your CircleCI account and gives it permission to access the logs and status data it needs to analyze test runs.

Step 1: Clone the example repo

Start by setting up a local copy of the demo project. It includes a math function with a simple logic bug and a test that fails as a result.

This minimal setup helps you see exactly how the MCP server identifies the issue and proposes a fix without getting lost in application complexity.

git clone https://github.com/CircleCI-Public/circleci-mcp-cookbook.git
cd circleci-mcp-cookbook/fix-failed-tests

You can find this project and other usage examples in the CircleCI MCP Cookbook.

Step 2: Push the code and trigger a failing build

Next, connect the repo to CircleCI so you can run the test suite in a real CI environment. The goal here is to generate a real test failure that the MCP Server can respond to.

Here’s how to trigger the initial failing build:

1. Create a new project in CircleCI and link it to your GitHub repo.
2. Push the code.

Once the pipeline runs, CircleCI will execute the test suite.

This gives us a clear failure to work with: the function is returning the wrong result.

Step 3: Ask your code assistant to fix the error

With the test failure in place, open your IDE and start a new chat with the agent. This is where the CircleCI MCP server begins to assist.

Ask the agent:

fix the failed test in CI

The agent will use the MCP Server to request structured test failure logs from your most recent pipeline run.

The assistant will parse the output and identify the exact test that failed. In this case, it sees that the test is returning -1 instead of the expected 3.

Next, the assistant traces the failure back to your source code. It opens the file containing the broken logic and highlights the specific function implementation.

At this point, it understands both the failure and the intent of the test and is ready to propose a fix.

Step 4: Push the fix and re-run your pipeline

Once you’ve reviewed and accepted the fix, commit the change and push it to GitHub. CircleCI will automatically rerun the pipeline.

If the fix was accurate, the pipeline will pass.

To confirm the pipeline status without switching to your browser, you can ask the agent:

what’s the status of the latest pipeline for this project?

Behind the scenes, the get_latest_pipeline_status tool will retrieve and summarize the most recent pipeline for your branch. You’ll see something like:

---
Workflow: build
Status: success
Duration: 2 minutes
Created: 5/01/2025, 10:15:30 AM
Stopped: 5/01/2025, 10:17:45 AM
---
Workflow: test
Status: success
Duration: 1 minute
Created: 5/01/2025, 10:18:00 AM
Stopped: 5/01/2025, 10:19:03 AM

This gives you a quick, readable overview of build progress and health directly in your IDE. Whether you’re validating a single test fix or checking the entire pipeline, it keeps the feedback loop fast and focused.

A faster feedback loop

This workflow shortens the gap between detection and resolution. CI failures no longer mean a 20-minute detour into logs, test files, and scattered breakpoints. You stay focused. The agent brings the context, helps with the fix, and moves you forward.

Try it yourself

You can try this workflow in under 10 minutes.

• Clone the example project
• Set up the CircleCI MCP Server in any IDE with MCP support
• Push a change to trigger a failing test
• Ask the agent to fix it

That’s all it takes to move from failure to fix.

What’s next?

We’re constantly adding new tools and feature to the MCP server to help you improve velocity, reduce toil, and integrate test feedback into your day-to-day development loop. You can stay up to date by watching the server repository or our changelog. You can also check back for new examples and guidance in the CircleCI MCP Server Cookbook.

To get started, sign up for a free CircleCI account and learn more about the CircleCI MCP server. It only takes a few minutes to set up, and once you do, you’ll start handling test failures faster and with less friction.