Harness MCPサーバーでClaude CodeからCI/CDパイプラインを操作する

Harness公式のMCPサーバー(harness/mcp-server、npmパッケージ名はharness-mcp-v2)は、Harnessのパイプライン実行、失敗の診断、サービスや環境の参照をClaude Codeから自然文で頼めるようにします。ツールは11個に絞られており、Harnessのリソースは種類名(resource_type)で指定します。接続方法は3通りで、手元で動かすnpx版、Harnessが運営するホスト型、自前で立てるHTTP版です。

この記事では接続の手順に加えて、実行を任せる範囲をどこで区切るかを扱います。パイプラインの実行やリソースの削除まで通る道具なので、Claude Code側の権限設定とサーバー側の設定の両方で歯止めをかけておくと安心です。

Harness MCPサーバーは11のツールで何を任せられるか

このサーバーは、APIのエンドポイントごとにツールを作る方式を採っていません。READMEによると、そうするとHarnessでは240以上のツールになり、LLMのツール選択が鈍るうえにスキーマでコンテキストが埋まるためです。代わりに11のツールが261のリソース種類に対して働きます。

読み取りはdescribe・list・get・search・status・diagnose、書き込みはcreate・update・delete・executeと、役割で二分できます。後半の権限設定は、この線で引きます。

対象範囲も広く、既定で有効なツールセットは46個中の42個です。CI/CDのほか、GitOps、フィーチャーフラグ、クラウドコスト管理、セキュリティテスト、カオスエンジニアリングなどを含みます。パイプラインの操作だけが目的なら、後述の絞り込みで不要な領域を外せます。

3つの接続方法を選ぶ

認証の仕組みが違うため、選び方は「誰の権限でHarnessを触らせたいか」で決まります。

まず試すなら、npx版が早道です。

APIキーを用意してnpx版を登録する

Harnessにログインし、My Profile → API Keys → New API Keyの順に進み、キーの下にトークンを作ります。トークンは<接頭辞>.<アカウントID>.<トークンID>.<シークレット>の形式です。アカウントIDはトークンから自動で取り出されるため、HARNESS_ACCOUNT_IDの指定は、アカウントIDを含まないキーのときだけ必要です。

Claude Codeへの登録は、READMEにあるclaude mcp add harness -- npx harness-mcp-v2が基本形です。キーを渡すには--envを足します。

claude mcp add --transport stdio \
  --env HARNESS_API_KEY=pat.xxx.xxx.xxx \
  harness -- npx -y harness-mcp-v2@latest

--envの直後にサーバー名を置くと、名前が環境変数の組として解釈されます。上のように--transportを間に挟むと、この問題を避けられます。保存先は既定で自分だけが使えるlocalスコープです。チームで設定を共有する場合は--scope projectで.mcp.jsonに書き出せますが、キーそのものを書き込まないでください。.mcp.jsonは環境変数の展開に対応しているので、キーは${HARNESS_API_KEY}の参照にして、実体は各自の環境に置く形にします。

登録後は、Claude Code内で/mcpを開いてharnessが接続済みになっているかを確かめます。Claude Code側の資料によると、MCPサーバーの起動待ちが長いときは、MCP_TIMEOUT(例: MCP_TIMEOUT=10000 claudeで10秒)で時間切れまでの長さを変えられます。npxの初回取得が遅い環境で役立ちます。

ホスト型に繋ぐ

ホスト型を有効にしてもらった場合は、URLを指定するHTTP接続です。

claude mcp add --transport http harness https://mcp.harness.io/mcp

Claude Codeの/mcpからOAuthのサインインに進みます。READMEの設定例では、事前登録のクライアントIDとしてmcp-clientが示されています。動的なクライアント登録に対応しない接続で認証が通らないときは、claude mcp addの--client-idに渡す選択肢があります。ホスト型のURLはHarnessが管理しており、クライアント側の設定から接続先の環境を切り替えることはできません。専用環境のHarnessを使っている場合は、Harness Supportに有効化を依頼するか、npx版でHARNESS_BASE_URLを指定します。

