Menu
Mattering Automations connector

A Buildkite MCP that can read a red build and do something about it

Connect one Buildkite API access token and your pipelines, builds, jobs, logs, artifacts, agents, and annotations become workflow steps. An AI agent can pull the failing job's log, write a summary back onto the build page as an annotation, and open a task, while a build that needs a human approval waits for one instead of for someone to notice.

40 ready-made nodes One credential to connect Works with Claude, ChatGPT, and Matter

What the Buildkite MCP connector does

The Buildkite connector for Mattering Automations is 40 nodes on the Buildkite REST API v2, 25 that read and 15 that act: organizations and their members, pipelines from create and update through archive, unarchive, and delete, builds listed across every organization the token can reach or one pipeline with create, cancel, and rebuild, jobs with retry, unblock, log output, and environment variables, build agents including a stop, artifacts with time limited signed download URLs, build annotations read and written, teams, clusters, cluster queues, and the organization's emoji shortcodes. One Buildkite API access token, sent as a Bearer token, authenticates all of it.

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 start from Buildkite: List Organization Builds filtered to failed, read the broken step with Buildkite: Get Job Log Output, and post what it found back onto the build with Buildkite: Create Build Annotation, without anyone opening a CI dashboard.

The point of putting CI on a canvas is everything that is not CI. A failed build can open a task in Mattering Productivity with the log excerpt attached, a deploy can wait behind an approval that lives where the approvers already are and then release the gate with Buildkite: Unblock Job, and a nightly sweep can write build durations into a Mattering database next to the rest of your operating data. Credentials sit with your other connector secrets, and no agent needs shell access or a CI dashboard login to do any of it.

Two things about this connector are worth knowing before you wire anything. The first is safety modeling: five nodes are flagged destructive, Buildkite: Revoke Access Token, Buildkite: Delete Pipeline, Buildkite: Delete Job Log Output, Buildkite: Delete Artifact, and Buildkite: Stop Agent, and three more spend real money and minutes because they start real CI work, Buildkite: Create Build, Buildkite: Rebuild Build, and Buildkite: Retry Job. Each one says so on the node itself. The second is addressing: Buildkite payloads carry both a UUID and a slug for organizations and pipelines, and only the slug works in a path, while builds are addressed by their per-pipeline number. Every field in this connector asks for the value that actually works and says so in its description, which is the difference between a workflow that runs and one that returns a tidy 404.

One connection, three surfaces

  • Visual automations. Drag Buildkite 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 Buildkite node, ready to drop on the canvas

40 nodes, generated from the connector itself so this list always matches what ships. Expand a category to browse.

Read and query nodes 25

Buildkite: Get Access Token

Check the stored API access token: returns its uuid, the SCOPE list it carries, its description, creation date and expiry, plus the owning user. Every token can call this regardless of scopes, so it is the credential health check to run first, and the scope list tells you up front whether a write node will be allowed. The token value itself is never echoed.

Buildkite: Get Agent

Fetch one agent by UUID: connection state, host details, version, queue, meta-data, the job it is running, and when it connected or was last seen.

Buildkite: Get Artifact Download URL

Get a time-limited signed download URL for one artifact, returned at data.url with HTTP 302. The node deliberately does NOT follow the redirect: it hands back the URL so a later step can fetch the file, rather than pulling a binary into the automation payload. The URL expires, so use it promptly.

Buildkite: Get Build

Fetch one build by its pipeline build NUMBER: state, branch, commit, message, creator, meta-data, timings and the full jobs array with each job's exit status and log URL. The natural node to poll while waiting on a build.

Buildkite: Get Current User

Fetch the user the token belongs to: id, name, email and avatar. Requires the read_user scope. Useful for stamping which identity an automation is acting as.

Buildkite: Get Job

Fetch one job by id: state, command, exit status, step key, agent, retry lineage and timings, plus the log and artifact URLs. Use it to poll a single long-running step.

Buildkite: Get Job Environment Variables

