Toolsets

The Buildkite MCP server organizes its MCP tools into logical groups of toolsets, each of which can be selectively enabled on the MCP server, based on your requirements.

Available toolsets

Each toolset groups related MCP tools, which interact with specific areas of the Buildkite platform. You can enable these individual toolsets by configuring them for the remote or local Buildkite MCP server. Doing so effectively restricts your AI tool's or agent's access to the Buildkite API, based on each set of MCP tools made available through the MCP server's configured toolsets.

Toolset (name)	Description	Tools
`user`	User, authentication, and Buildkite organization	`current_user`, `user_token_organization`, `access_token`
`clusters`	Buildkite clusters management	`get_cluster`, `list_clusters`, `get_cluster_queue`, `list_cluster_queues`
`pipelines`	Pipelines management	`get_pipeline`, `list_pipelines`, `create_pipeline`, `update_pipeline`
`builds`	Builds operations	`list_builds`, `get_build`, `create_build`, `wait_for_build`, `get_jobs`, `unblock_job`
`logs`	Logs processing	`search_logs`, `tail_logs`, `read_logs`, `get_logs_info`
`artifacts`	Artifacts management	`list_artifacts`, `get_artifact`
`annotations`	Annotations management	`list_annotations`
`tests`	Test Engine	`list_test_runs`, `get_test_run`, `get_failed_executions`, `get_test`

Configuring the remote MCP server

You can configure toolset availability for the remote MCP server by adding the required toolset names as part of an extension to the remote MCP server's URL (for a single toolset only), or alternatively, and for multiple toolsets, as part of the header of requests sent to the Buildkite platform from the remote MCP server.

You can also configure read-only access to the remote MCP server as part of this process, and when configuring multiple toolsets, be selective over which ones have read-only access.

Using a URL extension

