# Buildkite MCP
> Official MCP server exposing Buildkite pipeline, build, job, test, artifact, and log data to AI tools.
Canonical: https://www.mcpfolio.com/servers/buildkite
Last updated: 2026-10-28
## Catalog record

- Publisher: Buildkite
- Categories: search

## Website

https://buildkite.com/docs/apis/mcp-server

## Repository

https://github.com/buildkite/buildkite-mcp-server

## Transports

stdio (local), Streamable HTTP (remote)

## Authentication

API-backed tools require a Buildkite API access token. HTTP mode can authenticate each request with Authorization pass-through; server should sit behind an authenticating reverse proxy.

## Tools

- **access_token**: Get information about the current API access token including its scopes and UUID
- **cancel_build**: Cancel a running build on a Buildkite pipeline
- **cancel_job**: Cancel a single command job without canceling the rest of its build; use cancel_build to cancel a whole build. Only command jobs that are scheduled, reserved, assigned, accepted, or running can be canceled. A job that has not started becomes 'canceled'; a running job becomes 'canceling' until its agent stops it. Returns the updated job
- **compare_builds**: Compare step outcomes, final-attempt retry counts and execution/scheduling times between builds in one pipeline. Defaults to the most recently created earlier successful build on the same branch; baseline_build_number overrides this. Matches step keys or, for unkeyed jobs, unique exact names with matching type, group, matrix and parallel coordinates. match_method identifies heuristic name_fallback matches; ambiguous or unnamed unkeyed jobs remain unmatched. A change in soft_failed (a failure allowed by soft_fail, which does not block the build) is state_changed, never newly_failing or recovered. Returns at most 100 comparisons, prioritizing failures, and optional bounded log evidence for up to three newly blocking failures: newly_failing jobs, then state_changed jobs that are now hard failures (for example soft-failed before). Scans at most 1000 jobs per build; refuses incomplete inventories. Historical co-occurrence does not prove a cause or that retrying is safe. Use get_build_failure_summary for deeper failure diagnosis.
- **create_annotation**: Create an annotation on a build or specific job. Use scope='build' (default) or scope='job' with job_id
- **create_build**: Trigger a new build on a Buildkite pipeline for a specific commit and branch, with optional environment variables, metadata, and author information
- **create_cache_registry**: Create a cache registry in a cluster. Optional metadata and policy may be omitted, set, or explicitly cleared
- **create_cluster**: Create a new cluster in an organization
- **create_cluster_queue**: Create a new queue in a cluster
- **create_cluster_secret**: Create cluster secret
- **create_pipeline**: Set up a new CI/CD pipeline in Buildkite with YAML configuration or an approved pipeline template, repository connection, and cluster assignment
- **create_pipeline_schedule**: Create a new pipeline schedule that triggers builds on a cron-driven interval
- **create_pipeline_webhook**: Create a GitHub webhook for an existing pipeline configured with a compatible Buildkite GitHub App
- **current_user**: Get details about the user account that owns the API token, including name, email, avatar, and account creation date
- **disable_pipeline_github_webhook_processing**: Disable traditional GitHub webhook processing and return its state to avoid duplicate builds during cutover. Requires Full Access to a GitHub or GitHub Enterprise pipeline and expanded-webhook enrollment; unavailable controls return 404. Does not delete repository webhooks or disable dedicated GitHub Actions triggers
- **enable_pipeline_github_webhook_processing**: Enable traditional GitHub webhook processing and return its state. Requires Full Access to a GitHub or GitHub Enterprise pipeline and expanded-webhook enrollment; unavailable controls return 404. Does not create repository webhooks or change dedicated GitHub Actions triggers
- **get_agent**: Get detailed information about a specific agent including its connection state, host details, current job, metadata, and pause status
- **get_artifact**: Get a specific artifact by organization, pipeline, build, job, and artifact identifiers. Text artifacts under 64 KiB are returned inline in `content`; larger or binary artifacts return metadata plus a short-lived `download_url`. When `download_url_auth` is \"none\" the URL is presigned (a buildkiteartifacts.com S3 link) — fetch it with a plain GET and NO Authorization header. It expires after `download_url_expires_in_seconds`; if it has expired, call this tool again for a fresh URL.
- **get_build**: Get a single build with lightweight annotation summaries. Annotation bodies and jobs are not included — use list_annotations to read annotations, list_jobs or get_job for job detail, and list_step_uploads to see the dynamic pipeline configuration the build received via `buildkite-agent pipeline upload`
- **get_build_failure_summary**: Diagnose a Buildkite build failure in one call. Returns build.state, build.job_state_counts tallying every job in the build by state (when present, use it to confirm the returned problem jobs are the build's only problems without calling list_jobs), terminal problem jobs, canceled jobs, promised failures from running jobs, soft-failed jobs (soft_failed true: ran and failed, but the step's soft_fail setting in the pipeline allowed that exit status, so they did not block the build; soft_failed is authoritative, so the pipeline configuration is not needed; listed after blocking failures and canceled jobs — not proof the problem is harmless, but do not dig into their logs, retry, or fix them unless the user asks or evidence links them to the reported failure), and — unless include_never_ran_jobs is false, using the remaining max_jobs slots — the jobs that never ran (waiting_failed/blocked_failed/unblocked_failed stopped by a failed dependency, broken excluded by pipeline configuration — no logs, never the cause), and size-bounded diagnostic content from logs, annotations, and failed Test Engine tests. Each terminal failed or timed-out job carries failed_tests (only enabled tests whose every execution within that job failed, with failure_reason joined from that job's newest failed execution) and failed_tests_status ('found', 'none_recorded', 'ingestion_pending', or 'unavailable'); an empty or absent failed_tests list does NOT mean the job's tests passed — follow the job's failed_tests_hint and treat the job's log_tail as the authoritative fallback. A failed test with failure_detail_status 'not_retrieved' had no execution fetched for its job; when it carries both test_suite_slug and run_id, call get_failed_executions with them for the detail (page past the first 100 if needed). When run_id is absent, the suite lists several runs for this build or none: use get_build_test_engine_runs to list them and query each. Each failed test also carries its Test Engine labels, such as 'flaky', and executions_count_by_result for its attempts within that job (failed: 2 means the first run and a retry both failed, which is why the job log can report more failures than failed_tests lists), so there is no need to call a test tool or get_failed_executions for them. If a failed test is labeled 'flaky', do not stop at the label: trace the actual error (failure_reason, failure_expanded, or the job log) and propose a permanent fix. Never conclude a failure is flaky from a PR or commit title alone. Retry the job with retry_job only when the user explicitly permits it. Annotation content is in the body_html field; there is no body field. Start with this tool before calling individual job, log, annotation, or test tools.
- **get_build_test_engine_runs**: Get test engine runs data for a specific build in Buildkite. This can be used to look up Test Runs.
- **get_cache_registry**: Get a cache registry by UUID, including its structured access policy
- **get_cluster**: Get detailed information about a specific cluster including its name, description, default queue, and configuration
- **get_cluster_queue**: Get detailed information about a specific queue including its key, description, dispatch status, and hosted agent configuration
- **get_cluster_secret**: Get cluster secret information
- **get_failed_executions**: Get failed test executions for a specific test run in Buildkite Test Engine. Optionally get the expanded failure details such as full error messages and stack traces.
- **get_job**: Get a single job by its UUID. Provide 'pipeline_slug' and 'build_number' for a build-scoped lookup, or omit both to look the job up by organization and job ID alone
- **get_job_env**: Get the environment variables for a specific job in a Buildkite build
- **get_pipeline**: Get detailed information about a specific pipeline including its configuration, steps, environment variables, and build statistics
- **get_pipeline_github_webhook_processing**: Get traditional GitHub webhook processing state. Requires Full Access to a GitHub or GitHub Enterprise pipeline and expanded-webhook enrollment; unavailable controls return 404. Does not describe dedicated GitHub Actions triggers
- **get_pipeline_schedule**: Get detailed information about a single pipeline schedule including its cron expression, target branch, environment variables, enabled state, last failure, and next build time
- **get_repository_connection**: Get a repository connection's service account, host, and provider rate limit. rate_limit is the cached GitHub installation core API quota for this connection (limit, used, remaining, reset_at), not the Buildkite API rate limit; it is null when the quota is unavailable or does not apply to the connection type. If reset_at is in the past, the quota has reset since it was cached, so treat used and remaining as stale. Requires organization administrator access
- **get_step_upload**: Get a single dynamic pipeline upload including its pipeline definition rendered as YAML (definition_yaml). Definitions over the API's render limit are omitted: definition_yaml is omitted, definition_yaml_omitted is true and definition_bytes reports the size. Only available while the build is within its maximum lifetime (~30 days); older builds return 410 Gone
- **get_test**: Get a specific test in Buildkite Test Engine, including execution metrics aggregated over a selected time window. This provides additional metadata for failed test executions. The response also includes transition_count_score and probabilistic_flakiness_score, which help judge whether a failure is flaky. Each score is absent unless the suite has a monitor of that type and the monitor has scored the test. The time window does not apply to them.
- **get_test_run**: Get a specific test run in Buildkite Test Engine
- **get_test_workflow**: Inspect a configured Buildkite Test Engine workflow by UUID, including its monitor conditions, filters, alarm/recovery actions, and links. Webhook endpoints are always redacted. Describes configured behavior, not event history or proof that an action ran.
- **list_agents**: List agents in an organization with their connection state, host details, version, current job, and pause status
- **list_annotations**: List annotations for a build or a specific job. Use scope='build' (default) or scope='job' with job_id. Annotation content is in the body_html field; there is no body field
- **list_artifacts_for_build**: List all artifacts for a build across all jobs, including filenames, paths, sizes, and MIME types. Output can be large for big builds — use per_page and paginate. To fetch an artifact's contents or a download URL, call get_artifact with that artifact's id and job_id.
- **list_artifacts_for_job**: List all artifacts for an individual job, including filenames, paths, sizes, and MIME types. To fetch an artifact's contents or a download URL, call get_artifact with that artifact's id and job_id.
- **list_builds**: List builds, newest first, for a pipeline or, when pipeline_slug is omitted, across all pipelines in an organization. Returns lightweight summaries including pipeline_slug, creator and finished_at; jobs are not included — use list_jobs or get_job for job detail. Org-wide listings without created_from can time out. For questions spanning many builds, filter by state, branch, creator and date with per_page 100 instead of calling get_build per build
- **list_cache_registries**: List cache registries in a cluster, ordered by slug. Returns items and cursor pagination links
- **list_cluster_queues**: List all queues in a cluster with their keys, descriptions, dispatch status, and agent configuration
- **list_cluster_secrets**: List cluster secrets
- **list_clusters**: List all clusters in an organization with their names, descriptions, default queues, and creation details
- **list_jobs**: List jobs for a Buildkite build, returning an actionable summary by default. For CI failure diagnosis, use state='failed,timed_out,expired' to avoid returning successful jobs, and investigate jobs without soft_failed first: soft_failed true means the job ran and failed but soft_fail allowed its exit status, so it did not block the build. Broken jobs never ran because pipeline configuration excluded them; they are not failures. Use detail_level='detailed' for execution metadata or 'full' for the existing full MCP job response. Returns 'items' and cursor pagination 'links'
- **list_pipeline_schedules**: List the pipeline schedules for a pipeline, including cron expression, target branch, environment variables, enabled state, and next scheduled build time
- **list_pipelines**: List all pipelines in an organization with their basic details, build counts, and current status
- **list_repository_connections**: List an organization's source control repository connections, such as GitHub apps, Bitbucket Server, and GitLab Self-Managed. Returns all connections unpaginated with id, type, display_name, and url only; use get_repository_connection for host details and GitHub provider rate limits. Requires organization administrator access
- **list_skills**: List available skill guides that document usage patterns, pitfalls, and workflows for Buildkite MCP tools
- **list_step_uploads**: List the dynamic pipeline uploads (`buildkite-agent pipeline upload`) a build received, newest first, without their definitions. Each item includes state, the uploading job (source_job_id), created_jobs_count (omitted until applied, 0 when applied but no jobs were created), and rejection details. Use get_step_upload to read an upload's pipeline definition. Only available while the build is within its maximum lifetime (~30 days); older builds return 410 Gone
- **list_test_runs**: List all test runs for a test suite in Buildkite Test Engine
- **list_test_suites_for_pipeline**: List the Buildkite Test Engine suites that have recorded at least one run attributed to a pipeline, ordered by creation time. Use this to find the test_suite_slug needed by the other Test Engine tools.
- **list_test_workflows**: List configured workflows for a Buildkite Test Engine suite, newest first. Returns monitors, filters, alarm/recovery actions, and links. Webhook endpoints are always redacted. Use this to discover automation and labels used to mark flaky tests before querying list_tests. Use get_test_workflow to inspect one. Configuration does not prove an action ran or rank tests by flakiness.
- **list_tests**: List tests in a Buildkite Test Engine suite with execution metrics aggregated over a selected time window. Supports filtering, metric sorting, and pagination.
- **list_tests_for_build**: List tests and their execution metrics for a Buildkite build. Requires the build UUID (the build ID, not the pipeline build number) and supports filtering, metric sorting, and pagination.
- **load_skill**: Load the full content of a skill guide by name
- **pause_cluster_queue_dispatch**: Pause dispatch on a cluster queue, preventing new jobs from being dispatched to agents
- **read_execution_trace**: Read an OpenTelemetry trace summary for a Buildkite Test Engine execution, including category rollups and slowest spans
- **read_logs**: Read log entries from the file, optionally starting from a specific row number. ALWAYS use 'limit' parameter to avoid excessive tokens. For recent failures, use 'tail_logs' instead. Recommended limits: investigation (100-500), exploration (use seek + small limits). The json format: {ts: timestamp_ms, c: content, rn: row_number}.
- **rebuild_build**: Rebuild/retry an entire build on a Buildkite pipeline
- **resume_cluster_queue_dispatch**: Resume dispatch on a paused cluster queue, allowing jobs to be dispatched to agents again
- **retry_failed_jobs**: Retry the failed jobs in a build that are safe to retry, and report every job retried or skipped with a reason. Unlike the Buildkite REST API's retry_failed_jobs endpoint, which retries every job in the chosen failure states, this classifies each job and retries it individually. Only infrastructure failures are retried: expired, agent_lost (exit status -1 with no signal reason), agent_stop, agent_refused and stack_error. Soft-failed, canceled and timed-out jobs, command failures and other signal reasons are skipped because a retry would likely fail again or undo a deliberate stop. Use retry_job to retry a skipped job after inspecting it
- **retry_job**: Retry a specific failed or timed out job in a Buildkite build
- **search_logs**: Search log entries using regex patterns with optional context lines. For recent failures, try 'tail_logs' first, then use search_logs with patterns like 'error|failed|exception' and limit: 10-20. The json format: {ts: timestamp_ms, c: content, rn: row_number}.
- **set_default_cache_registry**: Set a cluster's default cache registry by UUID. A cluster always has a default, so this switches it to another registry in the same cluster rather than clearing it. Returns the updated cluster
- **slowest_executions_for_build**: List the slowest test executions for a Buildkite build across every visible Test Engine suite, slowest first. Returns the identifiers needed by read_execution_trace and whether each execution has a trace.
- **tail_logs**: Show the last N entries from the log file. RECOMMENDED for failure diagnosis - most build failures appear in the final log entries. More token-efficient than read_logs for recent issues. The json format: {ts: timestamp_ms, c: content, rn: row_number}.
- **unblock_job**: Unblock a blocked job in a Buildkite build to allow it to continue execution
- **update_cache_registry**: Update a cache registry by UUID. Omitted fields remain unchanged; nullable metadata and policy may be set or explicitly cleared
- **update_cluster**: Update an existing cluster's name, description, emoji, color, or default queue
- **update_cluster_queue**: Update an existing cluster queue's description or retry agent affinity
- **update_pipeline**: Modify an existing Buildkite pipeline's configuration, repository, settings, or metadata
- **update_pipeline_schedule**: Modify an existing pipeline schedule's cron expression, branch, environment variables, or enabled state
- **user_token_organization**: Get the organization associated with the user token used for this request
- **validate_pipeline**: Validate Buildkite pipeline YAML against the official pipeline schema without calling the Buildkite API. Use this to check a pipeline definition (e.g. .buildkite/pipeline.yml) before creating or updating a pipeline, or before committing pipeline changes
- **wait_for_build**: Wait for a build to reach a terminal state (passed, failed, canceled, skipped, not_run, or blocked on a block step), polling for up to 45 seconds. Returns finished=true along with the build once it settles. If the build is still in progress when the window closes it returns finished=false and the current state only, with no build detail — call this tool again to keep waiting. Judge a long build by build_elapsed_seconds, which counts from the build's own start time and does not reset between calls; waited_seconds covers only the latest call. Do not wait indefinitely: after roughly ten consecutive calls, stop and report the build as still running with its elapsed time rather than continuing to poll. Jobs and annotation bodies are never included — use list_jobs or get_job for job detail, and list_annotations to read annotations

## Sources

- [official_tool_reference](https://buildkite.com/docs/apis/mcp-server/tools)
- [official_current_implementation_tool_catalog](https://github.com/buildkite/buildkite-mcp-server/tree/bfc2462b0500aff39d81ab56a22e4a7bce95618c)
- [official_release_notes](https://buildkite.com/resources/changelog/)
- [official_toolset_configuration](https://buildkite.com/docs/apis/mcp-server/tools/toolsets)

## Setup

Use the interactive setup panel on [the detail page](https://www.mcpfolio.com/servers/buildkite) to view instructions for each supported client.