CircleCI MCP server: deprecated, and what replaced it

Which of CircleCI's two MCP servers to connect, what an agent can ask each of them, and why thirteen CircleCI tools cost more context than GitHub's forty-four.

Last verified 1 September 2026 · from CircleCI's repository, its documentation and the server's own tools/list response

This page is one of 90 in a directory of monitoring and developer tools. Each page checks what an AI coding agent can get out of the tool through its MCP server, the connector that lets the agent query the tool directly.

What is the CircleCI MCP server?

It is CircleCI's server for the Model Context Protocol. The agent gains tools for reading build failures, finding flaky tests, and checking pipeline status.

There are two surfaces and they are not equal. The npm package @circleci/mcp-server-circleci runs on your machine and holds a CircleCI personal API token. The hosted server at mcp.circleci.com is CircleCI's current recommendation and its direct replacement.

The deprecation is explicit rather than implied. The README states the repository will be archived, that existing versions remain installable, and that running an unmaintained server holding a personal API token is not recommended.

CircleCI covers release broadly, reaches part of the way into code review through test results, and reaches nothing in production observability, agent observability or cost.

In practice, CircleCI answers questions about what the pipeline did and why it failed, and nothing about the system the pipeline deployed to. An agent connected here can find the flaky test behind an intermittent failure and re-run the workflow. It cannot tell you that the deploy made production slower. Pair this connector with an observability one.

What can an AI agent do with CircleCI?

What connecting costs before the first question

A context window is the amount of text a model can hold at once, and connecting uses some of it before the agent asks anything. Every tool the server registers sends its name, description and input schema to the model when the session starts. The tool list is charged whether or not a single tool is called.

Thirteen tools here cost more than GitHub's default forty-four. The cause is description length. CircleCI's tool descriptions average 2,560 characters; GitHub's average 124, about twenty times shorter.

Long descriptions are not automatically wrong, and CircleCI's carry worked examples and parameter guidance that help an agent choose correctly. The cost is real either way, and it is paid on every session whether or not a tool is called.

Encodings: GPT-5.6, GPT-5.5 o200k_base; GPT-4, GPT-3.5 cl100k_base; Claude Haiku 4.5 to Opus 5 count_tokens. Counted 19 August 2026 from tools/list on the published @circleci/mcp-server-circleci package, run locally with a placeholder token.

Registration is static, so no CircleCI account was involved. Figures cover name, description and input schema. The two models in column one share the o200k_base encoding, so they get one count. The spread is formatting, about 10%, narrow because prose rather than schemas carries the payload. Reasoning tokens are output, spent per request. The tool list is input, charged once at connection.

The Claude figures are measured rather than encoded. Anthropic publishes no local tokenizer, so the definitions were sent to the API's count_tokens endpoint and a no-tools baseline subtracted. The range covers two tokenizer generations rather than two serializations. Haiku 4.5 and Opus 4.6 sit at the low end, Opus 5 and Sonnet 5 at the high end. The gap between them is about a third.

CircleCI MCP server limits: where answers come back incomplete

CircleCI documents the limits below. The first is about the package's lifecycle, not an incomplete answer. The other two are about answers that come back incomplete.

How to configure CircleCI MCP for agents

1. 1

   Migrate before you configure

   CircleCI states this package is deprecated and the repository will be archived, and names the hosted server at mcp.circleci.com as the replacement.

2. 2

   If you must run it, treat the token as the risk

   CircleCI's own warning is that running an unmaintained server holding a personal API token is not recommended.

3. 3

   Keep the three pipeline triggers off the allowlist

   run_pipeline, rerun_workflow and run_rollback_pipeline all reach production, and the server has no read-only mode.

4. 4

   Budget the context

   Thirteen tools cost about 11,755 tokens, roughly 6% of a 200,000-token window, because the descriptions are long rather than because the tools are many.

Paste this into your agent’s instructions

CircleCI's quiet failure is an empty test result: find_flaky_tests returns nothing both when there are no flaky tests and when the pipeline never uploaded results. The block makes the agent say which it saw.

When you answer using CircleCI MCP tools, state:
- The project and branch each result came from.
- Whether test results were present. find_flaky_tests needs
  store_test_results in the pipeline, so an empty answer may
  mean no results were uploaded rather than no flaky tests.
- Whether you triggered anything. run_pipeline, rerun_workflow
  and run_rollback_pipeline all reach production.
Never state that data does not exist. State that none was
returned under the constraints above.
Write your answer in ASD-STE100 Simplified Technical
English. Use short sentences with one idea in each.

Do you need the MCP server at all?

