OfficialDev & code hostinglocal stdio / remote HTTP

CircleCI MCP Server

Q: How do I re-authenticate in Claude Code?

For an OAuth2 connection, run /mcp and select Re-authenticate. For a personal API token, check that the token is still valid and belongs to a user with access to the project.

Lets agents list CircleCI runs, read job logs and test results, and rerun or cancel workflows through CircleCI's hosted endpoint.

Install

Claude Code

(then run /mcp, select circleci-mcp-server and choose Authenticate)

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

Claude Desktop and claude.ai

(Settings > Customize > Connectors, find CircleCI in the directory and add it, or choose Add custom connector with the server URL https://mcp.circleci.com/v1/mcp)

Cursor

(add circleci from the Cursor MCP Marketplace, or add to mcp.json)

{
  "mcpServers": {
    "circleci-mcp-server": {
      "url": "https://mcp.circleci.com/v1/mcp"
    }
  }
}

VS Code

(.vscode/mcp.json)

{
  "servers": {
    "circleci-mcp-server": {
      "type": "http",
      "url": "https://mcp.circleci.com/v1/mcp"
    }
  }
}

Windsurf

(mcp_config.json)

{
  "mcpServers": {
    "circleci-mcp-server": {
      "serverUrl": "https://mcp.circleci.com/v1/mcp"
    }
  }
}

Personal API token instead of OAuth2

(for hosts that can’t complete OAuth2, or headless use). In Claude Code:

$ claude mcp add --transport http circleci-mcp-server https://mcp.circleci.com/v1/mcp \
  --header "Authorization: Bearer <your-circleci-token>"

Other clients send the same Authorization: Bearer <your-circleci-token> header in their headers configuration.

CircleCI CLI MCP

(local; needs the CircleCI CLI and circleci auth login), from Connecting to the CircleCI CLI MCP:

circleci mcp claude enable    # Claude Desktop
circleci mcp cursor enable    # Cursor
circleci mcp vscode enable    # VS Code

The CLI’s README adds a step for Claude Code after enabling it in Claude Desktop:

circleci mcp claude enable # Enable in Claude desktop
claude mcp add-from-claude-desktop -s user # Add with current user scope

Commands and configuration as given in CircleCI’s connection guide. OAuth2 is CircleCI’s recommended sign-in; most clients prompt for it on first connect.

The CircleCI MCP server is CircleCI’s hosted endpoint that lets coding agents inspect, rerun and cancel CI runs.

The CircleCI MCP server runs at https://mcp.circleci.com/v1/mcp. CircleCI hosts it, so there is nothing to install locally, and an agent such as Claude Code, Cursor or Copilot in VS Code connects over HTTPS with OAuth2 or a personal API token (CircleCI MCP overview). The connection guide lists it for the Free, Performance and Scale cloud plans (Connecting to the CircleCI MCP server).

Its tools cover CI runs: list_runs, get_run, list_workflows, get_workflow, rerun_workflow (with from_failed to rerun only failed jobs), cancel_workflow, list_jobs, get_job, get_job_logs, list_artifacts, list_job_tests, download_usage_data and a hello connectivity check (CircleCI MCP overview). CircleCI’s advice: “Review destructive actions before confirming”, because rerunning or canceling a workflow changes real CI state.

CircleCI also builds an MCP server into the CircleCI CLI. It runs locally with your circleci auth login session or the CIRCLE_TOKEN variable and exposes the whole CLI as tools, including config validation, contexts, environment variables, orbs, policies and runners (CircleCI MCP overview). The CLI’s source is public in CircleCI-Public/circleci-cli under the MIT License.

The older npm package @circleci/mcp-server-circleci is deprecated; CircleCI says to remove it before connecting to the hosted server or the CLI MCP, for example with claude mcp remove circleci-mcp-server in Claude Code (Connecting to the CircleCI MCP server).

Questions

Is the CircleCI MCP server official?

Yes. CircleCI runs the hosted server at mcp.circleci.com and documents it on circleci.com/docs, along with the MCP server built into the CircleCI CLI.

Should I still use @circleci/mcp-server-circleci?

No. CircleCI deprecated that local npm server and says to remove it before connecting to the hosted server or the CLI MCP.

What is the difference between the hosted server and the CLI MCP?

The hosted server has a fixed set of tools for inspecting and acting on CI runs. The CLI MCP runs on your machine and exposes the whole CircleCI CLI, including config validation, orbs, contexts and runners.

How do I re-authenticate in Claude Code?

For an OAuth2 connection, run /mcp and select Re-authenticate. For a personal API token, check that the token is still valid and belongs to a user with access to the project.

Sources

Checked October 27, 2026.

Dev & code hosting

View all