Title: CircleCI MCP overview
URL Source: https://circleci.com/docs/guides/toolkit/circleci-mcp-overview/
Markdown Content:
We use cookies and similar tracking technologies, including browser fingerprinting, to make your interactions with our website more meaningful. They help us better understand how our websites are used, so we can tailor content for you. For more information, read thePrivacy Policy. To change your cookie settings and preferences, see theCookie Consent Manager.
Customize Settings[Allow all cookies](javascript: void(0);)
×
Cookie Consent Manager
Cookies are small text files that can be used by websites to make a user’s experience more efficient.
The law states that we can store cookies on your device if they are strictly necessary for the operation of this site. For all other types of cookies we need your permission.We also use browser fingerprinting and similar tracking technologies to identify visitors to our site. For these technologies, we also need your permission.
Privacy Policy
Note: 'Persistent' means data stays until you clear browser storage.
Strictly Necessary Cookies
Always Active - [x]
These cookies enable you to navigate circleci.com and to use our services and features. These cookies are necessary for the website to function and cannot be switched off in our systems. View strictly necessary cookies
Preference Cookies
These cookies enable us to provide enhanced functionality and personalization for our website. They may be set by us or by third party providers whose services we have added to our pages. View preference cookies
Statistics Cookies
These cookies collect information about how you use a circleci.com, like which pages you visited and which links you clicked on. View statistics cookies
Targeting Cookies
These cookies and other technologies collect information about the browsing habits associated with your device and are used to make advertising more relevant to you and your interests. This includes browser fingerprinting and similar technologies used by third-party vendors to identify site visitors for sales and marketing purposes. Toggling off this category opts you out of the sale or sharing of your personal information.View targeting cookies
Unclassified Cookies
Always Active
Unclassified cookies are cookies that we are in the process of classifying, together with the providers of individual cookies. View unclassified cookies
[Save Settings](javascript: void(0);)
Documentation structure for LLMs (llms.txt)
cmd+/ Clear
Ask AI
Light
Dark
Auto
Go to Application
[numberOfHits]
[path]
[numberOfHits]
1 2...12
CircleCI MCP overview
23 days ago
Cloud
Markdown
CircleCI’s MCP servers enable you to diagnose build failures, fix issues, and manage CI pipelines through natural language commands without leaving your development environment.
CircleCI previously offered a local MCP server that you installed with npx and configured with a personal API token. That server is deprecated. If your AI assistant still has it configured, remove it before connecting to the hosted MCP server and/or the CircleCI CLI MCP. For example, run claude mcp remove circleci-mcp-server in Claude Code.
Introduction
Model Context Protocol (MCP) is a standardized protocol that lets large language models (LLMs) interact with external systems. CircleCI offers two MCP servers that connect your AI coding assistant directly to your CircleCI runs. One is a hosted server that CircleCI runs for you. The other is built into the CircleCI CLI and runs on your machine. See Hosted server vs. the CircleCI CLI MCP for the difference between the two.
Both MCP servers provide the following benefits:
-
Diagnose build failures without leaving your IDE.
-
Receive structured information your AI assistant can understand.
-
Fix issues faster through natural language requests.
-
Rerun or cancel workflows without switching to the web app.
-
Improve your CI/CD pipeline without context switching.
Hosted server vs. the CircleCI CLI MCP
CircleCI exposes CircleCI to AI assistants through MCP in two ways:
-
The hosted MCP server, available at https://mcp.circleci.com/v1/mcp. CircleCI runs it, so there is nothing to install locally. It is listed in the Claude and Cursor MCP directories. Your AI assistant connects to it over HTTPS, authenticating with OAuth2 or a personal API token. See Connecting to the Hosted CircleCI MCP.
-
The CircleCI CLI MCP, built into the CircleCI CLI. It runs as a local process on your machine, and uses the credentials from circleci auth login or the CIRCLE_TOKEN environment variable. See Connecting to the CircleCI CLI MCP.
The two MCP servers differ in scope as well as in how they run.
The hosted MCP server exposes a focused, curated set of tools for observing and acting on CI runs, including:
The CLI MCP exposes the entire CircleCI CLI as tools including the following:
-
Config authoring. Validate, process, pack, and generate config YAML.
-
Org and project management. Manage contexts, environment variables, and project or org settings.
-
Orb tooling. Create, publish, validate, and diff orb versions.
-
Policy. Push, test, and evaluate Rego policies.
-
Self-hosted runners. Manage runner resource classes and tokens.
-
iOS code signing. Manage certificates and signing configs.
-
Deploy tracking. List and instrument deploys.
-
Docker Layer Cache. Purge DLC.
-
Direct API access. Call the CircleCI API directly through circleci api for anything not covered by a dedicated command.
Choose the hosted MCP server for day-to-day diagnostic work: investigating a failed run, reading logs, or rerunning a workflow. It requires nothing to install or maintain locally, and it is the right choice when your AI assistant only supports remote MCP servers.
Choose the CLI MCP when your assistant also needs to author or validate config, manage orbs, or handle other administrative tasks beyond inspecting runs. It is also the right choice when your organization keeps credentials on the developer’s machine rather than sending them to a remote server.
The two are independent, and connecting one does not disconnect the other.
How the hosted MCP server works
The hosted CircleCI MCP server acts as a bridge between your AI assistant and CircleCI, and works as follows:
-
You ask a question about your CircleCI runs in natural language.
-
Your AI assistant sends a request to the hosted MCP server.
-
The server calls the appropriate CircleCI APIs on your behalf.
-
The server transforms raw API responses into structured data.
-
Your AI assistant receives this data and provides you with useful insights.
The CLI MCP works the same way in principle, but calls the CircleCI CLI’s own commands locally instead of a remote server.
With the hosted CircleCI MCP server, you can perform CircleCI tasks using natural language commands. For example:
-
What failed on my last run on this branch?
-
List my recent CircleCI runs.
-
Rerun the failed jobs in that workflow.
-
Which tests failed in that job?
Supported tools
This section outlines the tools that the hosted CircleCI MCP server currently supports.
You do not call these tools yourself. You ask your AI assistant a question or give it an instruction in plain language. Your assistant then decides which tools to call, in which order, and with which arguments. This table is a reference for what your assistant can do on your behalf. Use it to understand its capabilities, or to troubleshoot why it took a particular action.
Most of these tools chain together. list_runs returns run IDs for get_run. get_run feeds list_workflows. list_workflows feeds list_jobs. list_jobs feeds get_job, get_job_logs, list_artifacts, and list_job_tests.
| Tool | What it does |
|---|
hello | Verifies connectivity to the hosted CircleCI MCP server. |
list_runs | Lists runs for a project, given its slug (gh/org/repo) or UUID, or your own runs across all projects. Filter by branch or run status. |
get_run | Fetches a single run by UUID, returning its phase, outcome, VCS details, and any config errors. |
list_workflows | Lists the workflows belonging to a run, given the run’s UUID. |
get_workflow | Fetches a single workflow by UUID, returning its name, phase, and outcome. |
rerun_workflow | Reruns a workflow, given its UUID. By default every job reruns from the start. Set from_failed to rerun only the failed jobs and everything downstream of them. |
cancel_workflow | Cancels a running workflow, given its UUID. |
list_jobs | Lists the jobs belonging to a workflow, given the workflow’s UUID. |
get_job | Fetches a single job by UUID, returning its phase, outcome, and per-step detail, including each step’s exit code. |
get_job_logs | Fetches the output of a job’s steps, given the job’s UUID. When you do not name a step, the tool reads the failed steps automatically. |
list_artifacts | Lists the files a job persisted, such as test reports, coverage, or build output, given the job’s UUID. |
list_job_tests | Lists a job’s test results, given the job’s UUID. The tool returns failing tests by default; set all to include passing and skipped tests. |
download_usage_data | Exports an organization’s usage data as downloadable CSV files, given an org slug or UUID and a date range of up to 31 days. |
Tools for the CLI MCP mirror the full CircleCI CLI, so there is no equivalent fixed list here. Run circleci help reference for a full dump of every command it can call.
Best practices
-
Ask specific questions. Name the branch, run, workflow, or job you care about, for example "why did the last run on main fail," rather than "check my builds." A specific question lets your assistant pick the right tool without back-and-forth.
-
Let your assistant chain tools. On the hosted MCP server, diagnosing a failure often takes several tool calls in sequence, such as list_runs, then get_run, then list_workflows, and so on down to get_job_logs. Ask for the outcome you want, and let your assistant work out the steps.
-
Review destructive actions before confirming. Rerunning or canceling a workflow changes real CI state, so check what your assistant is about to do first. This matters most on a shared or production-facing project.
-
Match the server to the task. Use the hosted server for diagnosing runs, and switch to the CLI MCP when a task needs config authoring, orb management, or another administrative capability. See Hosted server vs. the CircleCI CLI MCP.
Example workflows
Here are common scenarios where the hosted CircleCI MCP server can help you and your team:
Diagnosing a failed run
Your latest run on a branch fails:
-
You ask your assistant: "Why did my last run fail on this branch?".
-
The hosted MCP server finds the run, confirms it failed, and locates the failed job’s logs.
-
Your assistant identifies the issue and suggests a fix.
-
You apply the fix and continue working.
Rerunning only what failed
A run failed partway through a long workflow:
-
You ask your assistant to rerun the failed jobs in that workflow.
-
The hosted MCP server calls rerun_workflow with from_failed set, reusing the jobs that already succeeded.
-
Your workflow completes without rerunning everything from the start.
Investigating failing tests
Your team wants to understand why a job’s tests failed:
-
You ask your assistant which tests failed in a specific job.
-
The hosted MCP server returns the failing tests along with their failure messages.
-
Your assistant explains the failures and suggests fixes.
Troubleshooting
For general MCP troubleshooting steps, see the Model Context Protocol documentation.
Authentication issues
These steps cover the hosted MCP server. If the CLI MCP fails to connect, check your CLI session instead. See Connecting to the CircleCI CLI MCP.
-
If you connected to the hosted MCP server with OAuth2, re-authenticate from your MCP host. In Claude Code, run /mcp and select Re-authenticate.
-
If you connected to the hosted MCP server with a personal API token, confirm the token is still valid and belongs to a user with access to the project.
-
For setup steps, see Connecting to the Hosted CircleCI MCP.
Not seeing an up-to-date list of tools
After CircleCI releases new tools, restart your MCP host or reconnect the server to load them.
Additional resources
On This Page
Was this page helpful?
Yes No
Suggest an edit to this page
Still need help?
Working with agents
Clear
Ask AI
[numberOfHits]
[path]
[numberOfHits]
1 2...12
Guides
MCP
Chunk
Go to application
On This Page