Buildkite MCP connector
OAuth 2.1/DCRDeveloper ToolsAutomationAIConnect to Buildkite MCP. Manage CI/CD pipelines, builds, agents, clusters, and test suites from your AI workflows.
Buildkite MCP connector
-
Install the SDK
Section titled “Install the SDK”Terminal window npm install @scalekit-sdk/nodeTerminal window pip install scalekit -
Set your credentials
Section titled “Set your credentials”Add your Scalekit credentials to your
.envfile. 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> -
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.actionsconst connector = 'buildkitemcp'const identifier = 'user_123'// Generate an authorization link for the userconst { 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 callconst result = await actions.executeTool({connector,identifier,toolName: 'buildkitemcp_list_agents',toolInput: { org_slug: 'YOUR_ORG_SLUG' },})console.log(result)quickstart.py import osfrom scalekit.client import ScalekitClientfrom dotenv import load_dotenvload_dotenv()scalekit_client = ScalekitClient(env_url=os.getenv("SCALEKIT_ENV_URL"),client_id=os.getenv("SCALEKIT_CLIENT_ID"),client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),)actions = scalekit_client.actionsconnection_name = "buildkitemcp"identifier = "user_123"# Generate an authorization link for the userlink_response = actions.get_authorization_link(connection_name=connection_name,identifier=identifier,)print("Authorize Buildkite MCP:", link_response.link)input("Press Enter after authorizing...")# Make your first callresult = actions.execute_tool(tool_input={"org_slug":"YOUR_ORG_SLUG"},tool_name="buildkitemcp_list_agents",connection_name=connection_name,identifier=identifier,)print(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 UUID0 params
Get information about the current API access token including its scopes and UUID
buildkitemcp_cancel_build#Cancel a running build on a Buildkite pipeline3 params
Cancel a running build on a Buildkite pipeline
build_numberstringrequiredNo description.org_slugstringrequiredNo description.pipeline_slugstringrequiredNo description.buildkitemcp_create_annotation#Create an annotation on a build or specific job. Use scope='build' (default) or scope='job' with job_id10 params
Create an annotation on a build or specific job. Use scope='build' (default) or scope='job' with job_id
bodystringrequiredThe annotation body as HTML or Markdownbuild_numberstringrequiredNo description.org_slugstringrequiredNo description.pipeline_slugstringrequiredNo description.appendbooleanoptionalAppend the body to an existing annotation with the same contextcontextstringoptionalOptional annotation context used to identify or append to an annotationjob_idstringoptionalJob ID required when scope is jobpriorityintegeroptionalOptional annotation priority from 1 to 10scopestringoptionalAnnotation scope: 'build' (default) or 'job'. When 'job', job_id is required.stylestringoptionalOptional annotation style: success, info, warning, or errorbuildkitemcp_create_build#Trigger a new build on a Buildkite pipeline for a specific commit and branch, with optional environment variables, metadata, and author information8 params
Trigger a new build on a Buildkite pipeline for a specific commit and branch, with optional environment variables, metadata, and author information
branchstringrequiredNo description.commitstringrequiredThe commit SHA to buildmessagestringrequiredNo description.org_slugstringrequiredNo description.pipeline_slugstringrequiredNo description.environmentstringoptionalEnvironment variables to set for the buildignore_branch_filtersbooleanoptionalWhether to ignore branch filters when triggering the buildmetadatastringoptionalMeta-data values to set for the buildbuildkitemcp_create_cluster#Create a new cluster in an organization5 params
Create a new cluster in an organization
namestringrequiredNo description.org_slugstringrequiredNo description.colorstringoptionalHex color code for the cluster (e.g. #A9CCE3)descriptionstringoptionalDescription of the clusteremojistringoptionalEmoji for the cluster (e.g. :toolbox:)buildkitemcp_create_cluster_queue#Create a new queue in a cluster4 params
Create a new queue in a cluster
cluster_idstringrequiredNo description.keystringrequiredNo description.org_slugstringrequiredNo description.descriptionstringoptionalDescription of the queuebuildkitemcp_create_pipeline#Set up a new CI/CD pipeline in Buildkite with YAML configuration, repository connection, and cluster assignment11 params
Set up a new CI/CD pipeline in Buildkite with YAML configuration, repository connection, and cluster assignment
cluster_idstringrequiredThe cluster ID to assign the pipeline toconfigurationstringrequiredThe pipeline configuration in YAML formatnamestringrequiredNo description.org_slugstringrequiredNo description.repository_urlstringrequiredThe Git repository URLcancel_running_branch_buildsbooleanoptionalCancel running builds when new builds are created on the same branchcreate_webhookbooleanoptionalCreate a GitHub webhook to trigger builds on pull-request and push eventsdefault_branchstringoptionalThe default branch for builds and metrics filteringdescriptionstringoptionalNo description.skip_queued_branch_buildsbooleanoptionalSkip intermediate builds when new builds are created on the same branchtagsstringoptionalTags to apply to the pipeline for filtering and organizationbuildkitemcp_create_pipeline_schedule#Create a new pipeline schedule that triggers builds on a cron-driven interval9 params
Create a new pipeline schedule that triggers builds on a cron-driven interval
cronlinestringrequiredSchedule interval as a crontab expression (e.g. '0 0 * * *') or predefined value (e.g. '@daily'\, '@hourly'\, '@weekly'\, '@monthly'\, '@yearly')org_slugstringrequiredNo description.pipeline_slugstringrequiredNo description.branchstringoptionalTarget branch (defaults to the pipeline default branch)commitstringoptionalCommit reference (defaults to HEAD)enabledstringoptionalWhether the schedule is active. Defaults to true if unset.envobjectoptionalEnvironment variables to set on triggered buildslabelstringoptionalDescriptive label for the schedulemessagestringoptionalMessage attached to triggered buildsbuildkitemcp_current_user#Get details about the user account that owns the API token, including name, email, avatar, and account creation date0 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 status3 params
Get detailed information about a specific agent including its connection state, host details, current job, metadata, and pause status
agent_idstringrequiredNo description.org_slugstringrequiredNo description.detail_levelstringoptionalResponse 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-encoded5 params
Download a specific artifact's content, identified by its organization, pipeline, build, job, and artifact identifiers. The content is returned base64-encoded
artifact_idstringrequiredThe UUID of the artifact to downloadbuild_numberstringrequiredNo description.job_idstringrequiredThe UUID of the job that produced the artifactorg_slugstringrequiredNo description.pipeline_slugstringrequiredNo 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 tools6 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
build_numberstringrequiredNo description.org_slugstringrequiredNo description.pipeline_slugstringrequiredNo description.detail_levelstringoptionalResponse detail level: 'detailed' (default) or 'full'. Detailed includes job IDs/names/states; full includes complete job objectsinclude_agentbooleanoptionalInclude full agent details in job objects. When false (default)\, only agent.id is includedjob_statestringoptionalFilter 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.
build_numberstringrequiredNo description.org_slugstringrequiredNo description.pipeline_slugstringrequiredNo description.buildkitemcp_get_cluster#Get detailed information about a specific cluster including its name, description, default queue, and configuration2 params
Get detailed information about a specific cluster including its name, description, default queue, and configuration
cluster_idstringrequiredNo description.org_slugstringrequiredNo description.buildkitemcp_get_cluster_queue#Get detailed information about a specific queue including its key, description, dispatch status, and hosted agent configuration3 params
Get detailed information about a specific queue including its key, description, dispatch status, and hosted agent configuration
cluster_idstringrequiredNo description.org_slugstringrequiredNo description.queue_idstringrequiredNo 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.
org_slugstringrequiredNo description.run_idstringrequiredNo description.test_suite_slugstringrequiredNo description.include_failure_expandedbooleanoptionalInclude expanded failure details such as full error messages and stack tracespageintegeroptionalPage number for pagination (min 1)per_pageintegeroptionalResults per page for pagination (min 1\, max 100)buildkitemcp_get_job_env#Get the environment variables for a specific job in a Buildkite build4 params
Get the environment variables for a specific job in a Buildkite build
build_numberstringrequiredNo description.job_idstringrequiredNo description.org_slugstringrequiredNo description.pipeline_slugstringrequiredNo description.buildkitemcp_get_pipeline#Get detailed information about a specific pipeline including its configuration, steps, environment variables, and build statistics3 params
Get detailed information about a specific pipeline including its configuration, steps, environment variables, and build statistics
org_slugstringrequiredNo description.pipeline_slugstringrequiredNo description.detail_levelstringoptionalResponse 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 time3 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
org_slugstringrequiredNo description.pipeline_slugstringrequiredNo description.schedule_idstringrequiredNo description.buildkitemcp_get_test#Get a specific test in Buildkite Test Engine. This provides additional metadata for failed test executions3 params
Get a specific test in Buildkite Test Engine. This provides additional metadata for failed test executions
org_slugstringrequiredNo description.test_idstringrequiredNo description.test_suite_slugstringrequiredNo description.buildkitemcp_get_test_run#Get a specific test run in Buildkite Test Engine3 params
Get a specific test run in Buildkite Test Engine
org_slugstringrequiredNo description.run_idstringrequiredNo description.test_suite_slugstringrequiredNo description.buildkitemcp_list_agents#List agents in an organization with their connection state, host details, version, current job, and pause status7 params
List agents in an organization with their connection state, host details, version, current job, and pause status
org_slugstringrequiredNo description.detail_levelstringoptionalResponse detail level: 'summary' (default)\, 'detailed'\, or 'full'hostnamestringoptionalNo description.namestringoptionalNo description.pageintegeroptionalPage number for pagination (min 1)per_pageintegeroptionalResults per page for pagination (min 1\, max 100)versionstringoptionalNo description.buildkitemcp_list_annotations#List annotations for a build or a specific job. Use scope='build' (default) or scope='job' with job_id7 params
List annotations for a build or a specific job. Use scope='build' (default) or scope='job' with job_id
build_numberstringrequiredNo description.org_slugstringrequiredNo description.pipeline_slugstringrequiredNo description.job_idstringoptionalJob ID required when scope is jobpageintegeroptionalPage number for pagination (min 1)per_pageintegeroptionalResults per page for pagination (min 1\, max 100)scopestringoptionalAnnotation 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 URLs5 params
List all artifacts for a build across all jobs, including file details, paths, sizes, MIME types, and download URLs
build_numberstringrequiredNo description.org_slugstringrequiredNo description.pipeline_slugstringrequiredNo description.pageintegeroptionalPage number for pagination (min 1)per_pageintegeroptionalResults 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 URLs6 params
List all artifacts for an individual job, including file details, paths, sizes, MIME types, and download URLs
build_numberstringrequiredNo description.job_idstringrequiredNo description.org_slugstringrequiredNo description.pipeline_slugstringrequiredNo description.pageintegeroptionalPage number for pagination (min 1)per_pageintegeroptionalResults 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 organization9 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
org_slugstringrequiredNo description.branchstringoptionalFilter builds by git branch namecommitstringoptionalFilter builds by specific commit SHAcreatorstringoptionalFilter builds by build creatordetail_levelstringoptionalResponse detail level: 'summary' (default)\, 'detailed'\, or 'full'pageintegeroptionalPage number for pagination (min 1)per_pageintegeroptionalResults per page for pagination (min 1\, max 100)pipeline_slugstringoptionalFilter builds by pipeline. When omitted\, lists builds across all pipelines in the organizationstatestringoptionalFilter 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 configuration4 params
List all queues in a cluster with their keys, descriptions, dispatch status, and agent configuration
cluster_idstringrequiredNo description.org_slugstringrequiredNo description.pageintegeroptionalPage number for pagination (min 1)per_pageintegeroptionalResults 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 details3 params
List all clusters in an organization with their names, descriptions, default queues, and creation details
org_slugstringrequiredNo description.pageintegeroptionalPage number for pagination (min 1)per_pageintegeroptionalResults 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 time4 params
List the pipeline schedules for a pipeline, including cron expression, target branch, environment variables, enabled state, and next scheduled build time
org_slugstringrequiredNo description.pipeline_slugstringrequiredNo description.pageintegeroptionalPage number for pagination (min 1)per_pageintegeroptionalResults 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 status6 params
List all pipelines in an organization with their basic details, build counts, and current status
org_slugstringrequiredNo description.detail_levelstringoptionalResponse detail level: 'summary' (default)\, 'detailed'\, or 'full'namestringoptionalFilter pipelines by namepageintegeroptionalPage number for pagination (min 1)per_pageintegeroptionalResults per page for pagination (min 1\, max 100)repositorystringoptionalFilter pipelines by repository URLbuildkitemcp_list_test_runs#List all test runs for a test suite in Buildkite Test Engine4 params
List all test runs for a test suite in Buildkite Test Engine
org_slugstringrequiredNo description.test_suite_slugstringrequiredNo description.pageintegeroptionalPage number for pagination (min 1)per_pageintegeroptionalResults 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 agents4 params
Pause dispatch on a cluster queue, preventing new jobs from being dispatched to agents
cluster_idstringrequiredNo description.org_slugstringrequiredNo description.queue_idstringrequiredNo description.notestringoptionalReason for pausing dispatchbuildkitemcp_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}.
build_numberstringrequiredNo description.job_idstringrequiredNo description.org_slugstringrequiredNo description.pipeline_slugstringrequiredNo description.cache_ttlstringoptionalNo description.force_refreshbooleanoptionalNo description.limitintegeroptionalNo description.seekintegeroptionalNo description.buildkitemcp_rebuild_build#Rebuild/retry an entire build on a Buildkite pipeline3 params
Rebuild/retry an entire build on a Buildkite pipeline
build_numberstringrequiredNo description.org_slugstringrequiredNo description.pipeline_slugstringrequiredNo description.buildkitemcp_resume_cluster_queue_dispatch#Resume dispatch on a paused cluster queue, allowing jobs to be dispatched to agents again3 params
Resume dispatch on a paused cluster queue, allowing jobs to be dispatched to agents again
cluster_idstringrequiredNo description.org_slugstringrequiredNo description.queue_idstringrequiredNo description.buildkitemcp_retry_job#Retry a specific failed or timed out job in a Buildkite build4 params
Retry a specific failed or timed out job in a Buildkite build
build_numberstringrequiredNo description.job_idstringrequiredNo description.org_slugstringrequiredNo description.pipeline_slugstringrequiredNo 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}.
build_numberstringrequiredNo description.job_idstringrequiredNo description.org_slugstringrequiredNo description.patternstringrequiredNo description.pipeline_slugstringrequiredNo description.after_contextintegeroptionalNo description.before_contextintegeroptionalNo description.cache_ttlstringoptionalNo description.case_sensitivebooleanoptionalNo description.contextintegeroptionalNo description.force_refreshbooleanoptionalNo description.invert_matchbooleanoptionalNo description.limitintegeroptionalNo description.reversebooleanoptionalNo description.seek_startintegeroptionalNo 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}.
build_numberstringrequiredNo description.job_idstringrequiredNo description.org_slugstringrequiredNo description.pipeline_slugstringrequiredNo description.cache_ttlstringoptionalNo description.force_refreshbooleanoptionalNo description.tailintegeroptionalNo description.buildkitemcp_unblock_job#Unblock a blocked job in a Buildkite build to allow it to continue execution5 params
Unblock a blocked job in a Buildkite build to allow it to continue execution
build_numberstringrequiredNo description.job_idstringrequiredNo description.org_slugstringrequiredNo description.pipeline_slugstringrequiredNo description.fieldsobjectoptionalJSON object containing string values for block step fieldsbuildkitemcp_update_cluster#Update an existing cluster's name, description, emoji, color, or default queue7 params
Update an existing cluster's name, description, emoji, color, or default queue
cluster_idstringrequiredNo description.org_slugstringrequiredNo description.colorstringoptionalNew hex color code for the clusterdefault_queue_idstringoptionalID of the default queue for the clusterdescriptionstringoptionalNew description for the clusteremojistringoptionalNew emoji for the clusternamestringoptionalNew name for the clusterbuildkitemcp_update_cluster_queue#Update an existing cluster queue's description or retry agent affinity5 params
Update an existing cluster queue's description or retry agent affinity
cluster_idstringrequiredNo description.org_slugstringrequiredNo description.queue_idstringrequiredNo description.descriptionstringoptionalNew description for the queueretry_agent_affinitystringoptionalAgent retry affinity: prefer-warmest or prefer-differentbuildkitemcp_update_pipeline#Modify an existing Buildkite pipeline's configuration, repository, settings, or metadata11 params
Modify an existing Buildkite pipeline's configuration, repository, settings, or metadata
org_slugstringrequiredNo description.pipeline_slugstringrequiredNo description.cancel_running_branch_buildsstringoptionalCancel running builds when new builds are created on the same branchcluster_idstringoptionalNo description.configurationstringoptionalThe pipeline configuration in YAML formatdefault_branchstringoptionalThe default branch for builds and metrics filteringdescriptionstringoptionalNo description.namestringoptionalNo description.repository_urlstringoptionalThe Git repository URLskip_queued_branch_buildsstringoptionalSkip intermediate builds when new builds are created on the same branchtagsstringoptionalTags to apply to the pipeline for filtering and organizationbuildkitemcp_update_pipeline_schedule#Modify an existing pipeline schedule's cron expression, branch, environment variables, or enabled state10 params
Modify an existing pipeline schedule's cron expression, branch, environment variables, or enabled state
org_slugstringrequiredNo description.pipeline_slugstringrequiredNo description.schedule_idstringrequiredNo description.branchstringoptionalNo description.commitstringoptionalNo description.cronlinestringoptionalSchedule interval as a crontab expression or predefined valueenabledstringoptionalWhether the schedule is active. Re-enabling clears previous failure data.envobjectoptionalEnvironment variables to set on triggered builds. Providing this field REPLACES the existing env map entirely — include all keys you want to retain.labelstringoptionalNo description.messagestringoptionalNo description.buildkitemcp_user_token_organization#Get the organization associated with the user token used for this request0 params
Get the organization associated with the user token used for this request