ClaudeとBuildkiteを連携してパイプラインとジョブログを調査する

BuildkiteのCIが落ちたとき、ビルド番号やURLをClaudeに渡して原因を調べさせたい。その入口になるのが、Buildkiteが公開しているオープンソースのMCPサーバーです。パイプライン・ビルド・ジョブのデータに加え、Test Engineのテスト結果までAIアシスタントから扱えます。接続先はBuildkiteがホストするリモート型と、自分で動かすローカル型の2種類です。Claude Code・claude.ai・Claude Desktopへの接続手順、調査に使うツール、書き込みを止める設定を順に扱います。

リモート型とローカル型、どちらを使うか

リモート型には、用途の違うエンドポイントが3つあります。

OAuth型は、対話認証を完了できない自動ワークフローには向きません。パイプラインの中からAIエージェントとして呼ぶなら、バージョンを固定できるローカル型を選びます。トークンをすでに持つ常駐エージェントなら/directも使えます。

BuildkiteのMCPサーバーは開発が活発で、ツールや挙動が変わったり削除されたりする可能性があります。特定のツールの挙動を保ちたいときは、版を固定します。Dockerならbuildkite/mcp-serverをbuildkite/mcp-server:<version>のようなタグに替えるか、特定リリースのバイナリを使います。Buildkiteがホストするリモートのエンドポイントは自動で更新され、版を固定できません。

Claude Codeにリモートサーバーを繋ぐ

Claude Codeのインストール後、次のコマンドでリモートサーバーを追加します。

claude mcp add --transport http buildkite https://mcp.buildkite.com/mcp

追加後の初回接続でOAuthの認可画面が開きます。Buildkiteの組織を選んでAuthorizeを押す流れで、組織がSSOを求める場合は先にSSOでログインしてから戻ります。Claude Code v2.1.289のclaude mcp add --helpには、HTTPサーバー向けに-t, --transportと-H, --headerが載っています。保存先を選ぶ-s, --scopeの既定はlocalです。ヘルプの例には、--header "Authorization: Bearer ..."でヘッダーを渡す書式も載っています。

複数の組織を使い分ける

複数のBuildkite組織に所属していると、認可画面でどの組織に許可を与えたのかが曖昧になります。URLにorganizationパラメーターを付けると、認可画面でその組織が選択済みになります。組織ごとに別名で登録すれば、ツール呼び出しがどの組織に向かうのかも名前で区別できます。

claude mcp add --transport http buildkite-acme "https://mcp.buildkite.com/mcp?organization=acme"
claude mcp add --transport http buildkite-other "https://mcp.buildkite.com/mcp?organization=other"

このパラメーターは認可画面の初期選択を決めるだけで、アクセス制御ではありません。slugの代わりにorganization_uuidも使えます。

claude.aiとClaude Desktopにカスタムコネクタとして繋ぐ

組織のAPI IPアドレス許可リストを設定している場合は、BuildkiteのegressのIPアドレスを許可リストに加える必要があります。リモートMCPサーバーはBuildkiteのインフラからAPIを呼ぶためです。そのアドレスはBuildkiteのmeta APIから取得できます。API呼び出しはこの許可リストの対象です。

ツールセットを絞るときは、コネクタをツールセットごとに別々に作ります。名前はBuildkite - pipelines toolsetのように、絞り込みの内容が分かるものにします。URLはhttps://mcp.buildkite.com/mcp/x/pipelinesの形で、複数のコネクタを同じセッションで使うには、それぞれに接続します。

ローカルMCPサーバーをDockerで動かす

ローカル型は、Buildkiteパイプラインから呼ぶ自動化や、実行バージョンを固定したい場合に使います。Docker 20.x以降が必要です。イメージはcgr.dev/chainguard/staticを土台にし、非特権ユーザーで動きます。READMEは、安全に動かすためにコンテナでの実行を勧めています。

docker pull buildkite/mcp-server
docker run --pull=always -q -it --rm \
  -e BUILDKITE_API_TOKEN=<api-token-value> \
  buildkite/mcp-server stdio

Claude Codeからこのローカルサーバーに繋ぐには、Docker実行とバイナリ実行で登録コマンドが変わります。

# Docker で動かす場合
claude mcp add buildkite -- docker run --pull=always -q --rm -i \
  -e BUILDKITE_API_TOKEN=bkua_xxxxx buildkite/mcp-server stdio
 
# ビルド済みバイナリを入れている場合
claude mcp add buildkite --env BUILDKITE_API_TOKEN=bkua_xxxxx -- buildkite-mcp-server stdio

Claude Desktopから使うなら、claude_desktop_config.jsonに書きます。ファイルは「Settings > Developer > Edit Config」ボタンから開けます。

--pull=alwaysは、起動のたびに最新のイメージを取得する指定です。APIアクセストークンは、Buildkiteのユーザー設定の「API Access Tokens」から発行します。

トークンのスコープは最小限にできます。最小構成はread_builds・read_pipelines・read_userで、ログを読むならread_build_logsを足し、書き込みを許すときだけwrite_buildsを加えます。

ローカル型には、自前ホストのHTTPモードもあります。buildkite-mcp-server httpで起動すると、http://localhost:3000/mcpでストリーミングHTTPとして待ち受けます。このモードではOAuthは起動しません。トークンを1Passwordに置く場合の環境変数としてBUILDKITE_API_TOKEN_FROM_1PASSWORDもあります。

Buildkite MCPで何ができるか

MCPサーバーはBuildkiteのREST APIをラップしています。ツールは多数ありますが、障害調査で頻繁に触れるのは次のあたりです。