Fetch the environment variables a job ran with, under data.env. Invaluable for debugging why one build behaved differently from another. NOTE: this returns whatever the job had in its environment, so if the pipeline injects secrets as plain environment variables they land in the automation's execution record.

Buildkite: Get Job Log Output

Fetch a job's log as JSON: the log text at data.content, its size in bytes, and header timestamps. The node an automation reaches for when it wants to summarize or search a failure. Logs can be large, so expect a big payload on chatty steps.

Buildkite: Get Organization

Fetch one organization by slug: name, web URL, creation date, and the sub-resource URLs for its pipelines, agents and emojis.

Buildkite: Get Pipeline

Fetch one pipeline by slug: repository, default branch, YAML configuration, visibility, cluster, tags and archived state.

Buildkite: List Agents

List an organization's build agents with connection state, hostname, IP, version, queue, meta-data and the job each one is currently running. The capacity view: count connected agents against scheduled jobs to see whether CI is starved.

Buildkite: List All Builds

List builds across EVERY organization the token can see, newest first. The broadest read in the connector: good for a cross-organization dashboard, but set exclude_jobs when you only need state, because full build payloads with jobs are large.

Buildkite: List Build Annotations

List the annotations attached to a build: the rendered HTML panels steps publish for coverage numbers, test summaries and links. This is where a build's own report lives, so it is the richest thing to forward into a chat message or a task.

Buildkite: List Build Artifacts

List every artifact uploaded by every job in a build, with path, filename, MIME type, size, SHA1 and the job that produced it. Filter by path with a glob to find one file across a large matrix build.

Buildkite: List Cluster Queues

List a cluster's queues with their key, description and dispatch state. dispatch_paused is the one to watch: a paused queue means jobs are piling up and no agent will pick them up, which looks identical to a capacity problem until you check.

Buildkite: List Clusters

List an organization's clusters: the isolation boundary that groups agent queues and the pipelines allowed to use them. Each entry carries its default queue and the cluster UUID a pipeline needs at creation time.

Buildkite: List Emojis

List the emoji shortcodes an organization can use, with their image URLs and any aliases, including custom emoji uploaded by the organization. Useful when rendering build messages or pipeline names elsewhere, since Buildkite stores shortcodes like :rocket: as literal text.

Buildkite: List Job Artifacts

List the artifacts one job uploaded, with path, size, MIME type, SHA1 and state. Narrower than the build-level lister when a matrix build produces the same filename from many jobs.

Buildkite: List Jobs

List a build's jobs with their id, step key, state, command and timings. Unlike every other Buildkite lister this one is CURSOR paginated and wraps its rows: the array lives at data.items and the next page URL at data.links.next. Filter state to failed to find exactly what broke.

Buildkite: List Organization Builds

List builds across all of one organization's pipelines, newest first, with the same filter set as the other build listers. This is the practical one for an organization-wide CI status feed: filter state to running or failed to see what needs attention.

Buildkite: List Organization Members

List the people in an organization with their user UUID, name, email, role (admin or member) and SSO mode. The ids here are the user UUIDs the build listers' creator filter and the teams lister's user_id filter expect.

Buildkite: List Organizations

List the Buildkite organizations this token can access, each with the SLUG that every other node needs. Note the response carries both an id UUID and a slug: paths use the slug.

Buildkite: List Pipeline Builds

List one pipeline's builds, newest first. Each entry carries the build NUMBER that every build action needs, plus state, branch, commit, message and timings. Filter by branch to answer questions like whether main is green.

Buildkite: List Pipelines

List an organization's pipelines with their SLUG, repository, default branch, visibility, archived state and live build and job counts. The running and scheduled counts make this a one-call CI health check.

Buildkite: List Teams

List an organization's teams with their UUID, name, slug, privacy and whether each is the default team. Requires the read_teams scope and only returns anything once Teams is enabled on the organization. The UUIDs here are what the pipeline nodes' teams field expects.

Action nodes 15

Buildkite: Archive Pipeline

