Hosted MCP server now available

CircleCI now hosts an MCP server at https://mcp.circleci.com/v1/mcp. Point your AI assistant at that URL, sign in with OAuth2, and it can read and act on your CI. There is nothing to install and nothing to keep up to date — every client hits the same endpoint, and new tools appear the moment we ship them.

Every tool runs as the authenticated user and sees exactly what that user can see.

What it exposes

24 tools, grouped around the questions people actually bring to CI:

• Find the failure – list_runs is the entry point, and each id feeds the next level: get_run, list_run_workflows, get_workflow, list_workflow_jobs, get_job. With no project named, mine=true lists your own runs across every project, which is the short path to “what of mine is broken”.
• Explain the failure – get_job names the failed step and its exit code. list_job_tests returns only the failing tests by default. get_job_logs reads the failed steps automatically when you do not name one. get_job_resource_usage reports what the executor actually used, against the limits of its resource class — memory near 100% is what an OOM kill looks like. list_job_artifacts gives the files the job kept, with download URLs.
• Fix and move on – rerun_workflow (with from_failed=true to reuse the jobs that passed) and cancel_workflow.
• Work on config before you push – validate_config compiles a config and reports its errors, expanding orbs, parameters, and matrix jobs. get_orb shows whether a pin is stale and get_orb_source shows how to call an orb correctly. None of these need a project; they work on YAML you are holding.
• Track what shipped – list_deployments answers “what is live” and “when did X ship” from a project alone, with list_deploy_components, list_deploy_environments, and list_deploy_component_versions underneath it, plus rollback_deploy_component to go back to a known-good version.
• Account data – get_me and download_usage_data.

What we tuned for

An agent’s constraints are not a human’s, so the tools are built around them:

• Logs cost tokens, so we do not send you raw ones. Step output is replayed through a terminal model rather than run through an ANSI stripper — tools like Docker redraw progress with carriage returns, and stripping the escapes alone leaves a pile of stale, half-drawn lines. Redraws collapse to their final state. tail_lines then keeps only the end of each step, where errors surface, defaulting to 500 and capped at 5000.
• Reading a large log should not cost a large amount of memory. The tail is taken in a bounded ring buffer as the stream arrives, so peak memory is a function of the bounds, not of how big the log was.
• Knowing which tool to reach for matters more than having the tool. Five tools take a job id and answer different questions, so the server ships instructions describing the id chain, which tool answers which question, and what each one costs — enough for a model to try list_job_tests before reaching for logs.
• Results are typed. Every tool declares an output schema, so answers come back as structured content rather than prose to be re-parsed.
• Errors say what was wrong — the wrong kind of id, a missing project, an execution index out of range — so a model can correct the call instead of retrying it unchanged.

Connect it

The server is listed in both the Claude and Cursor MCP directories, so in those clients you can add it without editing a config file. Otherwise, add https://mcp.circleci.com/v1/mcp as a remote MCP server: claude.ai and Claude Desktop take it under Settings → Connectors → Add custom connector, and Claude Code, Cursor, VS Code, and Windsurf are covered in the connection guide below.

CircleCI MCP overview →

Connecting to the CircleCI MCP server →