Provider REST API

17 actions

Connect Claude to CircleCI

Read failed pipelines, workflows, jobs, test results and artifacts, and trigger, rerun or cancel CircleCI workflows. Toolspoke puts 17 of its actions behind one MCP endpoint that Claude, Cursor, and Codex all speak.

Connect View pricing

Connection: Provider REST API
Authentication: Personal API token
Actions exposed: 17
What a call bills: Nothing
Adapter: Maintained by Toolspoke

Connected in three steps

1
Install CircleCI
Open the marketplace in your workspace, add CircleCI to the project your agents work in, and it appears on the gateway immediately.
2
Connect the credential
Authenticate with personal api token. Where to get one, and what it has to be able to reach, is the next section.
3
Point your agent at the gateway
Give your client one address, https://toolspoke.com/mcp. Claude Code takes it as a command, Claude and Claude Desktop add it as a custom connector, and Cursor, Codex and VS Code each read it from a config file of their own.

.mcp.json

{
  "mcpServers": {
    "toolspoke": {
      "type": "http",
      "url": "https://toolspoke.com/mcp"
    }
  }
}

One block covers every tool you have installed. CircleCI shows up in the client as soon as your policy allows it, and so does everything else you install later.

Where the address goes, per client

Claude Code: Run it in your project, then /mcp to sign in
claude mcp add --transport http toolspoke https://toolspoke.com/mcp
Claude and Claude Desktop: Settings, then Connectors, then Add custom connector
https://toolspoke.com/mcp
Cursor: ~/.cursor/mcp.json, or .cursor/mcp.json for one project
{ "mcpServers": { "toolspoke": { "url": "https://toolspoke.com/mcp" } } }
Codex: ~/.codex/config.toml
[mcp_servers.toolspoke] url = "https://toolspoke.com/mcp"
VS Code: .vscode/mcp.json, or the MCP: Add Server command
{ "servers": { "toolspoke": { "type": "http", "url": "https://toolspoke.com/mcp" } } }

What CircleCI asks for

Personal API token. You provide it once, when you install the connector. Toolspoke encrypts it at rest and decrypts it only for the length of a single call, and the gateway attaches it to the outbound request itself, so it is never part of the arguments an agent sends.

Personal API tokenRequired: CircleCI → User Settings → Personal API Tokens → Create New Token. Project API tokens do not work with API v2. The token acts as you, with every permission you have in every organization you belong to.; CCIPAT_…
CircleCI URLOptional: Leave blank for CircleCI cloud. For a self-hosted CircleCI server install, use its origin, e.g. https://circleci.example.com.; https://circleci.com

What Claude can do in CircleCI

17 actions, each one declared and named by the connector rather than discovered at runtime. A workspace policy grants a person all of them, a hand-picked selection, everything on the read side, everything on the write side, or none.

Reads: 13Reads
Writes: 2Writes
Destructive: 2Destructive

Reads

Fetches data and changes nothing.

list_organizations
List the organizations the token's user belongs to, with the slug (e.g. gh/acme) that list_pipelines takes. A CircleCI personal token has no scopes - it either works or it does not - so this call is a complete connection test: if it returns the organization, every read below can reach it.
list_pipelines
List recent pipelines across an organization, newest first. Use it to find the latest pipeline on a branch, then list_pipeline_workflows to see what failed.
list_project_pipelines
List recent pipelines of one project, newest first, optionally on one branch.
get_pipeline
Retrieve one pipeline by id, with its trigger, commit and any configuration errors.
list_pipeline_workflows
List the workflows of one pipeline with their status - failed, success, running, on_hold and so on.
get_workflow
Retrieve one workflow by id, with its status and timing.
list_workflow_jobs
List the jobs in one workflow with their status and job_number. An approval job's id here is the approval_request_id that approve_job takes.
get_job
Retrieve one job by project and job number, with its status, executor, duration and any messages CircleCI attached.
get_job_steps
List one job's steps with each step's status, exit code and output_url. The output_url is a short-lived signed link to that step's log, readable without a token. Look for the step whose status is failed.
list_job_tests
List the test results one job stored with store_test_results, including each failure's message.
list_job_artifacts
List the artifacts one job stored, with each file's path and download URL.
get_flaky_tests
List the tests CircleCI has seen both pass and fail on the same commit in this project - its flaky-test report.
get_workflow_metrics
Summarize each workflow in a project over a reporting window - success rate, run count, duration percentiles and credits used.

