MCP tools overview

MCP tools form the fundamental components of an MCP server, and provide the mechanisms through which AI tools and agents can access a system's APIs, through its MCP server.

Learn more about MCP tools in the Core Server Features and Tools sections of the Understanding MCP servers page in the Model Context Protocol docs.

Available MCP tools

The Buildkite MCP server exposes the following categories of MCP tools.

The names of these tools (for example, list_pipelines) typically do not need to be used in direct prompts to AI tools or agents. However, each MCP tool name is designed to be understandable, so that it can be used directly in a prompt when you want your AI tool or agent to explicitly use that MCP tool to query the Buildkite platform.

As part of configuring your AI tool or agent with the remote or local Buildkite MCP server, you can restrict its access to specific categories of tools using toolsets.

Buildkite recommends configuring your project's AGENTS.md file with a hint to help guide your AI tool or agent to use the Buildkite MCP server and its tools with your project.

While the Buildkite MCP server makes calls to the Buildkite REST API, in some cases only a subset of the resulting fields are returned in the response to your AI tool or agent. This reduces noise for your AI tool or agent and reduces costs associated with text tokenization of the response (also known as token usage).

User, authentication and Buildkite organization

These MCP tools are associated with authentication and relate to querying details about the access token's user and Buildkite organization they belong to.

Tool Description

Tool	Description
`access_token`	Uses the Get the current token REST API endpoint to retrieve information about the current API access token, including its scopes and UUID.
`current_user`	Uses the Get the current user REST API endpoint to retrieve details about the user account that owns the API token, including name, email, avatar, and account creation date. Required token scope: `read_user`.
`user_token_organization`	Uses the Get an organization REST API endpoint to retrieve details about the Buildkite organization associated with the user token used for this request. Required token scope: `read_organizations`.

access_token

Uses the Get the current token REST API endpoint to retrieve information about the current API access token, including its scopes and UUID.

current_user

Uses the Get the current user REST API endpoint to retrieve details about the user account that owns the API token, including name, email, avatar, and account creation date.

Required token scope: read_user.

user_token_organization

Uses the Get an organization REST API endpoint to retrieve details about the Buildkite organization associated with the user token used for this request.

Required token scope: read_organizations.

Buildkite clusters

These MCP tools are used to retrieve details about the clusters and their queues configured in your Buildkite organization, as well as create, update, and pause or resume them. Learn more about clusters in Clusters overview.

Tool	Description
`list_clusters`	Uses the List clusters REST API endpoint to list all clusters in an organization with their names, descriptions, default queues, and creation details. Required token scope: `read_clusters`.
`get_cluster`	Uses the Get a cluster REST API endpoint to retrieve detailed information about a specific cluster including its name, description, default queue, and configuration. Required token scope: `read_clusters`.
`create_cluster`	Uses the Create a cluster REST API endpoint to create a new cluster in an organization. Required token scope: `write_clusters`.
`update_cluster`	Uses the Update a cluster REST API endpoint to update an existing cluster's name, description, emoji, color, or default queue. Required token scope: `write_clusters`.
`list_cluster_queues`	Uses the List queues REST API endpoint to list all queues in a cluster with their keys, descriptions, dispatch status, and agent configuration. Required token scope: `read_clusters`.
`get_cluster_queue`	Uses the Get a queue REST API endpoint to retrieve detailed information about a specific queue including its key, description, dispatch status, and hosted agent configuration. Required token scope: `read_clusters`.
`create_cluster_queue`	Uses the Create a self-hosted queue REST API endpoint to create a new queue in a cluster. Required token scope: `write_clusters`.
`update_cluster_queue`	Uses the Update a queue REST API endpoint to update an existing queue's description or retry agent affinity. Required token scope: `write_clusters`.
`pause_cluster_queue_dispatch`	Uses the Pause a queue REST API endpoint to pause dispatch on a queue, preventing new jobs from being dispatched to agents. Required token scope: `write_clusters`.
`resume_cluster_queue_dispatch`	Uses the Resume a paused queue REST API endpoint to resume dispatch on a paused queue, allowing jobs to be dispatched to agents again. Required token scope: `write_clusters`.

Agents

These MCP tools are used to inspect Buildkite agents in your Buildkite organization.

Tool Description

Tool	Description
`list_agents`	Uses the List agents REST API endpoint to list agents in an organization with their connection state, host details, version, current job, and pause status. Required token scope: `read_agents`.
`get_agent`	Uses the Get an agent REST API endpoint to retrieve details about a specific agent including its connection state, host details, current job, metadata, and pause status. Required token scope: `read_agents`.

list_agents

Uses the List agents REST API endpoint to list agents in an organization with their connection state, host details, version, current job, and pause status.

Required token scope: read_agents.

get_agent

Uses the Get an agent REST API endpoint to retrieve details about a specific agent including its connection state, host details, current job, metadata, and pause status.

Required token scope: read_agents.

Pipelines

These MCP tools are used to retrieve details about existing pipelines in your Buildkite organization, create new pipelines, update existing pipelines, and manage pipeline schedules.

