How to add Buildkite MCP Server to Windsurf

Official Buildkite MCP server to inspect pipelines, builds, jobs and tests and fix failed builds. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 15, 2026 · 60★ · http · oauth · official

Windsurf config for Buildkite MCP Server

Connect client to https://mcp.buildkite.com/mcp and complete OAuth

{
  "mcpServers": {
    "buildkite-mcp-server": {
      "serverUrl": "https://mcp.buildkite.com/mcp"
    }
  }
}

Remote server — no local install needed. Restart the client after saving the config.

Setup steps

1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
2Paste the Buildkite MCP Server config below.
3Fill in placeholder secrets, then save.
4Click Refresh in the MCP panel.
5Buildkite MCP Server's tools become available to Cascade.

Before you start

A Buildkite account with access to the relevant organization and pipelines
For the remote server (recommended): an MCP client that supports remote HTTP MCP + OAuth — connect to https://mcp.buildkite.com/mcp (or /mcp/readonly). No token needed.
For the local server: a Buildkite API access token from https://buildkite.com/user/api-access-tokens with scopes such as read_builds, read_pipelines, read_user (plus read_build_logs, read_artifacts, read_clusters, read_suites for full read; write_builds, write_pipelines for writes)
For local install: one of Homebrew, Docker, the Go toolchain, or a pre-built binary from GitHub Releases

What Buildkite MCP Server can do in Windsurf

current_user / access_token / user_token_organization

Identify the authenticated user, inspect the token's scopes, and resolve the org

list_pipelines / get_pipeline / create_pipeline / update_pipeline

Browse and manage CI/CD pipelines

list_builds / get_build / create_build / cancel_build / rebuild_build

Inspect builds and trigger, cancel, or rebuild them

unblock_job / retry_job / get_job_env

Unblock blocked steps, retry failed jobs, and read job environment

search_logs / tail_logs / read_logs

Search job logs by regex, tail recent output, or read full logs

list_artifacts_for_build / list_artifacts_for_job / get_artifact

List and download build/job artifacts

list_annotations / create_annotation

Read and add build annotations

list_agents / get_agent

Inspect connected Buildkite agents

Security

The remote server exposes your organization's pipeline configuration and build logs, which can contain secrets or sensitive output; review the scopes granted during authorization. For the local variant, treat BUILDKITE_API_TOKEN as a secret.

Buildkite MCP Server + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Buildkite MCP Server config there under the "mcpServers" key and restart the client.

Is Buildkite MCP Server safe to use with Windsurf?

Should I use the remote or local server?

Buildkite recommends the remote server (https://mcp.buildkite.com/mcp). It uses OAuth with short-lived tokens so you don't manage API keys; the local Go binary is for stdio clients or air-gapped setups.

How do I authenticate the remote server?

Via standard OAuth handled by your MCP client — access tokens last 12 hours and refresh tokens 7 days. No manual API token is needed.

What token scopes does the local server need?

At minimum read_builds, read_pipelines, and read_user. For full read access add read_build_logs, read_artifacts, read_clusters, read_organizations, and read_suites; for write actions add write_builds and write_pipelines.

View repo Full Buildkite MCP Server page