パイプラインの実行を会話で任せる

実行はharness_executeの担当です。Claudeには、次のように頼みます。

deploy_appパイプラインをmainブランチで実行して、終わるまで待って結果を教えて

このとき裏で組み立てられるのは、概ね次の呼び出しです。READMEの例に沿った形で、実際の引数はClaudeの判断で変わります。

{
  "resource_type": "pipeline",
  "action": "run",
  "resource_id": "deploy_app",
  "inputs": { "branch": "main" },
  "wait": true,
  "wait_timeout_seconds": 900
}

ここで押さえておく点が3つあります。

ランタイム入力を先に確かめさせる

実行前にruntime_input_templateをharness_getで取ると、そのパイプラインが実行時に求める値(<+input>の箇所)が分かります。READMEはこの手順を推奨しており、実行時の入力エラーが減るとしています。値が足りないときは、実行前の検査でエラーになり、期待されるキーや候補の入力セットが返ります。CIのコードベース指定には省略形があり、branch・tag・pr_number・commit_shaをそのまま渡せます。inputs.buildを明示した場合は、省略形の展開は行われません。

待ち合わせはサーバー側に任せる

wait: trueを付けると、サーバーが終了状態になるまで状況を確認し続けます。Claude側で確認の繰り返しを回さずに済み、1回の呼び出しで起動から結果までが返ります。待ち時間の既定は600秒で、10秒から7200秒の範囲で変えられます。確認の間隔は3秒から始まり、1.5倍ずつ延びて30秒で頭打ちになります。

タイムアウトしても、起動そのものは成功しています。応答にはexecution_timed_out: trueが付くので、Claudeには「再実行せず、まず実行中かどうかを確かめて」と添えておくと、二重起動を防げます。READMEも、最初の実行が動いていないと確認できるまでは再実行しないよう注意しています。

再実行・リトライも同じ道を通る

pipeline.retryにも同じwaitが使えます。失敗した実行のやり直しを頼むときは、元の実行IDをClaudeに伝えると、取り違えが起きにくくなります。HarnessのUIのURLを貼ると、組織・プロジェクト・パイプライン・実行のIDがサーバー側で取り出されるため、IDを調べる手間も省けます。

失敗したパイプラインの原因をログから探る

失敗の調査はharness_diagnoseが担当します。パイプラインに対しては、ステージとステップごとの所要時間と、失敗の詳細を返します。wait付きの実行が失敗で終わった場合、応答にはharness_diagnoseを呼ぶためのヒント(_diagnose_hint)が入るので、Claudeは実行の直後に原因の調査へ進めます。

頼み方の例を並べます。

• 「直近で失敗したデプロイの実行を診断して、落ちたステップとその理由を教えて」
• 「デリゲートが接続できないというエラーが出ている。デリゲートの状態を診断して」
• 「このプロジェクトの失敗率と、最近の実行をまとめて」(harness_status)

入力の違いが原因の失敗には、execution_inputsというリソースが使えます。実行に使われた入力YAMLを、入力セットの統合後の形で取得できます。入力セットのマージやGitに置いた入力セットのブランチ違いなど、実行画面だけでは再現しにくい差を突き止める用途です。参照専用で、書き込みは起きません。

ログの取得では、失敗したステップのログを並行してダウンロードします。並行数はHARNESS_DIAGNOSE_LOG_FETCH_CONCURRENCYで増やせますが、READMEは待ち時間がログ取得に支配されていて、メモリに余裕がある場合に限るとしています。

書き込み操作に歯止めをかける

実行・作成・更新・削除が通る道具を、承認なしに走らせない設計が要ります。止める場所は3つあります。

サーバー側の承認はClaude Codeで通るか

READMEの表では、承認に対応するクライアントとしてCursorとVS Code(Copilot)が「Yes」、Claude DesktopとDevin Desktopが「Not yet」とされています。Claude Codeは表に載っていません。一方、Claude Code側の資料には、MCPサーバーの要求に応じて入力用のダイアログが自動で出るとあります。それでも、サーバー側の承認だけに頼るのは避けます。ダイアログを出せない環境では、confirm: trueを付けた呼び出しが通る仕様になっているためです。