Archive a pipeline: it stops accepting new builds and drops out of the default pipeline list, while its history and artifacts are kept. This is the safe alternative to deleting a pipeline you no longer run, and Buildkite: Unarchive Pipeline puts it back.

Buildkite: Cancel Build

Cancel a build that is scheduled or running. Its jobs stop, the build lands in the canceled state, and the record stays in history. Cancelling a build that already finished changes nothing. This is the stop button for anything Create Build or Rebuild started.

Buildkite: Create Build

Start a new build on a pipeline at a given commit and branch. WARNING: this starts a REAL CI run. It consumes the organization's pipeline minutes, runs whatever the pipeline's steps do (including deploys), and cannot be undone. It is classed a reversible write only because it produces a build record that Buildkite: Cancel Build can stop while it is still running. Use the literal commit value HEAD to build the branch tip. Anything you pass in env and meta_data is visible to the build's steps, so never put secrets there.

Buildkite: Create Build Annotation

Attach an annotation panel to a build, in Markdown or HTML. The way to write an automation's findings back onto the build page where the team already looks, for example a deploy summary or a link to a report. Reusing the same context replaces that panel, or appends to it when append is true.

Buildkite: Create Pipeline

Create a pipeline in an organization. Supply EITHER a YAML configuration string (the modern form) OR a visual steps array, along with name, repository and cluster_id. Creating a pipeline does not itself run anything; the first build starts when something triggers it. Reversible via Buildkite: Delete Pipeline, which is Destructive.

Buildkite: Delete Artifact

DESTRUCTIVE AND IRREVERSIBLE: permanently deletes an uploaded artifact. The stored file is gone and cannot be recovered; the artifact record moves to the deleted state. Used for purging large or sensitive build outputs. Returns 204 with no body.

Buildkite: Delete Job Log Output

DESTRUCTIVE AND IRREVERSIBLE: permanently deletes a job's log output. Buildkite keeps no copy and the job's own record stays but with no log to read. The legitimate use is purging a log that captured a secret; fetch it first if you need the content. Returns 204 with no body.

Buildkite: Delete Pipeline

DESTRUCTIVE AND IRREVERSIBLE: permanently deletes a pipeline along with its build history, job logs and artifacts. There is no undo and no recycle bin. If you only want the pipeline to stop running, use Buildkite: Archive Pipeline instead, which keeps everything and can be reversed. Returns 204 with no body on success.

Buildkite: Rebuild Build

Re-run an existing build at the same commit, creating a NEW build whose rebuilt_from points at the original. WARNING: this starts a REAL CI run. It consumes the organization's pipeline minutes, runs whatever the pipeline's steps do (including deploys), and cannot be undone. It is classed a reversible write only because it produces a build record that Buildkite: Cancel Build can stop while it is still running. The pipeline must have rebuilds allowed. The classic retry a flaky build automation, and the classic way to accidentally redeploy, so gate it on the build's state.

Buildkite: Retry Job

Retry a single job inside a build, rescheduling that step rather than the whole build. WARNING: this runs REAL CI work and consumes pipeline minutes, and if the step deploys it will deploy again. Cheaper than a full rebuild when one flaky step failed. Only jobs in a retryable state can be retried.

Buildkite: Revoke Access Token

DESTRUCTIVE AND IRREVERSIBLE: permanently revokes the API access token this connector is authenticated with. Every Buildkite node in every automation stops working immediately and a new token must be created in Buildkite and stored again. There is no undo and no confirmation step. Build this into a break-glass credential-rotation flow only.

Buildkite: Stop Agent

DESTRUCTIVE BY DEFAULT: instructs an agent to disconnect. Buildkite's force parameter defaults to TRUE, which CANCELS the job the agent is currently running and the build that job belongs to; that work is lost and cannot be resumed. Set force to false to let the current job finish first, which is what a graceful drain wants. Returns 204 with no body.

Buildkite: Unarchive Pipeline

Restore an archived pipeline so it accepts builds again and reappears in the pipeline list. Clears archived_at.

Buildkite: Unblock Job

