A CircleCI MCP that starts builds, reads them, and reports back
Connect one personal API token and pipelines, workflows, jobs, artifacts, test metadata, environment variables, contexts, checkout keys, schedules, webhooks, and Insights metrics become workflow steps. An AI agent can triage a red build with the failing test names and the artifact links already in hand, a deploy can wait behind an approval task, and the result lands next to your tasks and databases instead of in a terminal.
What the CircleCI MCP connector does
The CircleCI connector for Mattering Automations is 55 nodes on the CircleCI API v2: list and read pipelines by id or by the number in the web app, fetch the source and compiled config a run actually used, walk a pipeline down to its workflows and jobs, pull job artifacts and per-test metadata, start runs through either trigger endpoint, cancel and rerun work in flight, manage project environment variables, contexts and context variables, checkout keys, scheduled pipelines and outbound webhooks, and read the whole Insights family from project and organization summaries to job timeseries and flaky tests. One personal API token authenticates all of it: CircleCI accepts either a Bearer authorization header, which its API developer's guide recommends, or the CircleCI-specific Circle-Token header that existing integrations widely use, and this connector sends Circle-Token, reaching the same v2 endpoints.
Every node speaks MCP, the open protocol for connecting AI assistants to tools, so Claude, ChatGPT, and any MCP-capable assistant can use them, alongside Matter, the AI assistant built into the platform. An agent can notice a workflow finished failing, list its jobs, read the test records the failing job uploaded, check whether that test is already on the project's flaky list, and open a task with the artifact links attached, without anyone opening the CircleCI web app.
The platform angle is what makes this more than an API wrapper. CircleCI nodes sit on the same canvas as every other connector: a build failure can open a Mattering Productivity task, a nightly sweep can write workflow metrics into a Mattering database, a deploy trigger can sit behind a human approval step, and the token lives once with the rest of your connector secrets rather than in a shell history or a script's environment. The nodes are shared surface, so the automation you build and the agent you ask are driving exactly the same operations.
The safety modeling is stated on the nodes rather than buried. Of the 55 nodes, 36 read and 19 act, and six carry a destructive flag: CircleCI: Delete Env Var, CircleCI: Delete Context Env Var, CircleCI: Delete Context, CircleCI: Delete Checkout Key, CircleCI: Delete Schedule, and CircleCI: Delete Webhook. Three more nodes deserve the same care for a different reason: CircleCI: Trigger Pipeline, CircleCI: Trigger Pipeline Run, and CircleCI: Rerun Workflow start real CI runs that queue compute against the organization's plan usage and execute whatever the config says, including deploy jobs, so rerunning a release workflow deploys again. Nothing they start is unstoppable: CircleCI: Cancel Workflow and CircleCI: Cancel Job end a run in flight, and each node description says so.
One connection, three surfaces
- Visual automations. Drag CircleCI nodes onto the canvas and wire them to triggers, conditions, and other apps.
- AI agents, yours or ours. These nodes speak MCP, the open protocol, so Claude, ChatGPT, and any MCP-capable assistant can use them, and Matter, the agent built into the platform, uses them natively.
- The whole platform. Combine with native tasks, projects, and other connectors, no middleware in between.
Every CircleCI node, ready to drop on the canvas
55 nodes, generated from the connector itself so this list always matches what ships. Expand a category to browse.
Read and query nodes 36
CircleCI: Get Checkout Key
Fetch one checkout key by fingerprint: its public key, type, preferred flag and creation time. Both md5 and sha256 fingerprints work; the runner URL-encodes whichever is given.
CircleCI: Get Context
Fetch a context by id: its name and creation time. Values are never included here; use List Context Env Vars for the variable names inside it.
CircleCI: Get Current User
Return the user the stored personal API token belongs to: id, login and display name. Takes no parameters and works for every valid token, so this is the credential health check to run first in any CircleCI automation. An invalid token gets 401 with a plain message and no secret is echoed back.
CircleCI: Get Env Var
Fetch one project environment variable by name. The value is MASKED (four x characters plus the last four characters), so this answers whether a variable exists and roughly which value is set, never what the secret is.
CircleCI: Get Flaky Tests
List a project's flaky tests: tests that passed and failed on the same commit. Each row names the test, its class and file, the job and workflow it flaked in, the pipeline and job numbers, how many times it has flaked and how much time that wasted; the response also carries a count of unique flaky tests. Flaky tests are branch agnostic, and a test drops off this list after two weeks without a new flake.
CircleCI: Get Job
Fetch a job's metadata by its UUID: name, job number, type, status, start and stop times, and the project, pipeline and workflow ids it belongs to. Use the job number it returns with the artifact and test metadata nodes.
CircleCI: Get Job Artifacts
List the artifacts a job stored, each with its path inside the artifact tree, the parallel node index that produced it, and a download URL. Those URLs are what a following HTTP node fetches, using the same CircleCI token. Only jobs with a store_artifacts step return anything.
CircleCI: Get Job Details
Fetch the full detail record for a job by project slug and job number: web URL, project and organization, executor type and resource class, parallelism and per-run statuses, contexts used, queued, started and stopped times and the duration in milliseconds. This is the richest job read and the one to use for run-time and resource reporting.
CircleCI: Get Job Test Metadata
Return the per-test records a job uploaded through store_test_results: test name, class name, source file, result, run time and any failure message. Only jobs with a store_test_results step return rows, and only in the formats CircleCI parses.
CircleCI: Get Job Timeseries
Timeseries metrics for every job in a workflow, bucketed hourly or daily: each row is one job in one interval with its run counts, throughput, duration statistics and indicative credits, plus the interval timestamp and the first and last execution times inside it. Retention differs by granularity: hourly buckets are kept for 48 hours, daily buckets for 90 days, and one request can span at most 90 days. Poll this sparingly; frequent polling is a documented way to get throttled.
CircleCI: Get Org Summary Metrics
Organization level summary metrics and trends: total runs, total duration, success rate, throughput and indicative credits for the whole org and for each project in it, plus the list of project names. Note that all_projects returns project NAMES, which are not project slugs and cannot be used directly in project-scoped nodes.
CircleCI: Get Pipeline
Fetch one pipeline by its UUID: number, state, project slug, trigger and actor, VCS branch or tag and revision, plus any config errors or warnings CircleCI recorded when it compiled the pipeline. Errors here are why a pipeline can exist and still run nothing.
CircleCI: Get Pipeline By Number
Fetch one pipeline by the number shown in the CircleCI web app and in commit statuses, without needing its UUID. Same payload as Get Pipeline.
CircleCI: Get Pipeline Config
Return the configuration a pipeline actually ran: source is the .circleci/config.yml as committed, compiled is the fully expanded config after orbs, parameters and matrix expansion. Setup workflows additionally fill setup-config and compiled-setup-config. The compiled text is the one to diff when a run behaves differently from what the file suggests.
CircleCI: Get Project
Fetch a project by slug: its name, project id (UUID), organization name, slug and id, and VCS info including the repository URL and default branch. The project id returned here is what the webhook nodes need as their scope id and what the pipeline definition listing needs as its project id.
CircleCI: Get Project Summary Metrics
Project level summary metrics and trends across every workflow and branch: total runs, total duration, success rate, throughput and indicative credits, broken out per workflow and per workflow/branch pair, plus the full lists of branch names and workflow names the project has. Runs going back at most 90 days are aggregated and trends cover at most 30 days. The all_workflows list this returns is what the workflow name pickers elsewhere in this connector read.
CircleCI: Get Schedule
Fetch one scheduled pipeline by id: name, description, timetable, parameters, attribution actor and timestamps. Available only for schedules on GitHub OAuth and Bitbucket Cloud pipeline definitions.
CircleCI: Get Webhook
Fetch one outbound webhook by id: name, URL, events, TLS verification flag, scope and timestamps. The signing secret is masked.
CircleCI: Get Workflow
Fetch one workflow by id: name, status, the pipeline it belongs to and that pipeline's number, the project slug, who started it, and its created and stopped times. The status field is what a polling automation watches to decide a run finished.
CircleCI: Get Workflow Job Metrics
Summary metrics for each JOB inside one workflow over the chosen reporting window: run counts, success rate, duration statistics, throughput and indicative credits, each row carrying the window it covers. Filter to one job by name or by a substring of it. This is where a slow or flaky step shows up against the rest of the workflow.
CircleCI: Get Workflow Metrics
Summary metrics for each of a project's workflows over the chosen reporting window: total, successful and failed runs, success rate, mean time to recovery, throughput, duration min/mean/median/p95/max and indicative credits, each row carrying the window it was computed over. Scoped to the default branch unless a branch is given or all branches is set. Metrics refresh daily, so the last 24 hours may be missing.
CircleCI: Get Workflow Runs
List recent runs of one workflow, newest first: run id, branch, status, duration in seconds, created and stopped times, indicative credits used and whether the run was an approval. Runs going back at most 90 days are available, and one request can cover at most 90 days between the start and end dates. This is the per-run detail behind the workflow metrics.
CircleCI: Get Workflow Summary
Metrics and trends for ONE workflow: run counts, success rate, mean time to recovery, throughput, duration statistics and indicative credits, alongside trend values for each. Use this for a single workflow health card; use Get Workflow Metrics when you want every workflow at once.
CircleCI: List Checkout Keys
List the SSH checkout keys a project uses to clone code: public key, type (deploy-key or github-user-key), fingerprint, whether it is the preferred key, and when it was created. Only public material is returned.
CircleCI: List Collaborations
List the organizations the token's user belongs to or can collaborate on, across VCS providers, each with its org slug (gh/example-org), name, id and VCS type. This is the org discovery call: it returns ORGANIZATIONS, not projects, so it feeds org-scoped nodes such as Get Org Summary Metrics and the context listing. The response is a bare JSON array, so output paths start at data[].
CircleCI: List Context Env Vars
List the environment variables in a context: variable name, context id, created and updated times. Values are NOT returned at all, not even masked, so this is a safe audit read of what a context provides.
CircleCI: List Contexts
List an organization's contexts with their ids, names and creation times. Identify the owner by slug (gh/example-org) or by organization id; pass one, not both. Context ids from here drive every context environment variable node.
CircleCI: List Env Vars
List a project's environment variables. Values come back MASKED, exactly as the web app shows them: four x characters plus the last four characters of the real value. Use this to audit which names exist, never to read a secret back out.
CircleCI: List Insights Branches
List the branches Insights currently holds data for, optionally narrowed to the branches one workflow ran on. At most 5,000 branches are returned. This is the branch discovery call the branch pickers on the other insights nodes read from.
CircleCI: List My Pipelines
List only the pipelines in this project that the token's own user triggered. Same item shape as List Project Pipelines. Useful for a personal automation that should react to its own runs and ignore everyone else's.
CircleCI: List Pipeline Definitions
List a project's pipeline definitions: the named config entry points shown in Project Settings > Pipelines, each with its id, name, the repository and file path its config is read from, and the repository its checkout step clones. The definition id is what Trigger Pipeline Run requires.
CircleCI: List Pipeline Workflows
List the workflows a pipeline started, each with its id, name, status (success, running, failing, on_hold, canceled and the rest), who started or canceled it, and its created and stopped timestamps. Workflow ids from here drive the cancel, rerun and job listing nodes.
CircleCI: List Project Pipelines
List a project's pipelines newest first, optionally limited to one branch. Each item carries the pipeline id and number, its state, the trigger that started it (api, webhook, explicit or scheduled_pipeline) and the VCS revision and commit. This is the entry point for every pipeline, workflow and job drill-down in this connector.
CircleCI: List Schedules
List a project's scheduled pipeline triggers with their id, name, description, timetable, pipeline parameters and the actor runs are attributed to. CircleCI documents this as covering schedules on GitHub OAuth and Bitbucket Cloud pipeline definitions only; GitHub App schedules live under pipeline definition triggers instead.
CircleCI: List Webhooks
List the outbound webhooks registered on a project: id, name, target URL, events, TLS verification flag and scope. The signing secret comes back masked. Webhooks are project-scoped: pass the project id as the scope id and project as the scope type, which is the only type CircleCI currently supports.
CircleCI: List Workflow Jobs
List the jobs in a workflow with their id, name, job number, status, type (build or approval), start and stop times and the jobs they depend on. Approval jobs carry an approval request id and no job number, since they gate rather than run. Job ids and numbers from here drive the job detail, artifact, test and cancel nodes.
Action nodes 19
CircleCI: Cancel Job
Cancel one running job by project slug and job number. The job ends in the canceled state and its workflow continues or fails according to the config; the job record and its logs stay. Nothing is deleted and the work can be redone with Rerun Workflow. Side effects a job already completed are not undone.
CircleCI: Cancel Workflow
Cancel a running workflow. Jobs still running stop, queued jobs never start, and the workflow ends in the canceled state; the record and its logs stay. Nothing is deleted and the workflow can be started again with Rerun Workflow. Work that a deploy job already completed is not undone by cancelling.
CircleCI: Create Checkout Key
Create a checkout key for the project and return its public half and fingerprint. A deploy-key reaches only this repository; a user-key acts as the authorizing user and reaches every repository that user can read, so prefer deploy-key unless a job must clone a second private repo. CircleCI documents this call as usable only with a personal API token, and not for GitLab or GitHub App projects. Adding a key does not remove the existing one.
CircleCI: Create Context
Create an empty context in an organization and return its id. A context is a named bundle of environment variables that jobs opt into from the config file. Identify the owner by slug or by organization id, not both. Creating a context changes nothing that already runs; jobs only see it once the config names it.
CircleCI: Create Env Var
Create a project environment variable, or overwrite the value of one that already exists under the same name. Every job in the project can read it, so treat it as a project wide secret. The response echoes the masked value only. Overwriting replaces a value that cannot be read back first, so check List Env Vars before reusing a name.
CircleCI: Create Schedule
Create a scheduled pipeline. From then on CircleCI starts real runs on the timetable, which draws on the organization's plan usage on every tick, so keep the timetable as sparse as the job needs. Available only on GitHub OAuth and Bitbucket Cloud organizations. Deleting the schedule stops it.
CircleCI: Create Webhook
Register an outbound webhook on a project. CircleCI then POSTs to the URL whenever the chosen events fire (workflow-completed, job-completed), signing each request with the signing secret so the receiver can verify it. Creating one changes no existing behaviour and Delete Webhook removes it. Turning off TLS verification means CircleCI stops checking the receiver's certificate.
CircleCI: Delete Checkout Key
DESTRUCTIVE: delete a checkout key. If it is the key the project clones with, every following build fails at the checkout step until a new key is created and registered with the VCS. The private half is gone and cannot be restored; recovery means creating a new key, not undoing this.
CircleCI: Delete Context
DESTRUCTIVE: delete a context. CircleCI documents that this also deletes EVERY environment variable inside it, and those values are unrecoverable because the API only ever returns variable names. Any job whose config names this context fails on its next run.
CircleCI: Delete Context Env Var
DESTRUCTIVE: remove an environment variable from a context. The value is unrecoverable, because the API never returns context variable values and nothing can copy it first. Every job that uses this context loses the variable on its next run.
CircleCI: Delete Env Var
DESTRUCTIVE: permanently delete a project environment variable. The value is unrecoverable, because CircleCI only ever returns it masked and no automation can take a copy first. Jobs that read the name start failing on their next run. Recreating it means having the original secret to hand.
CircleCI: Delete Schedule
DESTRUCTIVE: delete a scheduled pipeline. The trigger stops immediately and its timetable, parameters and attribution are gone; recreating it means re-entering all of them. Runs the schedule already started are not affected.
CircleCI: Delete Webhook
DESTRUCTIVE: delete an outbound webhook. Deliveries stop at once and the signing secret is gone, so recreating the webhook means issuing a new secret and updating the receiver. Anything downstream that depended on these deliveries goes quiet without erroring.
CircleCI: Rerun Workflow
Rerun a workflow and get the new workflow id back. This STARTS A REAL CI RUN: it queues compute that draws on the organization's CircleCI plan usage and re-executes the workflow's jobs, including any deploy jobs, so rerunning a release workflow deploys again. The original workflow is untouched and the new run can be stopped with Cancel Workflow. Set from failed to restart from the failed job onward, or pass specific job ids to rerun just those.
CircleCI: Set Context Env Var
Add an environment variable to a context, or replace the value of one that already exists under that name. The response carries the variable name and timestamps only. Replacing overwrites a value that cannot be read back first, so check List Context Env Vars before reusing a name.
CircleCI: Trigger Pipeline
Start a new pipeline on a branch or tag, optionally passing pipeline parameters. This RUNS REAL CI: it queues compute that draws on the organization's CircleCI plan usage and it executes whatever the config says, which can include deploy jobs that change live environments. Nothing is destroyed and a run in flight can be stopped with Cancel Workflow or Cancel Job. Branch and tag are mutually exclusive. CircleCI marks this endpoint superseded: it does not work for GitLab or GitHub App projects, which use Trigger Pipeline Run.
CircleCI: Trigger Pipeline Run
Start a pipeline from a named pipeline definition. This is the trigger CircleCI recommends and the only one that works for GitHub App, GitHub Enterprise Server and Bitbucket Data Center projects. It RUNS REAL CI: it queues compute that draws on the organization's plan usage and can run deploy jobs against live environments; a run in flight can be stopped with Cancel Workflow. The three path segments are the project slug split at its slashes, exactly as shown in Project Settings > Overview. Config branch or tag chooses where the config file is read from; checkout branch or tag chooses what the checkout step clones.
CircleCI: Update Schedule
Update a scheduled pipeline. Only the fields you fill are sent, and a sent field REPLACES its whole value: a new timetable object replaces the old timetable outright, and a new parameters object replaces the old parameters, so include every key you still want. Fetch the schedule first if you are changing one key of either.
CircleCI: Update Webhook
Update an outbound webhook. Only the fields you fill are sent; the events array REPLACES the existing list, so include every event you still want. Changing the signing secret invalidates signatures the receiver already trusts, so update the receiver at the same time. The scope cannot be changed.
Connecting CircleCI takes one credential
CircleCI authenticates API v2 requests with a personal API token, sent on every request to circleci.com/api/v2. CircleCI accepts it either as a Bearer authorization header, which its API developer's guide recommends, or as the CircleCI-specific Circle-Token header that existing integrations widely use; both reach the same v2 endpoints, and this connector sends Circle-Token. You create the token in the CircleCI web app under User Settings, then Personal API Tokens. CircleCI's own API documentation states that project API tokens are not supported on API v2, so a personal token is the only credential that works here. The token is created against a user account rather than a project, CircleCI documents it as granting full read and write permissions with no scopes to narrow, and it acts as the person who created it, which is the single most important thing to know before you store one: the choice of account is the real access decision, and a token in an automation is as powerful as the person who made it.
In the CircleCI web app, open User Settings, then Personal API Tokens, and create a token. Copy it when it is shown.
In Mattering Automations, open Connectors, click Add Connector, choose CircleCI, and create a credential with the token.
Click Test Connection. Mattering calls CircleCI's current user endpoint, which every valid personal token can call and which takes no parameters: a user record proves the credential, and a 401 means the token is wrong or has been revoked.
All 55 CircleCI nodes appear in the canvas palette. Run CircleCI: List Collaborations first for the organization slugs, then CircleCI: Get Project for the project id that the webhook and pipeline definition nodes need.
Common uses for the CircleCI MCP
Triage a red build without opening the dashboard
A workflow ends in failure and the investigation runs itself. CircleCI: List Workflow Jobs names the job that failed, CircleCI: Get Job Details adds the executor, resource class, queue and run times, CircleCI: Get Job Test Metadata returns the individual test records the job uploaded through store_test_results with their failure messages, and CircleCI: Get Job Artifacts returns download URLs for whatever the job stored. CircleCI: Get Flaky Tests answers the question a human asks next: is this test already known to flake, or is this new? An agent can assemble all of that into one task before anyone has read the failure email.
Deploys an agent can start, and a person can gate
CircleCI: Trigger Pipeline starts a run on a branch or tag with pipeline parameters, and CircleCI: Trigger Pipeline Run does the same from a named pipeline definition, which is the trigger CircleCI recommends and the only one that works for GitHub App, GitHub Enterprise Server and Bitbucket Data Center projects. Both run real CI against the organization's plan usage, so the useful pattern is not an unguarded agent tool: put the trigger behind an approval step or a condition, then poll CircleCI: Get Workflow until the status settles and report the outcome back into the same thread or task.
Environment variable and context audits that never expose a secret
CircleCI: List Env Vars returns a project's variables with values masked exactly as the web app shows them, four x characters plus the last four, and CircleCI: List Context Env Vars returns context variable names with no values at all. That makes a scheduled audit safe by construction: sweep every project and context, compare the names against the set your policy expects, and open a task on drift. CircleCI: Create Env Var and CircleCI: Set Context Env Var write new values when the sweep finds a gap, with the honest caveat the nodes state themselves, that writing over an existing name replaces a value nobody can read back first.
CI health reporting into a database you already use
CircleCI: Get Project Summary Metrics and CircleCI: Get Workflow Metrics cover success rate, mean time to recovery, throughput and duration percentiles per workflow, CircleCI: Get Workflow Job Metrics drills into the jobs inside one workflow, and CircleCI: Get Job Timeseries returns hourly or daily buckets that a scheduled refresh can advance instead of refetching. Write the rows into a Mattering database and the trend lives next to the work rather than behind a dashboard login. One caveat CircleCI publishes on these endpoints and this page repeats: Insights is not a financial reporting tool, its credit figures do not share a source of truth with the billing pages, and differences from the Plan Overview page are expected.
Schedules and webhooks kept as managed configuration
CircleCI: List Schedules, CircleCI: Create Schedule and CircleCI: Update Schedule turn scheduled pipelines into something a workflow can reconcile rather than something that drifts in the UI, and CircleCI: List Webhooks, CircleCI: Create Webhook and CircleCI: Update Webhook do the same for the outbound webhooks that push workflow-completed and job-completed events to your own receivers. Two vendor facts shape how you use them: schedule endpoints cover GitHub OAuth and Bitbucket Cloud pipeline definitions, and an update sends the whole value of any field it touches, so a new timetable or a new events array replaces the old one outright.
Checkout keys and access reviewed on a schedule
CircleCI: List Checkout Keys shows which SSH keys a project clones with, whether each is a deploy key or a user key, its fingerprint and its creation date, returning public material only. That is the raw material for a quarterly access review: flag user keys, which act as the authorizing person and reach every repository that person can read, and flag keys older than your rotation window. CircleCI: Create Checkout Key adds the replacement before CircleCI: Delete Checkout Key removes anything, which matters because deleting the key a project clones with fails every following build at the checkout step until a new key is registered with the version control provider.
Example: A failing workflow opens a triage task with the evidence attached
Built on the Automations canvas in a few minutes, or described in plain language to Matter and built for you.
Setup, once: CircleCI: Create Webhook registers an outbound webhook on the project for the workflow-completed event, pointed at an inbound webhook trigger in your Mattering automation. CircleCI signs each delivery with the secret you set, in a circleci-signature header carrying an HMAC-SHA256 digest of the body, so verify that signature in the receiver before acting on a payload.
Trigger: the inbound webhook fires when a workflow finishes, carrying the workflow id and its status.
A condition lets only failed workflows through, so green builds cost nothing.
CircleCI: List Workflow Jobs returns every job in that workflow with its status and job number, and the workflow picks out the ones that failed.
CircleCI: Get Job Details adds the run times, resource class and web URL for the failing job.
CircleCI: Get Job Test Metadata returns the individual failing test records, and CircleCI: Get Job Artifacts returns download URLs for the logs and reports the job stored.
CircleCI: Get Flaky Tests checks the failing test names against the project's flake list, so a known flake is labelled as one instead of paging someone.
The workflow opens a task in Mattering Productivity with the job link, the failing tests, the artifact URLs and the flake verdict in the description, assigned to whoever owns the service.
CircleCI MCP questions, answered
What CircleCI operations are supported?
55 nodes on CircleCI API v2: 36 query nodes and 19 action nodes. The read surface covers the current user and collaborations, project details, pipelines (per project, your own, by id, by number, config, workflows, definitions), workflows and their jobs, job details, artifacts and test metadata, project environment variables and context variables, checkout keys, schedules, webhooks, and the full Insights family (project and organization summaries, workflow metrics, workflow summary, workflow runs, job metrics, job timeseries, flaky tests, and branches). The action surface triggers pipelines through both endpoints, cancels and reruns work, and creates, updates and deletes environment variables, contexts and context variables, checkout keys, schedules and webhooks. Deliberately not included: workflow approval gates, which are a human control that automating would defeat, creating or deleting organizations and projects, policy management and OIDC custom claims, usage exports, deploy markers and rollback, and the OpenTelemetry exporters.
Does this work with Claude, ChatGPT, or other AI assistants?
Yes. Mattering exposes these nodes over MCP, an open protocol for connecting AI assistants to tools, so any MCP-capable assistant, including Claude and ChatGPT, can connect to your workspace and use them. Matter, the assistant built into the platform, uses the same nodes natively.
CircleCI publishes its own MCP server. Why use this one?
Both exist, and they are built for different jobs. CircleCI ships a first-party MCP server: a hosted remote server at mcp.circleci.com that authenticates with OAuth2, plus an open-source local server that is now built into the CircleCI CLI. It is good at what it is for, which is diagnosing a failing build, reading test results and spotting flaky tests from inside an editor, and if your assistant is the whole workflow then CircleCI's own server is the shorter path. The difference here is that these nodes run on the Mattering canvas as well as over MCP, so the same operation can sit inside a scheduled automation, behind an approval step, or in a chain that opens a Mattering Productivity task and writes rows into a Mattering database, with the token stored once alongside your other connector secrets. This connector also covers the configuration surfaces rather than only the diagnosis ones: project and context environment variables, contexts, checkout keys, scheduled pipelines and outbound webhooks.
What kind of CircleCI token does this use, and how much access does it carry?
A personal API token, created under User Settings, then Personal API Tokens. CircleCI accepts it either as a Bearer authorization header, which its API developer's guide recommends, or as the CircleCI-specific Circle-Token header that existing integrations widely use; this connector sends Circle-Token and reaches the same v2 endpoints. CircleCI's API documentation states that project API tokens are not supported on API v2, so the personal token is the only option, and there is no OAuth app flow for authenticating REST API v2 calls. The consequence is worth planning around: the token is created against a user account rather than a project, CircleCI documents it as granting full read and write permissions with no scopes to narrow, and it acts as the person who created it, so it reaches whatever that person reaches rather than only the one project you meant to automate. If your team separates duties, connect with a token from an account whose access matches what the automations should be able to reach, and rotate it in CircleCI when that person's role changes.
Can an AI agent start and stop real CI runs?
Yes, and the nodes are explicit about what that means. CircleCI: Trigger Pipeline, CircleCI: Trigger Pipeline Run and CircleCI: Rerun Workflow queue compute that draws on the organization's CircleCI plan usage and execute whatever the config says, which can include deploy jobs against live environments, so rerunning a release workflow deploys again. Nothing is destroyed by them and a run in flight can be stopped with CircleCI: Cancel Workflow or CircleCI: Cancel Job, though side effects a job already completed are not undone by cancelling. The pattern we would use: give an agent the read nodes freely, and put the three run-starting nodes behind a condition or an approval step.
Can it read secrets out of CircleCI?
No, and that is CircleCI's design rather than a limitation of this connector. Project environment variable reads return the value masked, four x characters plus the last four characters, so CircleCI: List Env Vars and CircleCI: Get Env Var answer whether a name exists and roughly which value is set, never what the secret is. Context variables are stricter still: CircleCI: List Context Env Vars returns names and timestamps with no value at all. Checkout key reads return public material only, and CircleCI: List Webhooks returns the signing secret masked rather than in full. This is why the delete nodes for variables are flagged destructive in the strongest terms: no automation can take a copy first.
What are CircleCI's API rate limits?
CircleCI documents the behaviour but not the numbers, so this page will not invent one. Throttled requests come back as HTTP 429, usually with a Retry-After header, and current allowances are readable from the response itself through the RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers and the X-RateLimit-Limit-Second, Minute, Hour and Day family. CircleCI states that limits differ across parts of the API, that they are subject to change, and that frequent polling is a way to get throttled, which is why the Insights node descriptions tell you to poll sparingly. When a call is refused the node reports the error on its output rather than silently retrying, so a workflow can wait and continue.
Which trigger node should I use?
It depends on how your organization connects to its version control provider, and both ship because dropping either would strand a whole class of organization. CircleCI: Trigger Pipeline takes a project slug and a branch or tag, which is the simple case, but CircleCI marks that endpoint superseded and it does not work for GitLab or GitHub App projects. CircleCI: Trigger Pipeline Run is the recommended one and the only one that works for GitHub App, GitHub Enterprise Server and Bitbucket Data Center projects; it takes the project slug split into its three path segments plus a pipeline definition id, which CircleCI: List Pipeline Definitions supplies, and it chooses the config source and the checkout target separately rather than taking a bare branch name. One limit to plan around before you pick: CircleCI documents the newer endpoint as covering every organization and pipeline type except GitLab, so on a GitLab project neither trigger node applies and those pipelines have to be started from CircleCI itself.
Why does the project slug field want a whole string instead of an org and a repo?
Because CircleCI's own guidance is to treat a project slug as an opaque string, and it has two documented forms. GitHub OAuth and Bitbucket Cloud organizations get the readable form, a version control slug plus organization and repository name, such as gh/example-org/example-repo. GitHub App, GitLab and Bitbucket Data Center organizations get an opaque form built from two identifiers under a circleci prefix. Composing one from parts breaks for the second group, so the connector takes a single field and every field description tells you where to copy it from in Project Settings. The related fact that catches people out: CircleCI API v2 has no project listing endpoint, so the slug is something you copy once rather than something a picker can discover.
Can I use the Insights nodes for cost reporting?
Treat them as engineering telemetry, not accounting. CircleCI states on these endpoints that Insights is not a financial reporting tool, that its credit figures do not share a source of truth with the billing pages, and that discrepancies with the Plan Overview page are expected, so a credits column from CircleCI: Get Workflow Metrics belongs in a trend chart rather than an invoice reconciliation. A few other honest limits carried on the nodes: summary metrics refresh daily, so the last 24 hours may be missing, aggregation reaches back at most 90 days, that same retention window bounds how far back a timeseries request can reach, and hourly buckets are retained for 48 hours against 90 days for daily buckets. One piece of our own guidance on top of those: because success rate and duration percentiles are rates rather than counts, combine them by refetching the window you actually want instead of averaging buckets you already have.
Put CircleCI to work inside your workspace
Connect once, then use every node in visual automations and AI agent workflows across the Mattering platform.
All product names, logos, and brands are property of their respective owners and are used for identification purposes only. Use of these names, logos, and brands does not imply endorsement or affiliation. CircleCI is a product of its respective owner; Mattering is an independent platform.