hello
Verifies connectivity to the hosted CircleCI MCP server.
LABSCO SUMMARY
The useful fact here is which one is dead: the npm package, not this.
Search results and older blog posts still point at @circleci/mcp-server-circleci, and anyone following those is installing something the vendor has retired. Hosted is now the supported path. Check CircleCI's guide for the specifics before wiring it in.
What it is
CircleCI's own hosted endpoint. It supersedes @circleci/mcp-server-circleci, the npm package they previously published and have now deprecated.
What you get
One address for every account, https://mcp.circleci.com/v1/mcp — you sign in with OAuth2 or send a personal API token. Its 13 tools cover pipeline runs, workflows (including rerun and cancel), jobs and their logs, artifacts, test results and usage data.
Requirements
Follow CircleCI's setup guide. If you are running the old npm package, this is the migration target.
Setup effort
Paste a URL, then authorize — add the endpoint to your client, then approve the OAuth consent screen
USE CASES
01
Migrating off the deprecated package
Switch from the npm server to CircleCI's hosted endpoint, which is the supported route now.
02
Reaching CI from an assistant
Connect through CircleCI's own setup rather than a community wrapper.
13 tools
Listed in project docs. Your client may show a different list.
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.
BEFORE YOU INSTALL
What to know first
Tools you get
13 tools named in the project's documentation.
Requires
- A CircleCI account with access to the projects you want to inspect
- An AI coding assistant or MCP host that supports remote MCP servers over streamable HTTP
Where it runs
All 5 documented clients connect to a hosted endpoint.
INSTALLATION
Connect your client
Add the endpoint to your client, then approve the OAuth consent screen.
Server setup
Claude.ai
ENDPOINT URL
https://mcp.circleci.com/v1/mcpRequirements
- OAuth2 (recommended): sign in with your CircleCI account when the client prompts. Fallback for hosts that cannot do OAuth2: a CircleCI personal API token sent as `Authorization: Bearer <YOUR_TOKEN>`
MCP Clients
Claude Code
CLAUDE CODE · TERMINAL
claude mcp add --transport http circleci-mcp-server https://mcp.circleci.com/v1/mcpCursor
CURSOR · JSON
{
"mcpServers": {
"circleci-mcp-server": {
"url": "https://mcp.circleci.com/v1/mcp"
}
}
}VS Code
VS CODE · JSON
{
"servers": {
"circleci-mcp-server": {
"type": "http",
"url": "https://mcp.circleci.com/v1/mcp"
}
}
}Windsurf
WINDSURF · JSON
{
"mcpServers": {
"circleci-mcp-server": {
"serverUrl": "https://mcp.circleci.com/v1/mcp"
}
}
}
