Find and fix CI build errors with AI

Software teams rely on CI/CD pipelines to build, test, and deploy code quickly. But when a build fails, it can disrupt the entire workflow. Digging through logs, chasing down errors, and switching between dashboards takes time you don’t want to waste.

In this tutorial, you’ll learn how to use your AI coding assistant — powered by structured data from your CI system — to diagnose and fix build failures faster. We’ll walk through setting up a broken project, using the CircleCI MCP server to retrieve build failure data, and letting your assistant guide you through identifying and correcting the issue, all without leaving your IDE.

This example is based on a real-world scenario from our CircleCI MCP Server Cookbook, where you can find patterns and examples for integrating CI insights into your development workflow.

Setting up the example project

Before you start, make sure you have:

• A CircleCI account
• A GitHub account
• Node.js 18 or newer installed locally
• An IDE that supports MCP server integration (Cursor, Windsurf, Claude Code, etc.)

Start by forking the example repository provided for this tutorial. Forking creates your own copy of the project under your GitHub account, ready for you to build on.

The project includes a pre-configured CircleCI pipeline, so as soon as you connect your forked repository to CircleCI, builds will automatically run without any extra setup. It also contains an intentional error that will cause the initial build to fail. Instead of digging through CircleCI logs manually, you’ll use your AI assistant to quickly surface and fix the problem.

Once your fork is ready, head to CircleCI and create a new project titled fix-failed-builds. Connect it to your forked repository so that every push automatically triggers a build. After the project is connected, you’re ready to move forward.

Preparing your environment

For your assistant to access CircleCI data, you’ll need to authorize it.

Log in to CircleCI and generate a personal access token under User Settings > Personal API Tokens. This token allows the MCP Server to query your project’s builds and failures securely. Save it somewhere safe — you’ll need it shortly.

Next, configure your IDE to use the MCP Server. During setup, you’ll provide your CircleCI personal API token as part of the MCP Server configuration. This authorizes the server to access build data for your projects, enabling your assistant to retrieve structured information directly.

Once connected, your assistant can pull build logs, analyze failures, and suggest fixes, all without switching tools or digging manually through CI dashboards.

Triggering the build failure

Push the code from your forked repository to GitHub. This will automatically trigger a new build in CircleCI. Because the project includes a known error, the build will fail.

Normally, this would mean opening the CircleCI dashboard, digging through raw logs, and trying to figure out what went wrong, a slow and often frustrating process.

Instead, you’ll stay inside your IDE and let your assistant retrieve and analyze the failure for you.

Retrieving and understanding the failure

Open the chat window in your IDE and prompt your assistant:

fix the issue from CI

The assistant will call the CircleCI MCP Server, retrieve structured data from the failed build, and present the results directly in your editor.

Instead of scrolling through unstructured logs yourself, you’ll get a clean summary. The assistant will analyze the failure and identify the issue: the package.json file defines a build script that tries to run next buildss, but next buildss is not a valid command. The typo (buildss instead of build) is causing the build to break during the install and build steps.

By using MCP Server, the assistant delivers both the raw data and a meaningful interpretation, saving you from the usual cycle of hunting through logs.

Fixing the issue

After diagnosing the problem, your assistant will suggest a fix: update the package.json file to correct the typo: changing next buildss to next build.

You can either accept the assistant’s help and apply the change directly or make the correction manually.

To fix it yourself, open the package.json file, locate the scripts section, and update the build script to:

"build": "next build"

Save your changes, then commit and push the fix:

git add package.json
git commit -m "Fix typo in build script"
git push origin main

Pushing the change will automatically trigger a new build. Whether you used the assistant’s auto-fix or made the change manually, this step should get the pipeline back on track.

Verifying the fix

After you push the corrected code, CircleCI will automatically trigger a new build.

To verify that the fix worked, open your project in the CircleCI dashboard and check the latest pipeline.

If the build passes, that confirms the issue was correctly diagnosed and resolved.

With structured insights from the MCP Server and your AI assistant, you were able to identify the problem and fix it quickly, without losing focus or getting bogged down in manual troubleshooting.

This is a faster, cleaner recovery process that fits naturally into how you already work.

Summary

Debugging CI build failures traditionally means breaking your focus: switching from your code to logs, dashboards, and trial-and-error troubleshooting.

By connecting your assistant to your CI pipelines through the CircleCI MCP Server, you remove much of that overhead. Your assistant retrieves structured data when you need it, explains failures clearly, and suggests actionable fixes, keeping you moving forward.

We’re actively building out the CircleCI MCP Server Cookbook to include even more examples you can use to build faster, diagnose smarter, and integrate CI feedback seamlessly into your development process.

Sign up for a free CircleCI account today and install the CircleCI MCP server to start bringing build insights directly into your development workflow.