Tool	Description
`list_pipelines`	Uses the List pipelines REST API endpoint to list all pipelines in an organization with their basic details, build counts, and current status. Required token scope: `read_pipelines`.
`get_pipeline`	Uses the Get a pipeline REST API endpoint to retrieve detailed information about a specific pipeline including its configuration, steps, environment variables, and build statistics. Required token scope: `read_pipelines`.
`create_pipeline`	Uses the Create a YAML pipeline REST API endpoint to set up a new CI/CD pipeline in Buildkite with YAML configuration, repository connection, and cluster assignment. Required token scope: `write_pipelines`.
`update_pipeline`	Uses the Update a pipeline REST API endpoint to modify an existing Buildkite pipeline's configuration, repository, settings, or metadata. Required token scope: `write_pipelines`.
`list_pipeline_schedules`	Uses the List pipeline schedules REST API endpoint to list the pipeline schedules for a pipeline, including cron expression, target branch, environment variables, enabled state, and next scheduled build time. Required token scope: `read_pipelines`.
`get_pipeline_schedule`	Uses the Get a pipeline schedule REST API endpoint to retrieve details about a single pipeline schedule including its cron expression, target branch, environment variables, enabled state, last failure, and next build time. Required token scope: `read_pipelines`.
`create_pipeline_schedule`	Uses the Create a pipeline schedule REST API endpoint to create a new pipeline schedule that triggers builds on a cron-driven interval. Required token scope: `write_pipelines`.
`update_pipeline_schedule`	Uses the Update a pipeline schedule REST API endpoint to modify an existing pipeline schedule's cron expression, branch, environment variables, or enabled state. Required token scope: `write_pipelines`.

Builds

These MCP tools are used to retrieve details about existing builds of a pipeline, create new builds, cancel builds, and retry builds.

Tool	Description
`list_builds`	Uses the List all builds REST API endpoint to list all builds for a pipeline with their status, commit information, and metadata. Required token scope: `read_builds`.
`get_build`	Uses the Get a build REST API endpoint to retrieve detailed information about a specific build including its jobs, timing, and execution details. Required token scope: `read_builds`.
`get_build_test_engine_runs`	Gets Test Engine runs data for a specific Buildkite Pipelines build, which can be used to look up test runs. Required token scope: `read_builds`.
`create_build`	Uses the Create a build REST API endpoint to trigger a new build on a Buildkite pipeline for a specific commit and branch, with optional environment variables, metadata, and author information. Required token scope: `write_builds`.
`cancel_build`	Uses the Cancel a build REST API endpoint to cancel a running build on a Buildkite pipeline. Required token scope: `write_builds`.
`rebuild_build`	Uses the Rebuild a build REST API endpoint to rebuild or retry an entire build on a Buildkite pipeline. Required token scope: `write_builds`.

Jobs

These MCP tools are used to retrieve details about jobs from a pipeline build, retry jobs, and unblock jobs in a pipeline build.

Tool Description

Tool	Description
`unblock_job`	Uses the Unblock a job REST API endpoint to unblock a blocked job in a Buildkite build to allow it to continue execution. Required token scope: `write_builds`.
`retry_job`	Uses the Retry a job REST API endpoint to retry a specific job that failed or timed out in a Buildkite build. Required token scope: `write_builds`.
`get_job_env`	Uses the Get a job's environment variables REST API endpoint to retrieve the environment variables for a specific job in a Buildkite build. Required token scope: `read_job_env`.

unblock_job

Uses the Unblock a job REST API endpoint to unblock a blocked job in a Buildkite build to allow it to continue execution.

Required token scope: write_builds.

retry_job

Uses the Retry a job REST API endpoint to retry a specific job that failed or timed out in a Buildkite build.

Required token scope: write_builds.

get_job_env

Uses the Get a job's environment variables REST API endpoint to retrieve the environment variables for a specific job in a Buildkite build.

Required token scope: read_job_env.

Logs

These MCP tools are used to process the logs of jobs, for the benefit of your AI tool or agent. These MCP tools leverage the Buildkite Logs Search & Query Library (used by the Buildkite MCP server), which converts the complex Buildkite logs returned by the Buildkite platform into Parquet file versions of these log files, making the logs more consumable for AI tools, agents and large language models (LLMs).

For improved performance, these Parquet log files are also cached and stored. Learn more about this in Smart caching and storage.

Tool Description

Tool	Description
`search_logs`	Search log entries using regex patterns with optional context lines.
`tail_logs`	Show the last N entries from the log file (that is, N lines for recent errors and status checks).
`read_logs`	Read log entries from the file, optionally starting from a specific row number.

search_logs

Search log entries using regex patterns with optional context lines.

tail_logs

Show the last N entries from the log file (that is, N lines for recent errors and status checks).

read_logs

Read log entries from the file, optionally starting from a specific row number.

Artifacts

These MCP tools are used to retrieve details about artifacts from a pipeline build, as well as obtain the artifacts themselves.

Tool Description

