Buildkite is a CI/CD platform for running and observing software delivery pipelines. Its hosted MCP server supports interactive OAuth and API-token pass-through for headless automation.
This guide covers Buildkite-side setup for an MCP server. The Buildkite agent template is separate from Buildkite credential administration.
Choose a connection method
Use OAuth for an interactive connection. Use an API token only for a non-interactive or headless service. For read-only investigation, Buildkite provides an upstream-enforced read-only OAuth endpoint: https://mcp.buildkite.com/mcp/readonly. See the Buildkite MCP overview.
Recommended: Read-only OAuth
Use the hosted read-only endpoint for a user-delegated investigation workflow. It issues a token whose MCP permissions are read-only.
- Add
https://mcp.buildkite.com/mcp/readonlyto the MCP client. - Start the connection, sign in to Buildkite, select the intended organization, and approve OAuth.
- Query a known test build and verify that a build in an unshared pipeline is unavailable.
- Confirm that build creation, retry, cancellation, and other write tools are absent.
Alternative: API-token pass-through
Use Buildkite's token pass-through endpoint, https://mcp.buildkite.com/direct, only for a headless service that cannot complete interactive OAuth.
- Create an API token for a dedicated identity with access only to the intended test pipelines.
- Send it as
Authorization: Bearer <Buildkite API token>to the/directendpoint. - Record its owner and expiry, then rotate or revoke it when the automation ends.
Alternative: Local MCP server
Buildkite also offers a local server for version-pinned or fully automated environments. It authenticates with an API token; use it only when the hosted OAuth or /direct endpoints do not fit the deployment.
Verify Buildkite MCP
Use this checklist to confirm the MCP server is connected with the intended access.
- Connect the MCP client using the newly created authorization.
- Confirm that Buildkite MCP tools are discovered.
- Read one known test resource that the authorized identity is allowed to access.
- Attempt to read a resource outside the approved Buildkite boundary; it should be unavailable or denied.
- Confirm that no write capability beyond the reviewed setup is available.
Troubleshooting
An authenticated request that cannot see a pipeline almost always reflects Buildkite organization membership or pipeline permissions. Correct the account's role instead of substituting an administrator token.
Next steps
Deploy the Buildkite agent template to create a governed agent in Dome that can inspect the approved CI/CD pipelines, with the template's included model, tools, and rules.