Release a block step so the build continues past a manual gate. This is how an approval flow in another system lets a Buildkite deploy proceed. Everything after the block step then runs, so treat it as authorizing that work. Supply fields when the block step declares input fields.

Buildkite: Update Pipeline

Update a pipeline. This is a PATCH, so only the fields you fill are changed and everything else is left alone. Note that configuration REPLACES the pipeline YAML wholesale, and changing slug changes the pipeline's URL, which breaks any automation still using the old one.

Connecting Buildkite takes one credential

Buildkite authenticates its REST API with an API access token sent as an Authorization Bearer header, and that is exactly what Mattering stores. Tokens are created in Buildkite under Personal Settings, then API Access Tokens, and they are scoped twice over: a token you create today reaches exactly one organization, and it carries a read and write scope set you choose per feature, with a separate delete tier on a few surfaces this connector does not touch. Only legacy tokens made before August 2023 hold several organizations, and they cannot take on more, so automating a second organization means a second token and a second Mattering credential. That double scoping is the thing to get right, because a token that is perfectly valid still returns 403 on a pipeline it was never granted.

1

In Buildkite, open Personal Settings, then API Access Tokens, and create a token. Pick the organization first: a new token reaches exactly one, and Buildkite preselects the organization you used most recently, so check that it is the one you meant. Set Token Expiry deliberately in the same form, because it defaults to seven days when left unset, and choose a duration that matches how often you will rotate the credential. Then grant the scopes your nodes need: read_pipelines and write_pipelines for the pipeline nodes, read_builds and write_builds for builds, retry, unblock, and annotations, and the three job scopes that the build scopes do not cover, read_build_logs for the job log node, write_build_logs to delete a job log, and read_job_env for the job environment variables node. That split is why a token that lists a build's jobs happily still returns 403 on the log. Add read_clusters for clusters and queues, write_agents for the stop agent node, write_artifacts for the delete artifact node, plus the read scopes for agents, artifacts, teams, organizations, and user.

2

Copy the token, then in Mattering Automations open Connectors, click Add Connector, choose Buildkite, and create a credential with the token pasted in. Buildkite shows the token value once at creation, so if you navigate away before pasting it you have to create a new one.

3

Click Test Connection. Mattering calls Buildkite's access token endpoint, which every token can call whatever its scopes, so a success proves the credential itself and a 401 means the token is wrong, mistyped, or revoked.

4

All 40 Buildkite nodes appear in the canvas palette. Run Buildkite: Get Access Token first to see the scope list the credential actually holds, then Buildkite: List Organizations for the organization slug that nearly every other node asks for.

Common uses for the Buildkite MCP

Triage a red build before anyone opens the dashboard

Buildkite: List Organization Builds filtered to the failed state is a one-node view of what needs attention across every pipeline in an organization. From a single build, Buildkite: List Jobs narrows to the step that broke, Buildkite: Get Job Log Output pulls the log an assistant can summarize, and Buildkite: List Build Annotations picks up whatever the pipeline already published about itself, coverage numbers, test summaries, links. The output goes wherever your team looks: a chat message, a task, a database row, or straight back onto the build.

An AI agent with read access to CI

The 25 query nodes are a safe surface to hand an assistant. Buildkite: Get Build polls a run to completion, Buildkite: Get Job returns one step's exit status and retry lineage, Buildkite: List Build Artifacts finds the report a matrix build produced, and Buildkite: Get Artifact Download URL hands back a signed link rather than pulling binary content into the run. One honest caveat carried on the node: Buildkite: Get Job Environment Variables returns whatever the job had in its environment, so on a pipeline that injects secrets as plain environment variables those values land in the automation's execution record.

Approvals that live where the approving happens

Buildkite's block steps already pause a build for a human. Buildkite: Unblock Job is how something outside Buildkite releases that gate, so the approval can be a task assignment, a chat reply, or a checklist in the system your reviewers actually use, and the build proceeds the moment it is granted. Treat it as authorizing work rather than clearing a notification: everything after the block step then runs, deploys included, and the node says so.

Retry the flaky step, not the whole afternoon