Not for the common cases. The CircleCI CLI and the v2 REST API cover pipelines, workflows and jobs, and CircleCI now also offers a CLI-based MCP as one of the two supported routes.

The server adds flaky-test analysis and the usage tools, which have no convenient CLI shape. Its descriptions are also detailed enough that an agent picks the right call unprompted.

The deprecation changes the calculation. Between an unmaintained local package and a maintained hosted endpoint, the hosted one is the better default even where the CLI would also do.

Use the hosted server. Reach for the CLI when the agent already has the repository and the question is about one pipeline.

CircleCI MCP server setup

The hosted server at mcp.circleci.com is CircleCI's recommendation and needs no install. The deprecated npm package runs with npx and needs a CircleCI personal API token in CIRCLECI_TOKEN.

Set CIRCLECI_BASE_URL as well if your organization is on a self-hosted or non-default CircleCI domain.

claude mcp add --transport http circleci https://mcp.circleci.com/v1/mcp

claude mcp add-json "circleci" '{"command":"npx",
  "args":["-y","@circleci/mcp-server-circleci"],
  "env":{"CIRCLECI_TOKEN":"<your-token>"}}'

{"mcpServers":{"circleci":{"command":"npx",
  "args":["-y","@circleci/mcp-server-circleci"],
  "env":{"CIRCLECI_TOKEN":"<your-token>"}}}}

[mcp_servers.circleci]
command = "npx"
args = ["-y", "@circleci/mcp-server-circleci"]
env = { CIRCLECI_TOKEN = "<your-token>" }

Every other client

Each block below is the configuration for one client, with the file path and the key that client expects.

{"mcpServers":{"circleci":{"command":"npx",
  "args":["-y","@circleci/mcp-server-circleci"],
  "env":{"CIRCLECI_TOKEN":"<your-token>"}}}}

{"mcpServers":{"circleci":{"command":"npx",
  "args":["-y","@circleci/mcp-server-circleci"],
  "env":{"CIRCLECI_TOKEN":"<your-token>"}}}}

{"servers":{"circleci":{"command":"npx",
  "args":["-y","@circleci/mcp-server-circleci"],
  "env":{"CIRCLECI_TOKEN":"<your-token>"}}}}

{"mcpServers":{"circleci":{"command":"npx",
  "args":["-y","@circleci/mcp-server-circleci"],
  "env":{"CIRCLECI_TOKEN":"<your-token>"}}}}

CIRCLECI_TOKEN=<your-token> \
CIRCLECI_BASE_URL=https://circleci.example.com \
npx -y @circleci/mcp-server-circleci

Read-only access, permissions and security

• The token is the stated risk

  CircleCI advises against running an unmaintained server that holds a CircleCI personal API token, which is what this package is.

• No read-only mode

  Three of CircleCI's thirteen tools trigger pipelines, including a rollback that reaches production. The MCP client allowlist is the remaining control.

• Migrate the remote transport first

  CircleCI names the self-managed remote transport as the first thing to move. That is the setup where you run the server yourself as a network-facing service, and it brokers your organization's token.

• The token carries your access

  A personal API token reaches every project you follow, so scope it to a user with the access you would give an agent.

Troubleshooting

No flaky tests found on a project that has them

find_flaky_tests reads CircleCI's test metadata, which exists only if the pipeline uploads it with store_test_results. Confirm that step before trusting the result.

401 on connect

CIRCLECI_TOKEN is missing or not a personal API token. For a self-hosted domain, set CIRCLECI_BASE_URL as well.

A pipeline ran that you did not trigger

run_pipeline, rerun_workflow and run_rollback_pipeline are write tools with no server-side flag. Remove them from your client's allowlist.

The package still installs but feels stale

It is deprecated and the repository is to be archived. Existing versions remain installable; the hosted server at mcp.circleci.com is the replacement.

CircleCI MCP server: Reference

What engineers report

CircleCI's MCP server has 91 stars and was last pushed on 6 August 2026. Public discussion of it is thin, so this section reports counts rather than quotes.

Repository facts retrieved from the GitHub API on 19 August 2026. Tool counts and description lengths come from the server's own tools/list response, not from the README.

Should you connect an agent to CircleCI?

Yes, though it is no longer actively maintained. Best for CircleCI teams connecting the hosted server, with pipeline-triggering tools left off the allowlist.

Strongest fit

Teams on CircleCI who want an agent to explain build failures and find flaky tests without leaving the editor.

Main advantage

Flaky-test detection and usage analysis, which have no convenient CLI equivalent.

Main weakness

The npm package is deprecated, and 13 tools cost more context than another vendor's default 44.

Operational risk

Pipeline triggers and rollbacks are write tools with no server-side read-only flag.

Frequently asked questions