Buildkite MCP Server

The Buildkite MCP Server connects AI assistants to your CI/CD platform Buildkite. Buildkite builds, tests and delivers software through pipelines that run on your own or hosted agents. MCP, the Model Context Protocol, is an open standard through which an assistant such as Claude Code or Cursor calls external tools. According to the documentation, the server exposes product data such as pipelines, builds, jobs and Test Engine data; it is built on the Buildkite REST API and published as an open-source project under the MIT licence. Instead of switching between browser tabs and log output when a build turns red, the assistant can track down the cause itself.

Hosted or local

There are two ways to run it. The hosted server is operated by Buildkite and updated automatically; according to the documentation it suits tools you work with directly from a prompt, but it is not meant for automated workflows that cannot complete interactive OAuth, and it cannot be pinned to a version. The local server runs on your machine or in a container, is yours to maintain, and fits automated workflows that need a fixed server version. For stable behaviour, the documentation recommends a versioned Docker tag or a release binary.

Three endpoints for the hosted server

At https://mcp.buildkite.com/mcp you reach the OAuth server with read and write access. https://mcp.buildkite.com/mcp/readonly is the read-only variant: it allows only tools whose required scope begins with read_, plus tools that need no scope. https://mcp.buildkite.com/direct is intended for headless agents and accepts an API token in the Authorization header; according to the documentation this endpoint is limited to 50 requests per minute per user. With the header X-Buildkite-Toolsets you can additionally restrict the set of tools to groups such as user, pipelines or builds.

What can the Buildkite MCP Server do?

For reading there are tools for the user and organisation, for clusters, queues, agents and pipelines including schedules, for builds, jobs and their environment variables, and for artifacts and annotations. For logs there are search_logs, tail_logs and read_logs; Test Engine provides tests, test runs and failed executions. According to the documentation, cluster secrets are only described and their values are never returned. get_build_failure_summary is particularly handy: the tool gathers problem jobs, log excerpts, error annotations and failed tests in one call, although the result can be partial. The README also describes compare_builds, which compares a failed build with the last passing one on the same branch.

For writing, the documentation lists 21 tools, such as create_build, rebuild_build, cancel_build, retry_job, unblock_job, and creating and changing pipelines, schedules, clusters and queues. Because these can trigger pipeline commands up to and including deployments, the documentation advises allowing write actions only after approval. For retries with limited rights, the README describes a retries toolset that works without the write_builds scope.

Sign-in and permissions

With the hosted server you sign in with your Buildkite account through OAuth; a short-lived token with preset read and write scopes is issued, valid for up to one hour, and refresh tokens last up to 30 days. With the local server and the /direct endpoint, the scope of your API token decides which calls succeed. The documentation points out that read-only mode restricts only that one connection: an agent with shell access and a separately authenticated bk CLI can still make changes.

Costs

The server itself is open source. You can use it with a Buildkite account; according to the pricing page there is a free plan for solo developers and small teams, as well as paid Pro and Enterprise plans. Hosted agents and some quotas incur usage-based charges. Current terms are on Buildkite's pricing page.

Who is the Buildkite MCP Server for?

It is worthwhile for teams that already run their builds on Buildkite and want faster troubleshooting: the assistant reads logs, compares builds and names likely causes without anyone copying output. Start with the read-only endpoint, and allow write access only once you trust the workflow. The documentation notes that tools may change or be removed as the project evolves.

A Buildkite account (for OAuth) or an API token (for /direct and the local server), and an MCP client with HTTP transport, for example Claude Code or Cursor.

With the Buildkite MCP Server, an AI assistant reads pipelines, builds and logs from Buildkite. This guide leads from choosing an endpoint to the first failure analysis.

Step 1: Prerequisites

You need a Buildkite account with access to the organisation you want, and an MCP client with HTTP transport, such as Claude Code or Cursor. If your organisation has an IP allowlist for the API, add Buildkite egress addresses as the documentation describes.

Choose the right endpoint

The hosted server offers three endpoints: /mcp with read and write access, /mcp/readonly for reading only, and /direct for headless agents with an API token. For getting started, /mcp/readonly is the safe choice. With the header X-Buildkite-Toolsets, for example with the value user,pipelines,builds, you restrict the tools further.

Step 2: Connect it to Claude Code

The command is claude mcp add --transport http buildkite https://mcp.buildkite.com/mcp. To preselect an organisation, append ?organization=your-organization to the address. For the read-only variant, register the address https://mcp.buildkite.com/mcp/readonly instead. On first use the OAuth sign-in opens; choose the organisation there and confirm with Authorize. Then check with /mcp that the tools appear.

claude mcp add --transport http buildkite https://mcp.buildkite.com/mcp

First failure analysis

Ask the assistant to investigate a failed build. The get_build_failure_summary tool gathers problem jobs, log excerpts, annotations and failed tests; results can be partial. For details it uses tail_logs or search_logs.

Write access with care

Tools such as retry_job, rebuild_build or create_build can trigger pipeline commands up to and including deployments. Enable them only once you trust the workflow, and have write actions approved in the client. Note that read-only mode restricts only this connection: a separately signed-in bk CLI with write rights is unaffected.

Local instead of hosted

For automated workflows that need a fixed version, the server runs locally or in a container with an API token. According to the documentation, use a versioned Docker tag or a release binary and a token with as few scopes as possible.

OAuth with the Buildkite account (hosted server) or a Buildkite API token (local server and /direct endpoint).

Read: pipelines, builds, jobs, logs, artifacts, annotations, clusters and Test Engine. Write (only on the /mcp endpoint or with a suitable token): start, rebuild and cancel builds, and change pipelines, schedules and clusters.

Build data, logs and environment variables that are read enter the AI client context and therefore reach the model provider. The hosted server is operated by Buildkite.

Write tools can trigger pipeline commands and deployments, logs and job environments can contain secrets, API tokens sit in plain text in configuration files, and log contents can carry prompt injection.