Writes

Creates or updates something on the other side.

trigger_pipeline
Start a new pipeline on a branch or tag. A write, not destructive - it adds a pipeline that cancel_workflow can stop - but it runs whatever the configuration runs, deploys included. Works for projects connected through the CircleCI OAuth app (gh/… and bb/… slugs); GitHub App projects need CircleCI's newer pipeline-run endpoint, which this connector does not declare.
rerun_workflow
Rerun a finished workflow - from the failed jobs only, or a chosen set of jobs, or from the start. It starts a new workflow; the old one is kept.

Destructive

Deletes or permanently alters something. Worth granting on purpose.

cancel_workflow
Cancel a running workflow. Destructive because it cannot be undone - running jobs stop part-way, and the work can only be rerun from the start.
approve_job
Approve an on-hold approval job so the workflow continues. Destructive because an approval job is a human gate - often the one in front of a production deploy - and an approval cannot be withdrawn.

What it will not do

Enforced by the gateway rather than left to convention, which is why each of these can be stated flatly.

It cannot call anything else: The 17 actions above are the whole of it. A call to any other name is refused before it reaches CircleCI rather than forwarded on, and connecting your account does not add to the list: it is fixed by the connector, not discovered at run time.
It reaches no further than your credential: Toolspoke holds no access to CircleCI of its own. Every call carries the credential you stored and nothing besides, so whatever that credential cannot reach, this connector cannot reach either.
It never hears from CircleCI: Nothing is pushed to it. There is no webhook, no subscription and no polling, so this connector cannot notice by itself that something changed in CircleCI. An agent has to ask.
It does not smooth over provider limits: Toolspoke does not retry, queue or back off around CircleCI's own rate limits. A call that CircleCI refuses comes back to the agent as a failed call.

Before you connect it

What can Claude do in CircleCI?

17 named actions: 13 that only read, 2 that write and 2 that delete or permanently alter something. They include list_organizations, list_pipelines and list_project_pipelines. Nothing outside that list is reachable: the connector declares each operation by name rather than proxying whatever an agent asks for.

What credentials does the CircleCI connector need?

Personal API token. The connector asks for personal api token, and optionally circleci url. Values are encrypted at rest and attached to the outbound request by the gateway, so they are never part of the arguments an agent sends and never reach the audit log.

Does the CircleCI connector work with Cursor and Codex, or only Claude?

Any client that speaks MCP, and every one of them gets the same 17 actions. There is a single address, https://toolspoke.com/mcp. Claude Code adds it with claude mcp add --transport http, Claude and Claude Desktop take it as a custom connector in settings, Cursor reads it from .cursor/mcp.json, Codex from ~/.codex/config.toml, and VS Code from .vscode/mcp.json. Each of them signs in to the gateway itself, so there is no key to paste.

What does the CircleCI connector not do?

The 17 actions above are the whole of it. A call to any other name is refused before it reaches CircleCI rather than forwarded on, and connecting your account does not add to the list: it is fixed by the connector, not discovered at run time. Toolspoke holds no access to CircleCI of its own. Every call carries the credential you stored and nothing besides, so whatever that credential cannot reach, this connector cannot reach either. Nothing is pushed to it. There is no webhook, no subscription and no polling, so this connector cannot notice by itself that something changed in CircleCI. An agent has to ask. Toolspoke does not retry, queue or back off around CircleCI's own rate limits. A call that CircleCI refuses comes back to the agent as a failed call.

Can I limit which actions an agent can call?

Yes, in two places. The project switches CircleCI's actions on and off one at a time, for everyone in the project at once, and the screen groups them by read, write and destructive so turning off everything that deletes is one click. An individual agent key can then be narrowed further, to particular toolkits in a project and to particular actions in a toolkit. Whatever it was granted, a key never reaches a project its owner cannot.

What gets recorded when an agent calls CircleCI?

Every attempt, with the agent that made it and the person that agent belongs to, the full request payload, the response payload, the status, the duration, and what the call cost in sandbox time and model tokens. Values whose key names a secret are masked out before the record is shown to anyone. An operation the connector marks as not retained never has its response body written at all, so the gateway keeps no second copy of what was read.

More developer tools connectors

Browse all of them