Buildkite
Buildkite is a platform for running fast, secure, and scalable continuous integration pipelines on your own infrastructure.
Verdict
Common use cases
- Check agent availability before deploying
- Audit API token scopes during security review
- Retrieve webhook IPs for firewall allowlist
- Triage build queue during incident response
- Verify runner capacity across environments
Integration
- Vendor
- Buildkite
- Category
- developer-tools
- Auth
- API_KEY
- Tools
- 3
- Composio slug
buildkite
Tools
- Get Current Access Token
Tool to retrieve the authenticated api access token details. use when you need to confirm the validity and scopes of the current api token.
- Get Meta
Tool to retrieve metadata about the buildkite api. use when you need to fetch webhook ip addresses for firewall or security configurations.
- List Pipeline Agents
Tool to list connected agents for an organization. use after confirming the organization slug. supports optional filtering and pagination.
Setup
Setup guide
- 11. In Switchy, open your workspace settings and navigate to Integrations. 2. Find Buildkite in the developer tools section and click Connect. 3. You'll be prompted to paste a Buildkite API access token — generate one at buildkite.com/user/api-access-tokens with at least read_agents and read_organizations scopes. 4. Paste the token into Switchy and click Authorize. 5. Switchy confirms the connection by fetching your token details. 6. Open any Space and type '@Buildkite list agents for my-org' (replace my-org with your actual organization slug). 7. If you see a list of connected agents with their status and metadata, the integration is working. 8. To find your organization slug, check the URL when viewing pipelines in Buildkite — it's the segment after buildkite.com/.
What teammates see: by default, memories from Buildkite are scoped to the Space (PROJECT visibility) - you can mark any memory PRIVATE or share it ORG-wide.
Works well with
Top models
Compatibility data appears once enough Spaces have used this MCP together with a given model.
How Switchy teams use it
Starter prompts
Agent Health Check
@Buildkite list all agents for acme-corp and show me which ones are currently idle or disconnectedOpen in a Space →
Token Scope Audit
@Buildkite get the details of my current access token including all granted scopesOpen in a Space →
Firewall Configuration
@Buildkite retrieve the webhook IP addresses I need to whitelist for incoming build notificationsOpen in a Space →
Runner Capacity Report
@Buildkite list agents for acme-corp and group them by connection status so I can see total capacityOpen in a Space →
Pre-Deploy Validation
@Buildkite show me all agents for acme-corp and filter for ones tagged with environment=productionOpen in a Space →
Example outputs
Illustrative - representative of the model's voice and quality, not literal recordings.
@buildkite show me all connected agents in our organization and their current status
Found 12 agents across your Buildkite organization. 9 agents are currently idle and available (including 'prod-runner-01' through 'prod-runner-06' and three staging runners). 2 agents are actively running builds ('deploy-agent-us-east' handling a production deployment, 'test-agent-02' running integration tests). 1 agent ('backup-runner') has been disconnected for 3 hours. All active agents are running version 3.52.0 with matching metadata tags for their respective environments.
This example demonstrates the List Pipeline Agents tool's ability to provide real-time infrastructure visibility. Requires an API token with 'read_agents' scope. Agent status reflects a point-in-time snapshot — refresh the query if you need current state during active deployments or scaling events.
@buildkite verify our API token has the right permissions for webhook configuration
Your current Buildkite API token (ending in ...x7k2) is valid and has the following scopes: read_organizations, read_pipelines, read_builds, read_agents, and write_builds. The token was created 14 days ago and belongs to the service account 'ci-automation@company.com'. However, this token does NOT have the 'write_webhooks' scope required to programmatically configure webhook endpoints. You'll need to regenerate the token with that scope or use the Buildkite web UI to set up webhooks manually.
This uses Get Current Access Token to audit authentication before attempting privileged operations. Essential for troubleshooting permission errors or validating service account setup. The tool only inspects the token in use — it cannot modify scopes or create new tokens.
@buildkite get the webhook IP ranges so I can update our firewall allowlist, then draft the infrastructure ticket
Buildkite webhooks originate from these IP ranges: 192.0.2.0/24, 198.51.100.0/24, and 203.0.113.0/24 (IPv4), plus 2001:db8::/32 (IPv6). Here's a draft infrastructure ticket: **Title:** Allowlist Buildkite Webhook IPs in Production Firewall **Description:** Update firewall rules to permit inbound HTTPS traffic from Buildkite's webhook IP ranges to our webhook receiver at webhook.company.com:443. This unblocks build status notifications for our CI/CD pipelines. **IP Ranges to Add:** [lists ranges above] **Priority:** Medium — current webhook failures are causing 15-minute notification delays.
This combines Get Meta (for authoritative IP data) with AI synthesis to create actionable documentation. The IP ranges shown are illustrative examples — actual ranges from Buildkite's API will differ. Webhook IPs can change; consider automating periodic checks rather than treating this as a one-time configuration.
Use-case deep-dives
When Buildkite MCP helps you triage build failures faster
A 6-person engineering team hits a Friday afternoon incident: builds are failing intermittently, and no one knows if it's a code issue or an agent problem. The Buildkite MCP is the right call here because you can query agent status directly from Switchy without context-switching to the Buildkite UI. One engineer asks the workspace to list pipeline agents, spots three offline agents in the us-west region, and escalates to infrastructure in under two minutes. The MCP's three-tool scope is narrow but surgical—it answers 'is our CI infrastructure healthy?' without drowning you in pipeline configuration details. If your team runs more than 20 agents across regions, this MCP pays for itself in reduced mean-time-to-triage. Add it to your Switchy workspace before the next deploy goes sideways.
Buildkite MCP for teaching new hires the pipeline setup
A startup with 3 backend engineers just hired their first junior developer, and they need to explain how Buildkite agents map to deployment environments without overwhelming the new hire. The Buildkite MCP is borderline useful here. You can use it to show the agent list in a Switchy thread and walk through which agents handle staging versus production builds, but the MCP doesn't expose pipeline definitions or build history—so you're still opening the Buildkite dashboard for the full picture. If your onboarding process is heavily documentation-driven and you already have runbooks in Notion or Confluence, skip this MCP and link to those instead. But if your team learns by doing and you want a junior to query agent health during their first week, the MCP gives them a safe sandbox to explore without admin access to the full Buildkite UI.
When you need to verify Buildkite token scopes across teams
A 12-person product org is preparing for SOC 2 compliance, and the security lead needs to audit which API tokens have access to Buildkite and what scopes they hold. The Buildkite MCP is the right tool for this one-time audit because the Get Current Access Token tool surfaces token details without requiring a full Buildkite admin login. The security lead adds the MCP to a private Switchy workspace, runs the token check, screenshots the scopes for the compliance folder, and removes the MCP the same day. This is a narrow use-case, but it's faster than logging into Buildkite's settings UI and manually documenting token permissions. If you're auditing more than just Buildkite—say, GitHub, AWS, and Datadog tokens—you'll want a dedicated secrets management tool instead. For a quick Buildkite-only audit, this MCP gets you in and out in under 10 minutes.
Frequently asked
What does the Buildkite MCP do in Switchy?
It lets AI assistants check your Buildkite API token status, fetch webhook IP addresses for firewall rules, and list connected build agents across your organization. You can ask questions like 'which agents are online' or 'what IPs should I whitelist' without leaving the conversation. The MCP doesn't trigger builds or modify pipelines—it's read-only metadata access.
Do I need admin access to connect Buildkite MCP?
You need a Buildkite API token with read scopes for the resources you want to query. Buildkite uses API key authentication, not OAuth, so generate a token in your Buildkite organization settings. The token's permissions determine what the MCP can see—if it can't read agents, the List Pipeline Agents tool won't work. No admin role required, but you control scope via the token.
Can the Buildkite MCP trigger builds or restart failed jobs?
No. The three tools are read-only: checking token validity, fetching API metadata, and listing agents. If you need to trigger builds or manage pipelines, use Buildkite's web UI or a separate automation tool. This MCP is for inspecting state and configuration, not orchestrating CI/CD workflows. It's useful for debugging agent connectivity or confirming your token works before scripting.
How is this different from just using the Buildkite API directly?
The MCP wraps three specific Buildkite API endpoints so AI assistants can answer questions conversationally. Instead of writing curl commands or reading JSON responses, you ask 'which agents are connected to my org' and get a plain-English summary. It's faster for one-off checks but less flexible than the full API—you can't create pipelines or manage builds through the MCP.
Who on the team should connect the Buildkite MCP?
Whoever manages your CI/CD infrastructure or needs to debug agent issues. Since it uses an API key, that person generates the token in Buildkite and pastes it into Switchy. The MCP doesn't consume Buildkite seats or pipeline minutes—it's just API calls. If multiple people need access, they can share the Switchy workspace; the token stays connected for everyone.