Buildkite

Buildkite

This connector works with the Buildkite REST API (https://api.buildkite.com/v2) and the Test Engine API (/v2/analytics): organizations, pipelines, builds, jobs and their logs, artifacts, annotations, agents, clusters and queues, and Test Engine suites, tests and runs. 34 tools: the AI reads all of these, and can start, rebuild and retry builds, unblock steps and add annotations after you confirm. It acts as the user who owns the token.

Setup (about 3 minutes)

1. In Buildkite open your avatar > Personal Settings > API Access Tokens (https://buildkite.com/user/api-access-tokens) and click New API Access Token.
2. Choose the organizations and these scopes: read_builds, read_build_logs, read_pipelines, read_artifacts, read_agents, read_clusters, read_organizations, read_user and, for Test Engine, read_suites. For the writes add write_builds. Leave out what you do not want the AI to do.
3. Paste the token into BUILDKITE_API_TOKEN. It is sent as Authorization: Bearer <token> to api.buildkite.com only.
4. Check it with buildkite_get_access_token (shows the scopes), then buildkite_list_organizations.

Slugs and numbers: tools take the organization slug (org) and the pipeline slug (pipeline) as in buildkite.com/<org>/<pipeline>, and the build number (#123), not the build UUID. Jobs, artifacts and agents use UUIDs. buildkite_list_test_runs filters by the build UUID (id of the build).

How to work

1. Find things: buildkite_get_current_user, buildkite_list_organizations, buildkite_get_organization, buildkite_list_pipelines, buildkite_get_pipeline.
2. Builds: buildkite_list_builds (whole organization) or buildkite_list_pipeline_builds (one pipeline), filtered by branch, state (failed, running, blocked ...), commit or dates. They leave jobs out by default; buildkite_get_build shows them.
3. Why did it fail: buildkite_list_jobs with state=failed, then buildkite_get_job and buildkite_get_job_log (the last 100,000 bytes by default). buildkite_list_annotations often holds the test summary. Artifacts: buildkite_list_build_artifacts, buildkite_list_job_artifacts, buildkite_get_artifact.
4. Agents and capacity: buildkite_list_agents, buildkite_get_agent, buildkite_list_clusters, buildkite_get_cluster, buildkite_list_cluster_queues.
5. Test Engine (flaky and slow tests): buildkite_list_test_suites, buildkite_list_tests (sort_by=reliability, order=asc for the least reliable, or labels=flaky), buildkite_get_test, buildkite_list_test_runs, buildkite_get_test_run, buildkite_list_failed_executions.

Writes need the user's confirmation: buildkite_create_build, buildkite_rebuild_build, buildkite_retry_failed_jobs, buildkite_retry_job, buildkite_unblock_job and buildkite_create_annotation. Builds run real steps on your agents, including deployments, and use compute. buildkite_unblock_job approves a manual gate, often the one before production: call it only when the user explicitly says so. Say which pipeline, build and branch and call after the user agrees.

Switched off at install: buildkite_cancel_build; it cannot be undone, so an admin switches it on when the team needs it.

Reading answers: states are lower case (passed, failed, running, blocked, canceled). Times are ISO 8601 in UTC. web_url opens the build or job in Buildkite. Test durations are in seconds, reliability is a fraction (0.95 = 95%).

Paging: list tools take page and per_page (up to 100, default 30). When there are more results the answer carries _pagination.nextUrl; call again with the next page (or after for buildkite_list_jobs) until _pagination is missing. Very deep build listings answer 400; narrow them with branch or created_from.

Limits: Buildkite limits REST calls per organization and per user per minute and answers 429 when either is used up; wait the seconds in RateLimit-Reset and try again.

Errors: 401 means the token is wrong, expired or revoked. 403 means the token lacks the scope for the call (check buildkite_get_access_token) or no access to that organization. 404 means a wrong slug, number or id. 422 explains why a build or job cannot be created, retried or unblocked.

Official MCP server: Buildkite also runs its own MCP server at https://mcp.buildkite.com/mcp (OAuth) and https://mcp.buildkite.com/direct (Authorization: Bearer <API token>).

Out of scope here: job environment variables (they hold secrets), deleting logs, artifacts, annotations or pipelines, creating or changing pipelines, clusters, queues and agent tokens, stopping or pausing agents, teams, members, audit events, package registries, and test state changes (mute, skip).