Tool	Description
`list_artifacts_for_build`	Uses the List artifacts for a build REST API endpoint to list a build's artifacts across all of its jobs, including file details, paths, sizes, MIME types, and download URLs. Required token scope: `read_artifacts`.
`list_artifacts_for_job`	Uses the List artifacts for a job REST API endpoint to list an individual job's artifacts, including file details, paths, sizes, MIME types, and download URLs. Required token scope: `read_artifacts`.
`get_artifact`	Uses the Download an artifact REST API endpoint to download a specific artifact's content. The content is returned base64-encoded. Required token scope: `read_artifacts`.

list_artifacts_for_build

Uses the List artifacts for a build REST API endpoint to list a build's artifacts across all of its jobs, including file details, paths, sizes, MIME types, and download URLs.

Required token scope: read_artifacts.

list_artifacts_for_job

Uses the List artifacts for a job REST API endpoint to list an individual job's artifacts, including file details, paths, sizes, MIME types, and download URLs.

Required token scope: read_artifacts.

get_artifact

Uses the Download an artifact REST API endpoint to download a specific artifact's content. The content is returned base64-encoded.

Required token scope: read_artifacts.

Annotations

These MCP tools are used to retrieve details about the annotations resulting from a pipeline build, or create annotations for a build or job.

Tool Description

Tool	Description
`list_annotations`	Uses the List annotations for a build or List annotations for a job REST API endpoint to list annotations for a build or specific job. Required token scope: `read_builds`.
`create_annotation`	Uses the Create an annotation on a build or Create an annotation on a job REST API endpoint to create an annotation on a build or specific job. Required token scope: `write_builds`.

list_annotations

Uses the List annotations for a build or List annotations for a job REST API endpoint to list annotations for a build or specific job.

Required token scope: read_builds.

create_annotation

Uses the Create an annotation on a build or Create an annotation on a job REST API endpoint to create an annotation on a build or specific job.

Required token scope: write_builds.

Test Engine

These MCP tools are used to retrieve details about Test Engine tests and their runs from a test suite, along with other Test Engine-related data.

Tool	Description
`get_test`	Uses the Get a test REST API endpoint to retrieve a specific test in Buildkite Test Engine. This provides additional metadata for failed test executions. Required token scope: `read_suites`.
`list_test_runs`	Uses the List all runs REST API endpoint to list all test runs for a test suite in Buildkite Test Engine. Required token scope: `read_suites`.
`get_test_run`	Uses the Get a run REST API endpoint to retrieve a specific test run in Buildkite Test Engine. Required token scope: `read_suites`.
`get_failed_executions`	Uses the Get failed execution data REST API endpoint to retrieve failed test executions for a specific test run in Buildkite Test Engine. Optionally retrieves the expanded failure details such as full error messages and stack traces. Required token scope: `read_suites`.

Smart caching and storage

To improve performance in accessing log data from the Buildkite platform, the Buildkite MCP server downloads and stores the logs of jobs in Parquet file format to either of the following areas.

For the local MCP server, on the file system of the machine running the MCP server.
For the remote MCP server, in a dedicated area of the Buildkite platform.

These Parquet log files are stored and managed by the MCP server and all interactions with these files are managed by the MCP server's log tools.

If the job is in a terminal state (for example, the job was completed successfully, had failed, or was canceled), then the job's Parquet format logs are downloaded and stored indefinitely.

If the job is in a non-terminal state (for example, the job is still running or is blocked), then the job's Parquet logs are retained for 30 seconds.

Storage locations

If you are running the local MCP server, the following table indicates the default locations for these Parquet log files.

Environment Default Parquet log file location

Environment	Default Parquet log file location
A physical machine (for example, a desktop or laptop computer)	The `.bklog` sub-directory of the home directory.
A containerized environment (for example, using Docker or Kubernetes)	The `/tmp/bklog` sub-directory of the file system's root directory level.

A physical machine (for example, a desktop or laptop computer)

The .bklog sub-directory of the home directory.

A containerized environment (for example, using Docker or Kubernetes)

The /tmp/bklog sub-directory of the file system's root directory level.

You can override these default Parquet log file locations through the $BKLOG_CACHE_URL environment variable, which can be used with either a local file system path or an s3:// path, where the latter may be better suited for pipeline usage, for example:

# Local development with persistent cache
export BKLOG_CACHE_URL="file:///Users/me/bklog-cache"

# Shared cache across build agents
export BKLOG_CACHE_URL="s3://ci-logs-cache/buildkite/"

The AGENTS.md file

The AGENTS.md file is used to help guide your AI tool or agent to work on a project. Depending on which AI tool or agent you use, this file might use a different name, such as CLAUDE.md for Claude Code.

Buildkite recommends configuring your project's AGENTS.md file by adding a hint like the following to help your AI tool or agent to use the Buildkite MCP server and its tools with your project:

- **CI/CD**: `my-buildkite-organization` Buildkite organization, `my-pipeline` pipeline slug for build and test (`.buildkite/pipeline.yml`), `my-pipeline-release` pipeline slug for releases (`.buildkite/pipeline.release.yml`)

You should replace your Buildkite organization, pipeline slugs, and pipeline file names with those applicable to your project.

Add this hint to an appropriate section within your AGENTS.md file. For example, for a typical development project, you might add this hint to a series of existing ones in a section about architecture.