When configuring your AI tool with the remote MCP server, you can enable a single toolset by appending /x/{toolset.name} to the end of the remote MCP server URL (https://mcp.buildkite.com/mcp), where {toolset.name} is the name of the toolset you want to enable. To enforce read-only access, append /readonly to the end of /x/{toolset.name}.

Examples

To enable the builds toolset for the remote MCP server, configure your AI tool with the following URL:

https://mcp.buildkite.com/mcp/x/builds

To enforce read-only access to this remote MCP server toolset, configure your AI tool with this URL instead:

https://mcp.buildkite.com/mcp/x/builds/readonly

The remote MCP server URL https://mcp.buildkite.com/mcp without any further extension provides unrestricted access to the Buildkite API, restricted only by all applicable token scopes available to your Buildkite user account's access token, and what you can access on the Buildkite platform.

Using headers

When configuring your AI tool with the remote MCP server, you can enable one or more toolsets by specifying their toolset names as a single-line comma-separated list value for the X-Buildkite-Toolsets header of requests sent to the Buildkite platform from the remote MCP server. To enforce read-only access, also add the X-Buildkite-Readonly header with a value of true.

Examples

To enable the builds toolset for the remote MCP server, configure your AI tool with the standard remote MCP server URL:

https://mcp.buildkite.com/mcp

along with the following request header:

X-Buildkite-Toolsets: builds

To enable the user, pipelines, and builds toolsets for the remote MCP server, configure your AI tool with the standard remote MCP server URL, and the following request header:

X-Buildkite-Toolsets: user,pipelines,builds

To enforce read-only access across all of these toolsets, use the following request headers:

X-Buildkite-Toolsets: user,pipelines,builds
X-Buildkite-Readonly: true

You can also be selective with read-only access to toolsets.

Learn more about how to configure different AI tools with these header configurations in Configuring AI tools with the remote MCP server.

Omitting the X-Buildkite-Toolsets and X-Buildkite-Readonly headers from these configurations provides unrestricted access to the Buildkite API, restricted only by all applicable token scopes available to your Buildkite user account's access token, and what you can access on the Buildkite platform.

Selective read-only access to toolsets

If you want to enable multiple toolsets, but be selective over which ones of these have read-only access, you'll need to create two remote MCP server configurations (using headers) for your AI tool—one for toolsets with both read and write access, and the other for toolsets with read-only access.

Examples

To enable the user and pipelines toolsets with read-only access, and the builds toolset with both read and write access, create two remote MCP server configurations with the standard URL:

https://mcp.buildkite.com/mcp

For the user and pipelines toolsets with read-only access to the remote MCP server, implement the request header:

X-Buildkite-Toolsets: user,pipelines
X-Buildkite-Readonly: true

And for the builds toolset with read and write access to the remote MCP server, implement the request header:

X-Buildkite-Toolsets: builds

You could also use the URL extension approach to do this by implementing three separate remote MCP server configurations, each of whose URLs are respectively:

https://mcp.buildkite.com/mcp/x/user/readonly
https://mcp.buildkite.com/mcp/x/pipelines/readonly
https://mcp.buildkite.com/mcp/x/builds

Ensure you provide an appropriate name for each MCP server configuration to make it easier to identify which toolsets and level of access each server has to the Buildkite API.

For example, instead of buildkite as an MCP server configuration name, use more descriptive names, for example: buildkite-read-only-user-pipelines-toolsets and buildkite-builds-toolset.

Configuring the local MCP server

You can configure toolset availability for the local MCP server by adding the required toolset names as part of an environment variable or command-line flag when either the Docker or binary version of the local MCP server is started.

You can also configure read-only access to the local MCP server as part of this process, and when configuring multiple toolsets, be selective over which ones have read-only access.

Using Docker

When configuring your AI tool with the local MCP server running in Docker, you can enable one or more toolsets by adding the BUILDKITE_TOOLSETS environment variable to the docker run command, and specifying the toolset names as a comma-separated list value for this variable. To enforce read-only access, also add the BUILDKITE_READ_ONLY environment variable with a value of true to this command.

Examples

To enable the builds toolset for the local MCP server, configure the docker run command with:

docker run --rm -e BUILDKITE_API_TOKEN=bkua_xxxxx -e BUILDKITE_TOOLSETS="builds" buildkite/mcp-server stdio

To enable the user, pipelines, and builds toolsets for the local MCP server, and enforce read-only access across all of these toolsets, configure the docker run command with:

docker run --rm -e BUILDKITE_API_TOKEN=bkua_xxxxx -e BUILDKITE_TOOLSETS="user,pipelines,builds" -e BUILDKITE_READ_ONLY="true" buildkite/mcp-server stdio

You can also be selective with read-only access to toolsets.

Most AI tool or agent configurations for the local MCP server require configuring the docker run command's environment variables with both an args array and env object in its JSON configuration file. Hence, the example above would be configured in these JSON files as:

{
  ...
    "buildkite-read-only-toolsets": {
      "command": "docker",
      "args": [
        "run", "--pull=always", "-q", "-i", "--rm",
        "-e", "BUILDKITE_API_TOKEN",
        "-e", "BUILDKITE_TOOLSETS",
        "-e", "BUILDKITE_READ_ONLY",
        "buildkite/mcp-server",
        "stdio"
      ],
      "env": {
        "BUILDKITE_API_TOKEN": "bkua_xxxxx",
        "BUILDKITE_TOOLSETS": "user,pipelines,builds",
        "BUILDKITE_READ_ONLY": "true"
      }
    }
  ...
}

Specifying BUILDKITE_TOOLSETS with a value of all enables all available toolsets, which is the default value for this environment variable when omitted.

Omitting the BUILDKITE_TOOLSETS and BUILDKITE_READ_ONLY environment variables from these docker run commands provides unrestricted access to the Buildkite API, restricted only by all applicable token scopes available to the Buildkite user account's API access token, and what it can access on the Buildkite platform.

Using the binary

When configuring your AI tool with the local MCP server running as a pre-built or source-built binary, you can enable one or more toolsets by adding the --enabled-toolsets flag to the buildkite-mcp-server command, and specifying the toolset names as a comma-separated list value for this flag. To enforce read-only access, also add the --read-only flag.

Examples

To enable the builds toolset for the local MCP server, configure the buildkite-mcp-server command with:

buildkite-mcp-server stdio --api-token=bkua_xxxxx --enabled-toolsets="builds"

To enable the user, pipelines, and builds toolsets for the local MCP server, and enforce read-only access across all of these toolsets, configure the buildkite-mcp-server command with:

buildkite-mcp-server stdio --api-token=bkua_xxxxx --enabled-toolsets="user,pipelines,builds" --read-only

You can also be selective with read-only access to toolsets.

Most AI tool or agent configurations for the local MCP server require configuring the buildkite-mcp-server command flags with an env object in its JSON configuration file. Hence, the example above would be configured in these JSON files as:

{
  ...
    "buildkite-read-only-toolsets": {
      "command": "buildkite-mcp-server",
      "args": ["stdio"],
      "env": {
        "BUILDKITE_API_TOKEN": "bkua_xxxxx",
        "BUILDKITE_TOOLSETS": "user,pipelines,builds",
        "BUILDKITE_READ_ONLY": "true"
      }
    }  
  ...
}

Specifying BUILDKITE_TOOLSETS environment variable or the --enabled-toolsets flag with a value of all enables all available toolsets, which is the default value for this environment variable or flag when omitted.

Omitting the BUILDKITE_TOOLSETS and BUILDKITE_READ_ONLY environment variables (or --enabled-toolsets and --read-only flags) from these buildkite-mcp-server commands provides unrestricted access to the Buildkite API, restricted only by all applicable token scopes available to the Buildkite user account's API access token, and what it can access on the Buildkite platform.

Selective read-only access to toolsets

If you want to enable multiple toolsets, but be selective over which ones of these have read-only access, you'll need to create two local MCP servers for your AI tool or agent, each with different configurations—one for toolsets with both read and write access, and the other for toolsets with read-only access.

Examples

To enable the user and pipelines toolsets with read-only access, and the builds toolset with both read and write access, create two local MCP servers (in this case, running in Docker) each with these different configurations.

For the user and pipelines toolsets with read-only access, configure the local MCP server's docker run command with:

docker run --rm -e BUILDKITE_API_TOKEN=bkua_xxxxx -e BUILDKITE_TOOLSETS="user,pipelines" -e BUILDKITE_READ_ONLY="true" buildkite/mcp-server stdio

And for the builds toolset with read and write access, configure the local MCP server's docker run command with:

docker run --rm -e BUILDKITE_API_TOKEN=bkua_xxxxx -e BUILDKITE_TOOLSETS="builds" buildkite/mcp-server stdio

When configuring your AI tool or agent with these local MCP servers, ensure you provide an appropriate name for each MCP server configuration to make it easier to identify which toolsets and level of access each server has to the Buildkite API.

For example, instead of:

"buildkite": { ... }

Use more descriptive names, for example:

"buildkite-read-only-user-pipelines-toolsets": { ... }

and

"buildkite-builds-toolset": { ... }