Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Buildkite MCP connector

OAuth 2.1/DCR Developer ToolsAutomationAI

Connect to Buildkite MCP. Manage CI/CD pipelines, builds, agents, clusters, and test suites from your AI workflows.

Buildkite MCP connector

  1. Install the SDK

    Section titled “Install the SDK”
    Terminal window
    npm install @scalekit-sdk/node

    Full SDK reference: Node.js | Python

  2. Set your credentials

    Section titled “Set your credentials”

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>

  3. Authorize and make your first call

    Section titled “Authorize and make your first call”
    quickstart.ts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    

    const scalekit = new ScalekitClient(
      process.env.SCALEKIT_ENV_URL,
      process.env.SCALEKIT_CLIENT_ID,
      process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    

    const connector = 'buildkitemcp'
    const identifier = 'user_123'
    

    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Buildkite MCP:', link)
    process.stdout.write('Press Enter after authorizing...')
    await new Promise(r => process.stdin.once('data', r))
    

    // Make your first call
    const result = await actions.executeTool({
      connector,
      identifier,
      toolName: 'buildkitemcp_list_agents',
      toolInput: { org_slug: 'YOUR_ORG_SLUG' },
    })
    console.log(result)

What you can do

Section titled “What you can do”

Connect this agent connector to let your agent:

  • Organization user token — Get the organization associated with the user token used for this request
  • Update pipeline schedule, pipeline, cluster queue — Modify an existing pipeline schedule’s cron expression, branch, environment variables, or enabled state
  • Job unblock, retry — Unblock a blocked job in a Buildkite build to allow it to continue execution
  • Logs tail — Show the last N entries from the log file
  • Search logs — Search log entries using regex patterns with optional context lines
  • Dispatch resume cluster queue, pause cluster queue — Resume dispatch on a paused cluster queue, allowing jobs to be dispatched to agents again

Tool list

Section titled “Tool list”

Use the exact tool names from the Tool list below when you call execute_tool. If you’re not sure which name to use, list the tools available for the current user first.

buildkitemcp_access_token # Get information about the current API access token including its scopes and UUID 0 params

Get information about the current API access token including its scopes and UUID

buildkitemcp_cancel_build # Cancel a running build on a Buildkite pipeline 3 params

Cancel a running build on a Buildkite pipeline

Name Type Required Description
build_number string required No description.
org_slug string required No description.
pipeline_slug string required No description.
buildkitemcp_create_annotation # Create an annotation on a build or specific job. Use scope='build' (default) or scope='job' with job_id 10 params

Create an annotation on a build or specific job. Use scope='build' (default) or scope='job' with job_id

Name Type Required Description
body string required The annotation body as HTML or Markdown
build_number string required No description.
org_slug string required No description.
pipeline_slug string required No description.
append boolean optional Append the body to an existing annotation with the same context
context string optional Optional annotation context used to identify or append to an annotation
job_id string optional Job ID required when scope is job
priority integer optional Optional annotation priority from 1 to 10
scope string optional Annotation scope: 'build' (default) or 'job'. When 'job', job_id is required.
style string optional Optional annotation style: success, info, warning, or error
buildkitemcp_create_build # Trigger a new build on a Buildkite pipeline for a specific commit and branch, with optional environment variables, metadata, and author information 8 params

Trigger a new build on a Buildkite pipeline for a specific commit and branch, with optional environment variables, metadata, and author information

Name Type Required Description
branch string required No description.
commit string required The commit SHA to build
message string required No description.
org_slug string required No description.
pipeline_slug string required No description.
environment string optional Environment variables to set for the build
ignore_branch_filters boolean optional Whether to ignore branch filters when triggering the build
metadata string optional Meta-data values to set for the build
buildkitemcp_create_cluster # Create a new cluster in an organization 5 params

Create a new cluster in an organization

Name Type Required Description
name string required No description.
org_slug string required No description.
color string optional Hex color code for the cluster (e.g. #A9CCE3)
description string optional Description of the cluster
emoji string optional Emoji for the cluster (e.g. :toolbox:)
buildkitemcp_create_cluster_queue # Create a new queue in a cluster 4 params

Create a new queue in a cluster

Name Type Required Description
cluster_id string required No description.
key string required No description.
org_slug string required No description.
description string optional Description of the queue
buildkitemcp_create_pipeline # Set up a new CI/CD pipeline in Buildkite with YAML configuration, repository connection, and cluster assignment 11 params

Set up a new CI/CD pipeline in Buildkite with YAML configuration, repository connection, and cluster assignment

Name Type Required Description
cluster_id string required The cluster ID to assign the pipeline to
configuration string required The pipeline configuration in YAML format
name string required No description.
org_slug string required No description.
repository_url string required The Git repository URL
cancel_running_branch_builds boolean optional Cancel running builds when new builds are created on the same branch
create_webhook boolean optional Create a GitHub webhook to trigger builds on pull-request and push events
default_branch string optional The default branch for builds and metrics filtering
description string optional No description.
skip_queued_branch_builds boolean optional Skip intermediate builds when new builds are created on the same branch
tags string optional Tags to apply to the pipeline for filtering and organization
buildkitemcp_create_pipeline_schedule # Create a new pipeline schedule that triggers builds on a cron-driven interval 9 params

Create a new pipeline schedule that triggers builds on a cron-driven interval

Name Type Required Description
cronline string required Schedule interval as a crontab expression (e.g. '0 0 * * *') or predefined value (e.g. '@daily'\, '@hourly'\, '@weekly'\, '@monthly'\, '@yearly')
org_slug string required No description.
pipeline_slug string required No description.
branch string optional Target branch (defaults to the pipeline default branch)
commit string optional Commit reference (defaults to HEAD)
enabled string optional Whether the schedule is active. Defaults to true if unset.
env object optional Environment variables to set on triggered builds
label string optional Descriptive label for the schedule
message string optional Message attached to triggered builds
buildkitemcp_current_user # Get details about the user account that owns the API token, including name, email, avatar, and account creation date 0 params

Get details about the user account that owns the API token, including name, email, avatar, and account creation date

buildkitemcp_get_agent # Get detailed information about a specific agent including its connection state, host details, current job, metadata, and pause status 3 params

Get detailed information about a specific agent including its connection state, host details, current job, metadata, and pause status

Name Type Required Description
agent_id string required No description.
org_slug string required No description.
detail_level string optional Response detail level: 'summary'\, 'detailed'\, or 'full' (default)
buildkitemcp_get_artifact # Download a specific artifact's content, identified by its organization, pipeline, build, job, and artifact identifiers. The content is returned base64-encoded 5 params

Download a specific artifact's content, identified by its organization, pipeline, build, job, and artifact identifiers. The content is returned base64-encoded

Name Type Required Description
artifact_id string required The UUID of the artifact to download
build_number string required No description.
job_id string required The UUID of the job that produced the artifact
org_slug string required No description.
pipeline_slug string required No description.
buildkitemcp_get_build # Get build information including job IDs, names, and states. Use job_state to filter (e.g. 'failed,broken'). Returns enough detail to identify which jobs to investigate with log and artifact tools 6 params

Get build information including job IDs, names, and states. Use job_state to filter (e.g. 'failed,broken'). Returns enough detail to identify which jobs to investigate with log and artifact tools

Name Type Required Description
build_number string required No description.
org_slug string required No description.
pipeline_slug string required No description.
detail_level string optional Response detail level: 'detailed' (default) or 'full'. Detailed includes job IDs/names/states; full includes complete job objects
include_agent boolean optional Include full agent details in job objects. When false (default)\, only agent.id is included
job_state string optional Filter jobs by state. Comma-separated for multiple states (e.g.\, 'failed\,broken\,canceled')
buildkitemcp_get_build_test_engine_runs # Get test engine runs data for a specific build in Buildkite. This can be used to look up Test Runs. 3 params

Get test engine runs data for a specific build in Buildkite. This can be used to look up Test Runs.

Name Type Required Description
build_number string required No description.
org_slug string required No description.
pipeline_slug string required No description.
buildkitemcp_get_cluster # Get detailed information about a specific cluster including its name, description, default queue, and configuration 2 params

Get detailed information about a specific cluster including its name, description, default queue, and configuration

Name Type Required Description
cluster_id string required No description.
org_slug string required No description.
buildkitemcp_get_cluster_queue # Get detailed information about a specific queue including its key, description, dispatch status, and hosted agent configuration 3 params

Get detailed information about a specific queue including its key, description, dispatch status, and hosted agent configuration

Name Type Required Description
cluster_id string required No description.
org_slug string required No description.
queue_id string required No description.
buildkitemcp_get_failed_executions # Get failed test executions for a specific test run in Buildkite Test Engine. Optionally get the expanded failure details such as full error messages and stack traces. 6 params

Get failed test executions for a specific test run in Buildkite Test Engine. Optionally get the expanded failure details such as full error messages and stack traces.

Name Type Required Description
org_slug string required No description.
run_id string required No description.
test_suite_slug string required No description.
include_failure_expanded boolean optional Include expanded failure details such as full error messages and stack traces
page integer optional Page number for pagination (min 1)
per_page integer optional Results per page for pagination (min 1\, max 100)
buildkitemcp_get_job_env # Get the environment variables for a specific job in a Buildkite build 4 params

Get the environment variables for a specific job in a Buildkite build

Name Type Required Description
build_number string required No description.
job_id string required No description.
org_slug string required No description.
pipeline_slug string required No description.
buildkitemcp_get_pipeline # Get detailed information about a specific pipeline including its configuration, steps, environment variables, and build statistics 3 params

Get detailed information about a specific pipeline including its configuration, steps, environment variables, and build statistics

Name Type Required Description
org_slug string required No description.
pipeline_slug string required No description.
detail_level string optional Response detail level: 'summary'\, 'detailed'\, or 'full' (default)
buildkitemcp_get_pipeline_schedule # Get detailed information about a single pipeline schedule including its cron expression, target branch, environment variables, enabled state, last failure, and next build time 3 params

Get detailed information about a single pipeline schedule including its cron expression, target branch, environment variables, enabled state, last failure, and next build time

Name Type Required Description
org_slug string required No description.
pipeline_slug string required No description.
schedule_id string required No description.
buildkitemcp_get_test # Get a specific test in Buildkite Test Engine. This provides additional metadata for failed test executions 3 params

Get a specific test in Buildkite Test Engine. This provides additional metadata for failed test executions

Name Type Required Description
org_slug string required No description.
test_id string required No description.
test_suite_slug string required No description.
buildkitemcp_get_test_run # Get a specific test run in Buildkite Test Engine 3 params

Get a specific test run in Buildkite Test Engine

Name Type Required Description
org_slug string required No description.
run_id string required No description.
test_suite_slug string required No description.
buildkitemcp_list_agents # List agents in an organization with their connection state, host details, version, current job, and pause status 7 params

List agents in an organization with their connection state, host details, version, current job, and pause status

Name Type Required Description
org_slug string required No description.
detail_level string optional Response detail level: 'summary' (default)\, 'detailed'\, or 'full'
hostname string optional No description.
name string optional No description.
page integer optional Page number for pagination (min 1)
per_page integer optional Results per page for pagination (min 1\, max 100)
version string optional No description.
buildkitemcp_list_annotations # List annotations for a build or a specific job. Use scope='build' (default) or scope='job' with job_id 7 params

List annotations for a build or a specific job. Use scope='build' (default) or scope='job' with job_id

Name Type Required Description
build_number string required No description.
org_slug string required No description.
pipeline_slug string required No description.
job_id string optional Job ID required when scope is job
page integer optional Page number for pagination (min 1)
per_page integer optional Results per page for pagination (min 1\, max 100)
scope string optional Annotation scope: 'build' (default) or 'job'. When 'job', job_id is required.
buildkitemcp_list_artifacts_for_build # List all artifacts for a build across all jobs, including file details, paths, sizes, MIME types, and download URLs 5 params

List all artifacts for a build across all jobs, including file details, paths, sizes, MIME types, and download URLs

Name Type Required Description
build_number string required No description.
org_slug string required No description.
pipeline_slug string required No description.
page integer optional Page number for pagination (min 1)
per_page integer optional Results per page for pagination (min 1\, max 100)
buildkitemcp_list_artifacts_for_job # List all artifacts for an individual job, including file details, paths, sizes, MIME types, and download URLs 6 params

List all artifacts for an individual job, including file details, paths, sizes, MIME types, and download URLs

Name Type Required Description
build_number string required No description.
job_id string required No description.
org_slug string required No description.
pipeline_slug string required No description.
page integer optional Page number for pagination (min 1)
per_page integer optional Results per page for pagination (min 1\, max 100)
buildkitemcp_list_builds # List builds for a pipeline or across all pipelines in an organization. When pipeline_slug is omitted, lists builds across all pipelines in the organization 9 params

List builds for a pipeline or across all pipelines in an organization. When pipeline_slug is omitted, lists builds across all pipelines in the organization

Name Type Required Description
org_slug string required No description.
branch string optional Filter builds by git branch name
commit string optional Filter builds by specific commit SHA
creator string optional Filter builds by build creator
detail_level string optional Response detail level: 'summary' (default)\, 'detailed'\, or 'full'
page integer optional Page number for pagination (min 1)
per_page integer optional Results per page for pagination (min 1\, max 100)
pipeline_slug string optional Filter builds by pipeline. When omitted\, lists builds across all pipelines in the organization
state string optional Filter builds by state (scheduled\, running\, passed\, failed\, canceled\, skipped)
buildkitemcp_list_cluster_queues # List all queues in a cluster with their keys, descriptions, dispatch status, and agent configuration 4 params

List all queues in a cluster with their keys, descriptions, dispatch status, and agent configuration

Name Type Required Description
cluster_id string required No description.
org_slug string required No description.
page integer optional Page number for pagination (min 1)
per_page integer optional Results per page for pagination (min 1\, max 100)
buildkitemcp_list_clusters # List all clusters in an organization with their names, descriptions, default queues, and creation details 3 params

List all clusters in an organization with their names, descriptions, default queues, and creation details

Name Type Required Description
org_slug string required No description.
page integer optional Page number for pagination (min 1)
per_page integer optional Results per page for pagination (min 1\, max 100)
buildkitemcp_list_pipeline_schedules # List the pipeline schedules for a pipeline, including cron expression, target branch, environment variables, enabled state, and next scheduled build time 4 params

List the pipeline schedules for a pipeline, including cron expression, target branch, environment variables, enabled state, and next scheduled build time

Name Type Required Description
org_slug string required No description.
pipeline_slug string required No description.
page integer optional Page number for pagination (min 1)
per_page integer optional Results per page for pagination (min 1\, max 100)
buildkitemcp_list_pipelines # List all pipelines in an organization with their basic details, build counts, and current status 6 params

List all pipelines in an organization with their basic details, build counts, and current status

Name Type Required Description
org_slug string required No description.
detail_level string optional Response detail level: 'summary' (default)\, 'detailed'\, or 'full'
name string optional Filter pipelines by name
page integer optional Page number for pagination (min 1)
per_page integer optional Results per page for pagination (min 1\, max 100)
repository string optional Filter pipelines by repository URL
buildkitemcp_list_test_runs # List all test runs for a test suite in Buildkite Test Engine 4 params

List all test runs for a test suite in Buildkite Test Engine

Name Type Required Description
org_slug string required No description.
test_suite_slug string required No description.
page integer optional Page number for pagination (min 1)
per_page integer optional Results per page for pagination (min 1\, max 100)
buildkitemcp_pause_cluster_queue_dispatch # Pause dispatch on a cluster queue, preventing new jobs from being dispatched to agents 4 params

Pause dispatch on a cluster queue, preventing new jobs from being dispatched to agents

Name Type Required Description
cluster_id string required No description.
org_slug string required No description.
queue_id string required No description.
note string optional Reason for pausing dispatch
buildkitemcp_read_logs # Read log entries from the file, optionally starting from a specific row number. ALWAYS use 'limit' parameter to avoid excessive tokens. For recent failures, use 'tail_logs' instead. Recommended limits: investigation (100-500), exploration (use seek + small limits). The json format: {ts: timestamp_ms, c: content, rn: row_number}. 8 params

Read log entries from the file, optionally starting from a specific row number. ALWAYS use 'limit' parameter to avoid excessive tokens. For recent failures, use 'tail_logs' instead. Recommended limits: investigation (100-500), exploration (use seek + small limits). The json format: {ts: timestamp_ms, c: content, rn: row_number}.

Name Type Required Description
build_number string required No description.
job_id string required No description.
org_slug string required No description.
pipeline_slug string required No description.
cache_ttl string optional No description.
force_refresh boolean optional No description.
limit integer optional No description.
seek integer optional No description.
buildkitemcp_rebuild_build # Rebuild/retry an entire build on a Buildkite pipeline 3 params

Rebuild/retry an entire build on a Buildkite pipeline

Name Type Required Description
build_number string required No description.
org_slug string required No description.
pipeline_slug string required No description.
buildkitemcp_resume_cluster_queue_dispatch # Resume dispatch on a paused cluster queue, allowing jobs to be dispatched to agents again 3 params

Resume dispatch on a paused cluster queue, allowing jobs to be dispatched to agents again

Name Type Required Description
cluster_id string required No description.
org_slug string required No description.
queue_id string required No description.
buildkitemcp_retry_job # Retry a specific failed or timed out job in a Buildkite build 4 params

Retry a specific failed or timed out job in a Buildkite build

Name Type Required Description
build_number string required No description.
job_id string required No description.
org_slug string required No description.
pipeline_slug string required No description.
buildkitemcp_search_logs # Search log entries using regex patterns with optional context lines. For recent failures, try 'tail_logs' first, then use search_logs with patterns like 'error|failed|exception' and limit: 10-20. The json format: {ts: timestamp_ms, c: content, rn: row_number}. 15 params

Search log entries using regex patterns with optional context lines. For recent failures, try 'tail_logs' first, then use search_logs with patterns like 'error|failed|exception' and limit: 10-20. The json format: {ts: timestamp_ms, c: content, rn: row_number}.

Name Type Required Description
build_number string required No description.
job_id string required No description.
org_slug string required No description.
pattern string required No description.
pipeline_slug string required No description.
after_context integer optional No description.
before_context integer optional No description.
cache_ttl string optional No description.
case_sensitive boolean optional No description.
context integer optional No description.
force_refresh boolean optional No description.
invert_match boolean optional No description.
limit integer optional No description.
reverse boolean optional No description.
seek_start integer optional No description.
buildkitemcp_tail_logs # Show the last N entries from the log file. RECOMMENDED for failure diagnosis - most build failures appear in the final log entries. More token-efficient than read_logs for recent issues. The json format: {ts: timestamp_ms, c: content, rn: row_number}. 7 params

Show the last N entries from the log file. RECOMMENDED for failure diagnosis - most build failures appear in the final log entries. More token-efficient than read_logs for recent issues. The json format: {ts: timestamp_ms, c: content, rn: row_number}.

Name Type Required Description
build_number string required No description.
job_id string required No description.
org_slug string required No description.
pipeline_slug string required No description.
cache_ttl string optional No description.
force_refresh boolean optional No description.
tail integer optional No description.
buildkitemcp_unblock_job # Unblock a blocked job in a Buildkite build to allow it to continue execution 5 params

Unblock a blocked job in a Buildkite build to allow it to continue execution

Name Type Required Description
build_number string required No description.
job_id string required No description.
org_slug string required No description.
pipeline_slug string required No description.
fields object optional JSON object containing string values for block step fields
buildkitemcp_update_cluster # Update an existing cluster's name, description, emoji, color, or default queue 7 params

Update an existing cluster's name, description, emoji, color, or default queue

Name Type Required Description
cluster_id string required No description.
org_slug string required No description.
color string optional New hex color code for the cluster
default_queue_id string optional ID of the default queue for the cluster
description string optional New description for the cluster
emoji string optional New emoji for the cluster
name string optional New name for the cluster
buildkitemcp_update_cluster_queue # Update an existing cluster queue's description or retry agent affinity 5 params

Update an existing cluster queue's description or retry agent affinity

Name Type Required Description
cluster_id string required No description.
org_slug string required No description.
queue_id string required No description.
description string optional New description for the queue
retry_agent_affinity string optional Agent retry affinity: prefer-warmest or prefer-different
buildkitemcp_update_pipeline # Modify an existing Buildkite pipeline's configuration, repository, settings, or metadata 11 params

Modify an existing Buildkite pipeline's configuration, repository, settings, or metadata

Name Type Required Description
org_slug string required No description.
pipeline_slug string required No description.
cancel_running_branch_builds string optional Cancel running builds when new builds are created on the same branch
cluster_id string optional No description.
configuration string optional The pipeline configuration in YAML format
default_branch string optional The default branch for builds and metrics filtering
description string optional No description.
name string optional No description.
repository_url string optional The Git repository URL
skip_queued_branch_builds string optional Skip intermediate builds when new builds are created on the same branch
tags string optional Tags to apply to the pipeline for filtering and organization
buildkitemcp_update_pipeline_schedule # Modify an existing pipeline schedule's cron expression, branch, environment variables, or enabled state 10 params

Modify an existing pipeline schedule's cron expression, branch, environment variables, or enabled state

Name Type Required Description
org_slug string required No description.
pipeline_slug string required No description.
schedule_id string required No description.
branch string optional No description.
commit string optional No description.
cronline string optional Schedule interval as a crontab expression or predefined value
enabled string optional Whether the schedule is active. Re-enabling clears previous failure data.
env object optional Environment variables to set on triggered builds. Providing this field REPLACES the existing env map entirely — include all keys you want to retain.
label string optional No description.
message string optional No description.
buildkitemcp_user_token_organization # Get the organization associated with the user token used for this request 0 params

Get the organization associated with the user token used for this request