Buildkite: Retry Job reschedules one failed step, which is cheaper than Buildkite: Rebuild Build re-running the entire pipeline at the same commit. Both start real CI work, consuming agent capacity and whatever compute those steps bill for, and if the step deploys it deploys again, so the sane pattern is a condition on the build or job state ahead of them and Buildkite: Cancel Build available as the stop button. Buildkite: Create Build is the same story from the other direction: a workflow elsewhere in the platform can kick off a run at a given branch and commit, using the literal value HEAD to build the branch tip.

Capacity and queue checks that explain a stuck build

When jobs sit scheduled and nothing picks them up, there are two very different causes and Buildkite tells them apart. Buildkite: List Agents shows how many agents are connected, what each is running, and their queue and meta-data, which is the capacity answer. Buildkite: List Cluster Queues shows dispatch state, and a queue with dispatch paused looks exactly like a capacity problem until you check it. Buildkite: List Clusters ties the two together, and a scheduled sweep can raise a task when connected agents fall behind scheduled jobs.

Pipeline lifecycle that prefers archive to delete

Buildkite: Create Pipeline stands one up from a YAML configuration string or a visual steps array, and Buildkite: Update Pipeline patches it, changing only the fields you fill, with two behaviors called out on the node: the configuration field replaces the pipeline YAML wholesale, and changing the slug changes the pipeline's URL and breaks any automation still using the old one. For pipelines you no longer run, Buildkite: Archive Pipeline keeps the history and artifacts and Buildkite: Unarchive Pipeline puts them back, which is why Buildkite: Delete Pipeline is flagged destructive and is rarely the right node.

Example: A build fails overnight: collect the evidence, annotate the build, open the task

Built on the Automations canvas in a few minutes, or described in plain language to Matter and built for you.

1

Trigger: a webhook you configured once on the pipeline in Buildkite delivers the build finished event to a Mattering webhook trigger, carrying the organization slug, the pipeline slug, and the build number.

2

A condition checks the build state so only failures continue past this point.

3

Buildkite: List Jobs reads the build's jobs, filtered to the failed state. Its rows sit at data.items rather than at the top level, because this is the connector's one cursor paginated lister.

4

Buildkite: Get Job Log Output pulls the failing step's log, and Matter or another MCP-capable assistant turns it into two sentences a person can act on.

5

Buildkite: Create Build Annotation posts that summary back onto the build page. Reuse the same context value and a re-run replaces the panel instead of stacking copies of it.

6

Buildkite: Get Artifact Download URL produces a signed link to the test report, and the workflow opens a task in Mattering Productivity with the summary, the build URL, and that link, so the morning starts with the evidence already gathered.

Buildkite MCP questions, answered

What Buildkite operations are supported?

40 nodes on the Buildkite REST API v2: 25 query nodes and 15 action nodes. Access token and current user reads, organizations and organization members, pipelines (list, get, create, update, archive, unarchive, delete), builds (three listers covering every organization the token can reach, one organization, and one pipeline, plus get, create, cancel, and rebuild), jobs (list, get, retry, unblock, log output, delete log output, environment variables), agents (list, get, stop), artifacts (per build, per job, signed download URL, delete), build annotations (list and create), teams, clusters, cluster queues, and emoji shortcodes. Deliberately not included: Buildkite Test Engine, Packages and Registries, Portals, Rules, and Pipeline Templates, which are separate product surfaces; audit event exports; agent tokens, which mint the credential agents use to join a cluster and do not belong on a canvas; team membership changes; and administrative configuration such as organization and pipeline settings, notification services, and repository connections.

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.

How is this different from Buildkite's own MCP server?

Buildkite ships an official MCP server, and it is a real one: a remote server at mcp.buildkite.com with OAuth, a direct endpoint for headless agents, and a self-hosted local option, covering builds, jobs, logs, and test runs. The difference is what surrounds the call. These nodes run as steps on an automation canvas next to every other connector, so a single workflow can catch a failed build, open a task, post to chat, wait on a human approval, and write a row, with the credential stored alongside your other connector secrets and one run history across all of it. If what you want is an assistant that can talk to Buildkite directly, the vendor server does that. If you want a Buildkite event to drive work in the other systems your team runs on, that is what this connector is for.