ジョブの再試行やブロック解除のツールは、buildsツールセットに含まれます。

繋いだだけでは監視されない

コネクタを繋いでも、AIツールがビルドを見張り始めるわけではありません。「Buildkite MCPサーバーを使って」とはっきり頼む必要があります。ビルドの完了待ちにはwait_for_buildがあり、1回の呼び出しで最長45秒待ちます。ブロックされたビルドは「終わった」とみなされ、入力待ちだと報告されます。長く見張らせるには、AIツール側で呼び出しを繰り返すか、自前のスケジュールを使います。

ビルド失敗を調べる流れ

ログのツールは、ジョブのログをParquet形式にして保存し、検索や読み取りを速くします。完了や失敗、キャンセルといった終了状態のジョブのログは保存され続けます。実行中やブロック中のジョブのログは、30秒だけ保持されます。ローカル型の保存先は、物理マシンならホームの.bklog、コンテナなら/tmp/bklogで、BKLOG_CACHE_URLでローカルパスかs3://に変えられます。

ツールセットと読み取り専用で権限を絞る

MCPサーバーはツールをツールセットにまとめています。user・pipelines・builds・investigations・logs・artifacts・annotations・tests・clustersなどです。必要なものだけを有効にすると、AIツールが触れるBuildkite APIの範囲が狭まります。

注意が要るのは、buildsツールセットが読み取りだけではない点です。create_build・cancel_build・rebuild_build・retry_job・unblock_jobがここに含まれます。調査だけをさせたいなら、buildsを入れたうえで読み取り専用を併用します。

リモート型で単一のツールセットに絞るには、URLに/x/{ツールセット名}を足します。

claude mcp add --transport http buildkite-builds https://mcp.buildkite.com/mcp/x/builds/readonly

複数のツールセットを組み合わせるときは、読み取り専用のURLにヘッダーでツールセットを渡します。

claude mcp add --transport http buildkite-read-only-toolsets \
  https://mcp.buildkite.com/mcp/readonly \
  --header "X-Buildkite-Toolsets: user,pipelines,builds"

ローカル型でも同じ絞り込みができます。Dockerなら環境変数のBUILDKITE_TOOLSETSとBUILDKITE_READ_ONLY、バイナリなら--enabled-toolsetsと--read-onlyを使います。何も指定しなければ全ツールセットが有効で、トークンの権限で許される範囲のBuildkite APIに触れられます。

用途別の組み合わせ例です。userツールセットは基本情報を返すので、どの構成にも入れておきます。

一部だけ書き込みを許したい場合は、読み取り用と書き込み用に設定を2つ作ります。たとえばbuildsは通常のURLで、userとpipelinesは読み取り専用のURLで、という分け方です。名前はbuildkite-read-only-user-pipelinesのように、権限が分かるものにします。

/directのAPIトークン経由では、トークンの権限が接続とは別に残ります。そのため読み取りのエンドポイントを選んでも、トークン自体の権限は小さくしておく必要があります。

CLAUDE.mdにヒントを書いて精度を上げる

Buildkiteは、AGENTS.md(Claude CodeではCLAUDE.md)に組織名とパイプラインslugのヒントを書くことを勧めています。ツールが繋がっていても、どの組織のどのパイプラインかをClaudeが推測する状態だと、質問のたびに確認が挟まります。

- **CI/CD**: `my-buildkite-organization` Buildkiteオーガニゼーション、build/testは`my-pipeline`パイプラインslug(`.buildkite/pipeline.yml`)、リリースは`my-pipeline-release`パイプラインslug(`.buildkite/pipeline.release.yml`)

自分の組織名・パイプラインslug・設定ファイル名に置き換え、アーキテクチャ節などに1行加えます。

よくあるつまずき

リモート型のOAuthアクセストークンの有効期限は12時間、リフレッシュトークンは7日間です。放置したセッションで急に認証エラーが出たら、期限切れを疑って再認証します。

リモート型のレート制限は、ユーザーごとに1分あたり50リクエストです。OAuthの/mcpと/directのどちらにも同じ上限がかかり、組織のREST APIの枠は消費しません。上限を超えると429が返り、ウィンドウは60秒で戻ります。各レスポンスのRateLimit-RemainingとRateLimit-Resetで残りの回数を確かめられ、RateLimit-Resetは日時ではなく、次のウィンドウまでの秒数です。自動リトライを組むなら、この値をそのまま待機秒数に使えます。429の本文にも、待つべき秒数が文章とresetフィールドで入ります。

ローカル型は逆に、組織の標準のREST APIレート制限を消費します。

読み取り専用のエンドポイントでは、必要なトークンスコープがread_で始まるツールと、スコープ指定のないツールだけが使えます。ビルドの作成やジョブの再試行を頼んで失敗するのは、権限不足であって設定ミスではありません。接続しているURLが/readonly付きかを見ます。

cache_registriesツールセットは、ローカル型のv1.24.0以前には存在しません。古いバイナリやイメージを使い続けていると、ツールセットを指定してもツールが現れないので、版を確かめます。

まとめ

個人の対話利用はリモート型、バージョンを固定したい自動化はローカル型です。/directやローカル型はAPIトークンで動くので、スコープをread_builds・read_pipelines・read_userの最小構成から始め、書き込みが要るときだけwrite_buildsを足します。Kubernetes側のMCPサーバー運用でも、権限を絞る考え方は共通します。詳しくはKubernetes MCPサーバーの記事にあります。IaC寄りの構成管理まで任せたい場合はTerraform MCPサーバーも参考になります。

コネクタの権限設定でつまずきやすい点は、Claude Connectorsの権限設定でよくある失敗にあります。