Buildkite MCP server overview

The Model Context Protocol (MCP) is an open protocol standard on how to connect artificial intelligence (AI) tools, agents and models to a variety of other systems and data sources.

Buildkite provides its own open-source MCP server to expose Buildkite product data (for example, data from pipelines, builds, and jobs for Pipelines, including test data for Test Engine) for AI tools, editors, agents, and other products to interact with.

Buildkite's MCP server is built on and interacts with the Buildkite REST API. Learn more about what the MCP server is capable of in Available MCP tools.

To start using Buildkite's MCP server, first determine which type of Buildkite MCP server to work with. This next section provides an overview of the differences between these MCP server types and how they need to be configured.

Once you have established which Buildkite MCP server to use (remote or local) and if local, have installed the MCP server and configured its API access token, you can then proceed to configure your AI tools to work with the remote (recommended) or local MCP server.

Types of MCP servers

Buildkite provides both a remote and local MCP server.

Remote MCP server

The remote MCP server is one that Buildkite hosts, and is available for all users to access at the following URL:

https://mcp.buildkite.com/mcp

This type of MCP server is typically used by AI tools that you interact with directly from a prompt, and is the recommended MCP server type to use.

What it's suitable for

The remote MCP server is suitable for personal usage with an AI tool, as it has the following advantages for this use case.

You don't need to configure an API access token, which poses a potential security risk if leaked.

Instead, you only require a Buildkite user account, and the Buildkite platform issues a short-lived OAuth access token, representing this user account for authentication, along with access permission scopes which are pre-set by the Buildkite platform to provide the authorization. This OAuth token auth process takes place after configuring your AI tool with the remote MCP server and connecting to it.

Note: OAuth access tokens are valid for 12 hours, and the refresh tokens are valid for seven days.
There is no need to install or upgrade any software. Since the remote MCP server undergoes frequent updates, you get access to new features and fixes automatically.

What it's not suitable for

The remote MCP server is not suitable for use in automated workflows, where running a specific version of the MCP server is important for generating consistent results.

Local MCP server

The local MCP server is one that you install yourself directly on your own machine or in a containerized environment.

This type of MCP server is typically used by AI tools used as AI agents, which an automated system or workflow, such as a Buildkite pipeline, can interact with. AI agent interactions are usually shell-based.

What it's suitable for

The local MCP server enables automated workflows (for example, using Buildkite Pipelines), where running a specific version of the MCP server is important for generating consistent results.

Also, if you want to contribute to the Buildkite MCP server project, the local MCP server allows you to run and test your changes locally.

What it's not suitable for

The local MCP server is not suitable for personal usage with an AI tool, as it has the following disadvantages.

Since your Buildkite API access token is used for authentication and authorization to the MCP server, you'll need to manage the security (for example, leak prevention) of this token and its storage in plain text.
You'll also need to manage upgrades to the MCP server yourself, especially if you choose to install the binary version of the local MCP server, which means you may miss out on new and updated features offered automatically through the remote MCP server.

If you intend to use the local Buildkite MCP server, learn more about how to set up and install it in Installing the Buildkite MCP server.

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.

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.

While Buildkite's MCP server makes calls to the Buildkite REST API, note that in some cases, only a subset of the resulting fields are returned in the response to your AI tool or agent. This is done to reduce noise for your AI tool / agent, as well as reduce costs associated with text tokenization of the response.