Can an AI agent start, cancel, or rebuild real builds?

It can, and the connector is blunt about what that means. Buildkite: Create Build and Buildkite: Rebuild Build start real CI runs: they run whatever the pipeline's steps do including deploys, consuming agent capacity and whatever compute those steps bill for, and cannot be undone. Buildkite: Retry Job carries the same warning for a single step. All three are classed reversible writes only because Buildkite: Cancel Build can stop a run that is still going, and the record stays in history either way. The practical pattern is to give an agent the read nodes freely and put the three run-starting nodes behind a condition, an approval task, or a manual run, and to scope the token itself so write_builds is granted only when you mean it.

What are Buildkite's API rate limits?

Buildkite documents a default of 200 requests per minute per organization, noting that the default can vary by plan, plus 50 requests per minute per user, and reports both budgets in RateLimit response headers on every reply. A breach returns 429 with a scope field naming which of the two limits was hit: rest for the organization limit, rest_user for the per-user one. It matters most for polling: a workflow checking a build every ten seconds across a few pipelines spends the per-user budget quickly. Poll on a slower interval, or skip polling entirely and let a Buildkite webhook push the finished event to a Mattering webhook trigger.

Why do the nodes ask for slugs and build numbers instead of ids?

Because that is what Buildkite's paths accept. Organization and pipeline payloads carry both an id UUID and a slug, and only the slug works in a URL, while builds are addressed by their per-pipeline number rather than by their id. Passing the UUID produces a 404 that looks like a permissions problem, which is the single most common Buildkite integration mistake. Every field in this connector asks for the value that works and says so in its description, and the canvas pickers chain in the order the API needs them: organization, then pipeline, then build, then job, then artifact. Jobs, agents, artifacts, clusters, queues, teams, and users genuinely are addressed by UUID.

Test Connection passed but a node returns 403. What is wrong?

Almost always the token's scopes or its organization, not the token itself. A Buildkite token created today reaches exactly one organization, so a second organization means a second token and a second Mattering credential, and it carries a read and write scope set chosen per feature, with a separate delete tier on a few surfaces this connector does not touch. The access token endpoint that Test Connection calls is callable by every token regardless of scopes, so it proves the credential without proving the permissions. Buildkite: Get Access Token exists for exactly this: run it and read the scope list the credential actually holds. If write_pipelines or write_builds is missing, or one of the job scopes such as read_build_logs, or the organization you are calling is not the one this token belongs to, create or edit a token that covers it and try again.

Does it cover Buildkite Test Engine, Packages, or Pipeline Templates?

No. Those are separate product surfaces with their own object models, and bolting two or three token nodes onto a CI connector would be worse than leaving them out. Test Engine in particular lives on the same api.buildkite.com host, so it is a curation decision rather than a technical limit, and it deserves its own pass. This connector covers the pipeline, build, job, agent, artifact, and annotation surface end to end instead.

Which nodes are destructive, and what exactly do they take with them?

Five. Buildkite: Revoke Access Token kills the credential the connector runs on, so every Buildkite node in every automation stops working at once and a new token has to be created and stored. Buildkite: Delete Pipeline takes the pipeline's build history, job logs, and artifacts with it, and Buildkite documents no undo for it, which is why archive and unarchive are built: archiving is documented as the option that preserves the pipeline's builds, build logs, and artifacts. Buildkite: Delete Job Log Output and Buildkite: Delete Artifact destroy stored output permanently, and their legitimate use is purging something that captured a secret. Buildkite: Stop Agent is the subtle one: Buildkite's force parameter defaults to true, which cancels the job the agent is running and the build that job belongs to, so set force to false when what you want is a graceful drain.

40 nodes waiting on the canvas

Put Buildkite 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. Buildkite is a product of its respective owner; Mattering is an independent platform.

Start Free Explore our Products