• IDENTIFY
  • ISOLATE
  • EXAMINE
  • HUMAN

How to debug failed build jobs with your AI

Connect CircleCI to your agent to turn messy build logs into clear answers. It scans your workflows to find the root cause of failures instantly.

Ask AI about this page

Short answer

How can my AI help me debug CircleCI failures?

Your AI pulls the specific job details and error logs from your failed pipelines to identify the broken step. You get a direct explanation of the failure instead of scrolling through thousands of lines of console output.

Where your debugging leads.

The path to a fix.

The AI moves from high-level pipeline status to the specific line of code causing the crash.

IDENTIFY

Locate failed pipelines

The AI scans your recent activity to find exactly which builds didn't pass. You stop hunting for the red icons.

ISOLATE

Find the broken job

It drills down into the specific workflow to see which job in the sequence hit the error. This narrows your focus immediately.

EXAMINE

Read error logs

The agent pulls the detailed job metadata and logs. It reads the stack trace so you don't have to.

HUMAN

Fix the code

The AI hands you the exact error message and the context. You take that info and push the fix to your repo.

The workflow

What your AI does when a build fails.

The agent follows the trail from the pipeline level down to the specific error log.

  1. Find recent failures

    The agent looks at your recent pipeline history to identify which ones ended in an error state.

    list_cci_pipelines

  2. Map the workflow

    Once a failed pipeline is found, the agent looks at the individual workflows within it to see the path taken.

    list_pipeline_workflows

  3. Target the job

    It identifies the specific job that failed within that workflow to stop looking at successful steps.

    list_workflow_jobs

  4. Extract the error

    The agent pulls the full metadata and logs for that specific job to find the stack trace or exit code.

    get_job_details

Try it

Copy these to start.

Use these prompts to kick off a debugging session.

Starting points

Replace the project names or pipeline IDs with your actual CircleCI identifiers.

CircleCI Connector

You're all set. Choose your MCP client and follow the setup instructions.

Connector linkhttps://edge.vinkius.com/vk_preview_RYNFniMxh53CKeYToBM2UNUbXRz4n2cftwtxDiON/mcp

Claude Desktop

Follow the steps below to connect in seconds.

  1. 1In Claude Desktop, open Settings → Connectors.
  2. 2Click “Add custom connector” and paste the connector link above as the remote MCP server URL.
  3. 3Click Add and start a new chat — CircleCI capabilities are ready to use.
Configuration · claude_desktop_config.jsonCopy
{
  "mcpServers": {
    "circleci-mcp": {
      "url": "https://edge.vinkius.com/vk_preview_RYNFniMxh53CKeYToBM2UNUbXRz4n2cftwtxDiON/mcp"
    }
  }
}
Copy into chat04

  • Check my recent CircleCI pipelines for any failed builds in the 'frontend-app' project.

  • Look at the last failed workflow in the 'api-service' pipeline and tell me which job failed.

  • Get the details for the failed job in the 'mobile-ios' workflow and explain the error.

  • Why did the 'deploy-prod' job fail in my most recent pipeline?

  • Claude
  • ChatGPT
  • Cursor
  • VS Code
  • Windsurf
  • Claude Code
  • JetBrains
  • Cline

Start here

Connect CircleCI once, then ask.

Just link your account once. Your credentials stay encrypted, and you can immediately start asking your agent about your builds.

Connect CircleCI to your AI

FAQ

Common questions

  • 01

    Can my AI fix the code for me?

    No. The AI identifies the error and explains the cause, but you must manually apply the fix to your repository.

  • 02

    Can the AI trigger a new build?

    No. This MCP is designed for inspecting and reading pipeline data, not for executing build commands or starting new workflows.

  • 03

    Does the AI see my entire codebase?

    No. It only sees the metadata, workflow steps, and logs provided by the CircleCI API.

  • 04

    Can I use this with any AI client?

    Yes, as long as the client supports the Model Context Protocol (MCP).

  • 05

    Will this delete any of my build history?

    No. The tools only allow the AI to read data. It cannot delete pipelines, jobs, or workflows.

  • More questions about CircleCI? The Connector page answers them. See everything the CircleCI Connector can do

Connect CircleCI to Claude, Cursor, ChatGPT & more