User and authentication

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`	Get information about the current API access token including its scopes and UUID. See Get the current token of the REST API docs for more information.
`current_user`	Get details about the user account that owns the API token, including name, email, avatar, and account creation date. See Get the current user of the REST API docs for more information.
`user_token_organization`	Get the organization associated with the user token used for this request. See Get an organization of the REST API docs for more information.

access_token

Get information about the current API access token including its scopes and UUID.

See Get the current token of the REST API docs for more information.

current_user

Get details about the user account that owns the API token, including name, email, avatar, and account creation date.

See Get the current user of the REST API docs for more information.

user_token_organization

Get the organization associated with the user token used for this request.

See Get an organization of the REST API docs for more information.

Organizations and clusters

These MCP tools are used to retrieve details about the clusters and their queues configured in your Buildkite organization. Learn more about clusters in Clusters overview.

Tool	Description
`list_clusters`	List all clusters in an organization with their names, descriptions, default queues, and creation details. See List clusters of the REST API docs for more information.
`get_cluster`	Get detailed information about a specific cluster including its name, description, default queue, and configuration. See Get a cluster of the REST API docs for more information.
`list_cluster_queues`	List all queues in a cluster with their keys, descriptions, dispatch status, and agent configuration. See List queues of the REST API docs for more information.
`get_cluster_queue`	Get detailed information about a specific queue including its key, description, dispatch status, and hosted agent configuration. See Get a queue of the REST API docs for more information.

Pipelines

These MCP tools are used to retrieve details about existing pipelines in your Buildkite organization, as well as create new pipelines, and update existing ones.

Tool	Description
`list_pipelines`	List all pipelines in an organization with their basic details, build counts, and current status. See List pipelines of the REST API docs for more information.
`get_pipeline`	Get detailed information about a specific pipeline including its configuration, steps, environment variables, and build statistics. See Get a pipeline of the REST API docs for more information.
`create_pipeline`	Set up a new CI/CD pipeline in Buildkite with YAML configuration, repository connection, and cluster assignment. See Create a YAML pipeline of the REST API docs for more information.
`update_pipeline`	Modify an existing Buildkite pipeline's configuration, repository, settings, or metadata. See Update a pipeline of the REST API docs for more information.

Builds

These MCP tools are used to retrieve details about existing builds of a pipeline, as well as create new builds, and wait for a specific build to finish.

Tool	Description
`list_builds`	List all builds for a pipeline with their status, commit information, and metadata. See List all builds of the REST API docs for more information.
`get_build`	Get detailed information about a specific build including its jobs, timing, and execution details. See Get a build of the REST API docs for more information.
`create_build`	Trigger a new build on a Buildkite pipeline for a specific commit and branch, with optional environment variables, metadata, and author information. See Create a build of the REST API docs for more information.
`wait_for_build`	Wait for a specific build to completed. This tool calls the Get a build endpoint to return the status of the build from its logs. If the build is still running, `wait_for_build` calls the Get a build endpoint with increasingly less frequency, to reduce text tokenization usage and traffic, until the returned build status is completed. See Get a build of the REST API docs for more information.

Jobs

These MCP tools are used to retrieve the logs of jobs from a pipeline build, as well as unblock jobs in a pipeline build. A job's logs can then be processed by the logs tools of the MCP server, for the benefit of your AI tool or agent.

Tool Description

Tool	Description
`get_job_logs`	Get the log output and metadata for a specific job, including content, size, and header timestamps. Automatically saves to file for large logs to avoid token limits. See Get a job's log output of the REST API docs for more information.
`unblock_job`	Unblock a blocked job in a Buildkite build to allow it to continue execution. See Unblock a job of the REST API docs for more information.

get_job_logs

Get the log output and metadata for a specific job, including content, size, and header timestamps. Automatically saves to file for large logs to avoid token limits.

See Get a job's log output of the REST API docs for more information.

unblock_job

Unblock a blocked job in a Buildkite build to allow it to continue execution.

See Unblock a job of the REST API docs for more information.

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
`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).
`get_logs_info`	Get metadata and statistics about the Parquet log file.
`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`	List a build's artifacts across all of its jobs, including file details, paths, sizes, MIME types, and download URLs. See List artifacts for a build of the REST API docs for more information.
`get_artifact`	Get detailed information about a specific artifact including its metadata, file size, SHA-1 hash, and download URL. See Get an artifact of the REST API docs for more information.

list_artifacts

List a build's artifacts across all of its jobs, including file details, paths, sizes, MIME types, and download URLs.

See List artifacts for a build of the REST API docs for more information.

get_artifact

Get detailed information about a specific artifact including its metadata, file size, SHA-1 hash, and download URL.

See Get an artifact of the REST API docs for more information.

Annotations

These MCP tools are used to retrieve details about the annotations resulting from a pipeline build.

Tool Description

Tool	Description
`list_annotations`	List all annotations for a build, including their context, style (success/info/warning/error), rendered HTML content, and creation timestamps. See List annotations for a build of the REST API docs for more information.

list_annotations

List all annotations for a build, including their context, style (success/info/warning/error), rendered HTML content, and creation timestamps.

See List annotations for a build of the REST API docs for more information.

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`	Get a specific test in Buildkite Test Engine. This provides additional metadata for failed test executions. See Get a test of the REST API docs for more information.
`list_test_runs`	List all test runs for a test suite in Buildkite Test Engine. See List all runs of the REST API docs for more information.
`get_test_run`	Get a specific test run in Buildkite Test Engine. See Get a run of the REST API docs for more 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. See Get failed execution data of the REST API docs for more information.
`get_build_test_engine_runs`	Get Test Engine runs data for a specific build in Buildkite Pipelines. This can be used to look up test runs.

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
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/"