--- title: "Connect Buildkite to Claude: Control Clusters, Agents, and Queues" slug: connect-buildkite-to-claude-control-clusters-agents-and-queues date: 2026-10-31 author: Nidhi KN categories: ["AI & Agents"] excerpt: "Learn how to safely connect Buildkite to Claude using a managed MCP server. Automate CI/CD pipelines, manage agent clusters, and analyze build logs with AI." tldr: "A comprehensive engineering guide to connecting Buildkite to Claude via Truto's MCP server. Learn to securely expose pipelines, agents, and builds to LLMs using dynamic tool generation, method filtering, and zero-data-retention architecture." canonical: https://truto.one/blog/connect-buildkite-to-claude-control-clusters-agents-and-queues/ --- # Connect Buildkite to Claude: Control Clusters, Agents, and Queues If you need to connect Buildkite to Claude to automate CI/CD pipelines, manage agent fleets, or triage failed builds, you need a [Model Context Protocol (MCP) server](https://truto.one/what-is-mcp-and-mcp-servers-and-how-do-they-work/). This server acts as the translation layer between Claude's JSON-RPC tool calls and Buildkite's REST APIs. You can either [build and maintain this infrastructure yourself](https://truto.one/the-hands-on-guide-to-building-mcp-servers-for-ai-agents-2026/), or use a managed integration platform like Truto to dynamically generate a [secure, authenticated MCP server URL](https://truto.one/managed-mcp-for-claude-full-saas-api-access-without-security-headaches/). If your team uses ChatGPT, check out our guide on [/connect-buildkite-to-chatgpt-manage-pipelines-builds-and-logs/](https://truto.one/connect-buildkite-to-chatgpt-manage-pipelines-builds-and-logs/). For a broader architectural overview on CI/CD automation, read [/connect-buildkite-to-ai-agents-automate-tests-runs-and-artifacts/](https://truto.one/connect-buildkite-to-ai-agents-automate-tests-runs-and-artifacts/). Giving a Large Language Model (LLM) read and write access to your core engineering infrastructure is a high-stakes engineering challenge. You must handle token lifecycles, map massive JSON schemas to LLM tool definitions, and deal with Buildkite's specific structural quirks. Every time Buildkite updates an endpoint or adds new cluster functionality, you have to update your server code, redeploy, and test the integration. This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Buildkite, connect it natively to Claude Desktop, and execute complex DevOps workflows using natural language. > Want to give your AI agents secure, authenticated access to Buildkite and 100+ other SaaS APIs? Let's talk about managed MCP architecture. > > [Talk to us](https://truto.one/book-a-demo/) ## The Engineering Reality of the Buildkite API A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against Buildkite's APIs is painful. You are not just integrating a flat list of endpoints—you are integrating a complex topological graph of Organizations, Clusters, Pipelines, Builds, Jobs, and Agents. If you decide to build a custom MCP server for Buildkite, here are the specific integration challenges you will face: ### Deeply Nested Hierarchies and Resource IDs Buildkite's data model heavily relies on composite routing parameters. To fetch a single artifact, you don't just query `/artifacts/:id`. You must construct a path containing the organization slug, pipeline slug, build number, and job ID. An LLM has no inherent context for this hierarchy. You must build an abstraction layer that explicitly maps these relationships so the LLM understands that to interact with a build, it first needs the pipeline slug, and to interact with a pipeline, it needs the organization slug. ### Mutable Agent Connection States Managing infrastructure via an LLM requires strict guardrails. Buildkite agents exist in highly fluid states (connected, pausing, paused, stopping, stopped). If you command an agent to stop while it is in the middle of a critical job without first pausing the queue, you risk interrupting production deployments. Your MCP tools must enforce state checks or provide explicit parameters to safely drain workloads before terminating agents. ### Strict Rate Limits and LLM Backoff Orchestration Buildkite aggressively enforces API rate limits. When a limit is hit, the API returns an `HTTP 429 Too Many Requests`. This introduces a critical architectural decision: who handles the backoff? Truto explicitly **does not retry, throttle, or apply backoff** on rate limit errors. Instead, when Buildkite returns a 429, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit information into standardized HTTP headers per the IETF specification: * `ratelimit-limit`: The maximum number of requests permitted in the current window. * `ratelimit-remaining`: The number of requests remaining. * `ratelimit-reset`: The time at which the limit resets. This pass-through design ensures that the LLM or your agent orchestration framework (like LangGraph or CrewAI) receives the immediate signal to halt execution, evaluate the `ratelimit-reset` window, and retry contextually, rather than hanging indefinitely on a hidden middleware queue. ## Step 1: Generate the Buildkite MCP Server URL [Truto dynamically generates MCP tools](https://truto.one/auto-generated-mcp-tools-for-ai-agents-a-2026-architecture-guide/) from Buildkite's API documentation. Rather than hand-coding tool definitions, Truto reads the API schemas, injects pagination instructions (like strictly passing `next_cursor` back unmodified), and exposes a JSON-RPC 2.0 endpoint. You can generate this server via the Truto UI or programmatically via the API. ### Method A: Via the Truto UI 1. Log into your Truto dashboard and navigate to your **Integrated Accounts**. 2. Select the connected Buildkite account you want to expose. 3. Click the **MCP Servers** tab. 4. Click **Create MCP Server**. 5. Configure the server parameters (Name, allowed methods, resource tags, and expiration). 6. Copy the generated secure MCP server URL (e.g., `https://api.truto.one/mcp/a1b2c3d4e5f6...`). ### Method B: Via the Truto API If you are dynamically provisioning AI workspaces for your internal developer platform, you can generate MCP servers programmatically. ```bash curl -X POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp \ -H "Authorization: Bearer YOUR_TRUTO_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Buildkite Incident Triage Bot", "config": { "methods": ["read", "update"], "tags": ["pipelines", "builds", "jobs", "agents"] }, "expires_at": "2026-12-31T23:59:59Z" }' ``` The API provisions a cryptographically hashed token backed by edge KV storage, ensuring high-availability routing for your MCP client. ## Step 2: Connect the MCP Server to Claude Once you have your Truto MCP URL, connecting it to Claude requires zero additional code. You can plug it directly into the Claude UI or configure it via the desktop config file. ### Method A: Via the Claude UI 1. Open Claude Desktop or Web. 2. Navigate to **Settings → Integrations → Add MCP Server**. 3. Paste your Truto MCP URL and click **Add**. 4. Claude will instantly negotiate a handshake, call `tools/list`, and populate its context window with the available Buildkite operations. *(Note: For ChatGPT users, navigate to Settings → Apps → Advanced settings → Developer mode, and add the server under Custom Connectors).* ### Method B: Via Manual Config File (SSE Transport) For custom agent architectures or specific Claude Desktop configurations, you can use the official `@modelcontextprotocol/server-sse` wrapper. Edit your `claude_desktop_config.json`: ```json { "mcpServers": { "buildkite-truto": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-sse", "--url", "https://api.truto.one/mcp/a1b2c3d4e5f6..." ] } } } ``` Restart Claude Desktop. The LLM is now physically wired into your Buildkite organization. ## Hero Tools for Buildkite Exposing the entire Buildkite API surface to an LLM can burn token context limits. Truto scopes tools via tags and method filters. Below are the highest-leverage "hero tools" generated for Buildkite workflows. ### 1. `list_all_buildkite_pipelines` Discovers all available pipelines within a specific organization. The LLM uses this to find pipeline slugs required for downstream build and job operations. > "Fetch all pipelines in our 'acme-corp' organization. Identify any pipelines currently experiencing a high volume of running builds." ### 2. `create_a_buildkite_build` Triggers a new build execution for a specific pipeline. The LLM can inject custom environment variables, specify branches, or target exact commits. > "Trigger a new build for the 'frontend-monorepo' pipeline on the 'main' branch, using the latest commit." ### 3. `buildkite_builds_cancel` Instantly cancels a running or scheduled build. This is critical for automated cost control or stopping runaway deployments detected by an observability agent. > "Cancel build number 405 on the 'payment-service-deploy' pipeline immediately." ### 4. `list_all_buildkite_agents` Retrieves the current fleet of Buildkite agents across the organization, including their exact connection state, version, and the specific jobs they are processing. > "List all connected Buildkite agents. Tell me which agents are currently running jobs and which are idle." ### 5. `buildkite_agents_pause` Safely prevents an agent from accepting new jobs. The agent will finish its current workload and then remain idle—the safest way to drain workloads before terminating instances. > "Pause the agent with ID 'agent-1234-uuid'. I need to drain it before we update the underlying EC2 instance." ### 6. `buildkite_jobs_get_log` Fetches the raw, unadulterated log output for a specific job. LLMs excel at parsing these raw strings to isolate stack traces, segfaults, or failing unit tests. > "Get the log output for job ID 'job-5678-uuid' in build 42. Analyze the logs and tell me exactly which unit tests failed and why." ### 7. `buildkite_jobs_retry_failed_jobs` A bulk action tool that instructs Buildkite to retry all failed jobs within a specific build number. Ideal for overcoming transient infrastructure flakes. > "Retry all failed jobs for build 88 on the 'mobile-app-ci' pipeline." For a complete list of dynamically generated tools and their JSON schemas, view the [Buildkite integration page](https://truto.one/integrations/detail/buildkite). ## Workflows in Action When Claude has access to these tools, it stops acting like a static chat interface and becomes an active site reliability engineer. Here is how complex infrastructure workflows execute in production. ### Workflow 1: CI/CD Incident Triage & Log Analysis When a critical pipeline goes red, digging through nested jobs and scrolling through 10,000 lines of console output is a massive time sink. You can delegate the entire triage process to Claude. > "Find the failed jobs in build 42 of the 'frontend-monorepo' pipeline and summarize the exact error logs." **Execution Steps:** 1. **`get_single_buildkite_build_by_id`**: Claude queries the build metadata to inspect the `job_state_counts` and retrieve the array of jobs, isolating the ones with a `failed` state. 2. **`buildkite_jobs_get_log`**: Claude extracts the `job_id` from the failed job and fetches the raw log payload. 3. **Analysis**: Claude processes the raw log text, ignores the successful build steps, extracts the specific webpack or jest failure stack trace, and returns a concise, human-readable summary of the root cause. ### Workflow 2: Agent Fleet Management & Drain Managing self-hosted agents requires careful operational hygiene. If an agent is running a stale AMI or an old Buildkite version, it needs to be drained and decommissioned. > "List all connected agents. If any are running version 3.40, pause them so they don't take new jobs." **Execution Steps:** 1. **`list_all_buildkite_agents`**: Claude retrieves the paginated list of all agents in the organization. 2. **Filtering**: Claude evaluates the `version` and `connection_state` fields in the JSON response, identifying agents running version 3.40. 3. **`buildkite_agents_pause`**: For every identified agent, Claude issues a pause command using the agent's unique ID. The agents will complete their current jobs but reject new dispatches. ### Workflow 3: Emergency Pipeline Freeze During a severity-1 incident, the first priority is stopping the bleeding. You must halt active deployments and prevent engineers from triggering new ones. > "Archive the 'payment-service-deploy' pipeline to prevent new deployments, and cancel any currently running builds for it." **Execution Steps:** 1. **`buildkite_pipelines_archive`**: Claude immediately marks the pipeline as archived, removing it from the UI and preventing new build creation. 2. **`buildkite_builds_list_for_pipeline`**: Claude queries the pipeline's history, passing query parameters to filter for builds currently in the `running` state. 3. **`buildkite_builds_cancel`**: Claude iterates over the active build numbers and issues cancellation commands, forcefully halting the deployment process. ```mermaid sequenceDiagram participant User as User Prompt participant Claude as Claude Desktop participant Truto as Truto MCP Router participant Buildkite as Buildkite API User->>Claude: "Archive pipeline and cancel running builds" Claude->>Truto: call tool: buildkite_pipelines_archive Truto->>Buildkite: POST /v2/organizations/{org}/pipelines/{slug}/archive Buildkite-->>Truto: 200 OK (Pipeline Archived) Truto-->>Claude: JSON Tool Result Claude->>Truto: call tool: buildkite_builds_list_for_pipeline (state=running) Truto->>Buildkite: GET /v2/organizations/{org}/pipelines/{slug}/builds?state=running Buildkite-->>Truto: 200 OK [Build #405, Build #406] Truto-->>Claude: JSON Tool Result Claude->>Truto: call tool: buildkite_builds_cancel (build=405) Truto->>Buildkite: PUT /v2/organizations/{org}/pipelines/{slug}/builds/405/cancel Buildkite-->>Truto: 200 OK (Canceled) Truto-->>Claude: JSON Tool Result ``` ## Security and Access Control Giving an LLM the ability to cancel builds and shut down infrastructure requires strict security boundaries. Truto MCP servers enforce isolation at the edge: * **Method Filtering**: Lock a server down to `read` operations only (e.g., `get`, `list`). An LLM using a read-only server physically cannot execute a `create`, `update`, or `delete` operation, no matter how hard you prompt it. * **Tag Filtering**: Scope access by domain. By configuring `tags: ["pipelines"]`, the MCP server will omit all tools related to `agents`, `clusters`, or `billing`. * **Time-To-Live (`expires_at`)**: Generate ephemeral MCP servers. Set a TTL of 24 hours for a contractor or a temporary AI debugging session. When the edge alarm fires, the token is permanently destroyed. * **Enforced API Token Auth**: Toggle `require_api_token_auth` to `true`. This forces the client to pass a valid Truto API token in the Authorization header alongside the URL token. Possession of the URL alone is no longer enough to execute tools. ## Moving Past Static CI/CD Dashboards Connecting Buildkite to Claude transforms how your engineering team interacts with deployment infrastructure. By delegating log analysis, agent management, and pipeline orchestration to an LLM, you remove the friction of navigating deeply nested UI dashboards and complex REST parameters. Truto handles the heavy lifting: dynamic tool generation, schema translation, token security, and standardized rate limit headers. Your developers can focus purely on defining prompts and building resilient, AI-driven automation workflows.