承認のダイアログが出せない環境では、要求が自動で辞退される事例もあります。VS Code拡張の現状はMCP elicitationが自動辞退される不具合にまとめています。

Claude Code側で止めるには、書き込み系のツールだけを承認制にします。

{
  "permissions": {
    "ask": [
      "mcp__harness__harness_execute",
      "mcp__harness__harness_create",
      "mcp__harness__harness_update"
    ],
    "deny": [
      "mcp__harness__harness_delete"
    ]
  }
}

ツール名はmcp__<サーバー名>__<ツール名>の形式で、サーバー名はclaude mcp addで付けた名前です。上の例はharnessと登録した前提です。権限ルールの考え方は/permissionsコマンドの解説で詳しく扱っています。

自動承認の天井を理解する

自動化の場面では、HARNESS_AUTO_APPROVE_RISKで自動承認の上限を決められます。値はnone・low_write・medium_write・high_write・allで、既定はnoneです。allにすると書き込みも破壊的な操作も確認なしで進みます。HTTP版では、セッションの接続時にx-harness-auto-approve-riskヘッダーでより厳しい値を選べますが、サーバー側の上限を超える値にはなりません。

使うツールと範囲を絞って運用する

初期状態のままでも動きます。運用に入るなら、次の設定を見ておきます。

非既定のツールセットは次の4つです。

ansible
autonomous_work
observability-evaluations
registries-v3

監査の記録には、ツール名・リソース種類・操作・識別子・時刻・リスク・結果・所要時間・承認の経路が入ります。参照系の記録には承認の情報が付かず、harness_describeとharness_schemaは記録の対象外です。チームで使う場合は、1人のキーを共有するより、利用者ごとのキーが流れるマルチユーザーモードか、OAuthモードのほうが「誰が実行したか」を残せます。

他のCI/CD向けMCPサーバーとの違い

CircleCI、Buildkite、Jenkinsなど、別のCIのMCPサーバーにも失敗診断の機能があります。CircleCI/Buildkite/Jenkins MCP比較で並べたように、Harnessは1つのサーバーがCI/CDからフィーチャーフラグ、コスト管理までを覆うので、ツールセットの絞り込みが前提になります。

CD側の動きでは、GitOpsで同期を任せるArgoCD MCPサーバーが近い位置にあります。Harnessのサーバーはharness_executeでGitOpsアプリの同期も扱えるため、ArgoCDと併用する場合は、どちらに同期を頼むかを決めておくと、二重の操作を防げます。CircleCIのMCPを実際に繋ぐ手順は、ClaudeとCircleCIの連携にあります。

接続できないときの切り分け

• 起動前にspawn npx ENOENTやnode: No such file or directoryが出る: クライアントがプロセスを起動できていない状態で、APIキーは関係ありません。READMEはGUIクライアントがシェルのPATHを引き継がないことを原因に挙げ、npxの絶対パスとPATHの指定を勧めています
• ホスト型が使えない: アカウントごとに有効化が必要です。APIキーを設定しても通りません
• HTTP版で認証エラーになる: HARNESS_MCP_AUTH_TOKENを設定した場合、/mcpへのすべてのリクエストにAuthorization: Bearer <token>が要ります。ループバック以外で公開するときは、この設定が既定で必須です
• 認証が通っても組織・プロジェクトが見つからない: HARNESS_ORGとHARNESS_PROJECTを設定するか、ClaudeにまずAPIで組織とプロジェクトを列挙させます

まとめ

Harness MCPサーバーは、11のツールで広いリソースを扱うため、任せる範囲の線引きが使い勝手を左右します。調査だけならサーバーを読み取り専用で起動し、実行まで任せるならharness_executeを承認制にします。削除はdenyで閉じたままにしておくのが無難です。待ち合わせにはwait: trueを使い、タイムアウト後の再実行は状況の確認を挟みます。