Secure Buildkite access for AI agents
Pipelines, builds, jobs, clusters, and test runs, plus build/job log search, via Buildkite's official MCP server.
Buildkite is where agents are most useful and most dangerous at the same time. Reading a failing job's log to explain what broke is exactly what you want; triggering builds, rewriting pipelines, or pausing a cluster queue on a hunch is not. Adding Buildkite here puts every tool call through your policies and onto the audit log, so you can hand agents the logs without handing them the CI system.
Server URL: https://mcp.buildkite.com/mcp
Credential modes
Buildkite supports per-org dynamic registration only, so there is no app to create on Buildkite's side and no client ID or secret to enter. See Credential modes for how it compares with Use SecureAuth's app and Bring your own app.
Before you begin
- A Buildkite account that can reach the pipelines and builds your agents need.
- Administrator access to your Agent Authority workspace, to add the resource.
Setup
- In the Agent Authority console, go to Tools & Services and click Add Resource.
- Select Buildkite from the catalog.
- On Choose how to install Buildkite, click Per-org dynamic registration. Selecting it adds the resource right away with its tools pre-configured.
Dynamic client registration
When you add the resource, the gateway registers its own OAuth client with Buildkite, the credential that lets it sign users in. Buildkite's own organization, pipeline, and cluster-level permissions still apply, so an agent can only reach what the person who signed in could already reach.
Verify the connection
The gateway syncs the Buildkite tools automatically. To check the connection end to end, ask your agent to run a request:
List my Buildkite pipelinesIf your pipelines come back, the connection is working.
How users connect
Access is per user. Each additional user connects their own Buildkite account the first time their agent calls a Buildkite tool: the gateway returns a sign-in link, the user authorizes once, and the tools work from then on. Go to Connections to manage linked accounts.
Available tools
Buildkite exposes 46 tools. They are grouped below; the resource's Overview tab shows the authoritative per-tool list under Available Tools once installed.
| Tool | Tags | Description |
|---|---|---|
current_user | read-only | Get the currently authenticated user |
user_token_organization | read-only | Get the organization associated with the current access token |
access_token | read-only | Get details about the current access token |
list_pipelines / get_pipeline | read-only | List pipelines, or get details about a specific pipeline |
create_pipeline / update_pipeline | write | Create or update a pipeline |
list_pipeline_schedules / get_pipeline_schedule | read-only | List or get a pipeline's scheduled builds |
create_pipeline_schedule / update_pipeline_schedule | write | Create or update a pipeline schedule |
list_builds / get_build | read-only | List builds, or get details about a specific build |
create_build | write | Trigger a new build |
cancel_build | destructive | Cancel a running build on a Buildkite pipeline |
rebuild_build | write | Rebuild or retry a whole build on a Buildkite pipeline |
get_build_test_engine_runs | read-only | Get Test Engine runs associated with a build |
list_jobs / get_job | read-only | List jobs on a build, or get details about a specific job |
get_job_env | read-only | Get a job's environment variables |
retry_job / unblock_job | write | Retry a failed job, or unblock a blocked job |
read_logs / tail_logs / search_logs | read-only | Read, tail, or search a job's build log |
list_artifacts_for_build / list_artifacts_for_job | read-only | List artifacts for a build or a specific job |
get_artifact | read-only | Get details about a specific artifact |
create_annotation | write | Create an annotation on a build or specific job |
list_annotations | read-only | List annotations for a build or a specific job |
list_agents / get_agent | read-only | List agents, or get details about a specific agent |
list_clusters / get_cluster | read-only | List clusters, or get details about a specific cluster |
create_cluster / update_cluster | write | Create or update a cluster |
list_cluster_queues / get_cluster_queue | read-only | List queues in a cluster, or get a specific queue |
create_cluster_queue / update_cluster_queue | write | Create or update a cluster queue |
pause_cluster_queue_dispatch / resume_cluster_queue_dispatch | write | Pause or resume dispatch on a cluster queue |
list_test_runs / get_test_run | read-only | List test runs, or get details about a specific test run |
get_test | read-only | Get details about a specific test |
get_failed_executions | read-only | Get failed test executions for a test run |
Two of these read tools deserve a second look before you allow them broadly: get_job_env returns a job's environment variables, and access_token describes the token behind the connection.
Required scopes
The gateway does not request a fixed scope list for Buildkite. It registers the client without naming any scopes and records the ones Buildkite returns.
Policy examples
Read-only Buildkite for everyone
One deny rule blocks every mutating tool while leaving reads on the default path:
- In Agent Actions, click Add Rule and name it "Buildkite: no CI mutations."
- Set the effect pill to Deny and the MCP scope pill to Buildkite.
- Add these tool patterns:
create_*,update_*,cancel_build,rebuild_build,retry_job,unblock_job,pause_cluster_queue_dispatch,resume_cluster_queue_dispatch. - Set the status to Active and click Create.
create_* and update_* cover all ten pipeline, schedule, cluster, queue, build, and annotation writers; the six explicit names are the mutating tools that don't share those prefixes. Everything else (the reads) keeps working.
Scope one agent to build and log triage
An allow rule on its own restricts nothing, because every org is seeded with an Allow all rule that anything unmatched falls through to. To confine an agent, pair the allow with a deny beneath it:
- Create the deny rule first: effect Deny, MCP scope Buildkite, Agent scope your triage agent, tool pattern
*. - Then create the allow rule: effect Allow, MCP scope Buildkite, the same Agent scope, tool patterns
list_builds,get_build,list_jobs,get_job,read_logs,tail_logs,search_logs,get_failed_executions.
Order matters, and so does the sequence you create them in: new rules insert at the top of the list, so building the deny first leaves the allow above it. That is the order you need. Evaluation is first-match-wins, so the agent's triage calls hit the allow, every other Buildkite call hits the deny, and neither ever reaches Allow all.
Scoping both rules to one agent keeps the blast radius small. A deny with no Agent scope would cut off every agent and user in the org.
Block destructive tools
One deny rule blocks every tool tagged destructive, regardless of its name:
- In Agent Actions, click Add Rule and name it "Buildkite: no destructive tools."
- Set the effect pill to Deny and the MCP scope pill to Buildkite.
- Open the Tools pill and pick the built-in tag
destructive. - Set the status to Active and click Create.
Next steps
- Create a policy – the full rule editor walkthrough.
- Policies – how first-match-wins ordering and the default Allow all rule interact.
- Block an agent from deleting GitHub branches – the same deny-first shape on another resource.