Gemini Cloud Assist MCPをClaude Codeにつないで障害調査する手順

Gemini Cloud Assist MCPは、Google Cloudの障害調査やTerraformレビューを「Cloud Operator」というエージェントに任せるためのMCPサーバーです。Claude Codeからは、プラグインを入れて/cloud-operator:setupを実行すると接続できます。ただしCloud OperatorとそのMCPサーバーはPrivate Previewで、利用にはGoogle Cloudの許可リスト登録が要ります。

先に押さえておくことは3つです。

• 接続先はhttps://geminicloudassist.googleapis.com/mcp/autocloudで、Claude Code側にはautocloudという名前のMCPサーバーとして登録される
• 使えるツールはask_cloud_operatorなど3つだけ
• 認証はOAuthクライアントを自分のプロジェクトに作る方式が基本で、gcloudのコマンドを直接ラップするgcloud MCPサーバーとは設計が違う

Gemini Cloud Assist MCPとは — Cloud Operatorに仕事を委ねるサーバー

リポジトリはGoogleCloudPlatform/gemini-cloud-assist-mcpです。READMEでは「自然言語でGoogle Cloud環境を理解・管理・トラブルシュートする」ためのサーバーと説明されています。

READMEが挙げるCloud Operatorの守備範囲は5つです。

ここで見落としやすいのが、gcloud MCPサーバーとの違いです。gcloud MCPサーバーはrun_gcloud_commandでClaudeがコマンドを組み立てて実行します。Cloud Operatorでは、Claudeは依頼を渡す窓口になり、Google Cloud側のツール呼び出しはOperatorエージェントが内部で行います。READMEにも「MCPツール呼び出しで起動されたエージェントが、Google Cloudへの自前のツール呼び出しを内部で行う」と書かれています。

ローカル版からリモート版への移行

このサーバーは、ローカルのNode.jsで動く構成からリモートMCPサーバー構成へ移行しました。リモート版を使うにはv0.8.0以降が必要で、READMEは旧ローカル版が数か月のうちにサポート終了すると告げています。旧版を移行期間中も使うなら、設定を古いバージョンに固定します。

リモート版の設定は、HTTPのURLを指定する形です。

3つのツールと、つながらないツール

/mcp/autocloudのエンドポイントが提供するのは次の3つです。

READMEにはask_cloud_assist・design_infra・investigate_issue・invoke_operation・optimize_costsという別のツールも載っています。これらはhttps://geminicloudassist.googleapis.com/mcp側のツールで、このリポジトリの設定からは使えません。リポジトリの設定どおりに接続してinvestigate_issueが出てこなくても、不具合ではなく仕様です。

前提条件 — 許可リスト、IAMロール、OAuthクライアント

接続の前に、次を揃えます。

• Cloud Operatorへのアクセス(許可リストに入ったプロジェクトと、Operatorエージェント)
• そのプロジェクトでroles/geminicloudassist.user
• APIの有効化に必要な権限。READMEではroles/serviceusage.serviceUsageAdminが挙がっている
• Google Cloud CLI(gcloud)と、Claude Code本体
• OAuthクライアントを作れる権限。オンボーディングガイドでは、プロジェクトのOwnerかEditor、またはService Usage AdminとOAuth Config Editorが挙がっている

オンボーディングガイドは所要時間を約15分と見積もっています。

プロジェクトは2つ出てくる点に注意してください。OAuthクライアントを作るプロジェクトと、Operatorエージェントがいるプロジェクトは別でもかまいません。ガイドでは前者を<PROJECT_ID>、後者を<AGENT_PROJECT>と呼び分けています。既存のOAuthクライアントがあれば、前者の作成手順は飛ばせます。

プラグインを入れて/cloud-operator:setupを実行する

Claude Code向けの手順は2段階です。最初に、セットアップに使うGoogleアカウントでgcloudにログインしてからインストーラーを流します。

gcloud auth login
curl -fsSL https://raw.githubusercontent.com/GoogleCloudPlatform/\
gemini-cloud-assist-mcp/main/plugins/cloud-operator/claude/install.sh \
  | bash
claude plugin list

claude plugin listでcloud-operatorが有効になっていることを確かめ、Claude Codeを再起動します。インストーラーはプラグインを入れるだけで、何も質問しません。URLは見やすさのために折っています。実際は1行のURLで実行してください。

次に、Claude Codeの中で案内付きセットアップを実行します。

/cloud-operator:setup <PROJECT_ID>

案内付きセットアップは、OAuthクライアントがあるかを尋ね、Consoleでの操作ごとに待ちながら進みます。クライアントシークレットが会話に残らないよう、登録は自分のターミナルでregister-mcp.shを実行する形です。そのあとClaude Codeを再起動すると続きから再開できます(claude -c)。最後にOperatorを動かすプロジェクトを尋ね、エージェントの応答を確認し、設定の聞き取りまで進みます。

手動で登録する場合の流れ

案内付きセットアップが途中で止まったときや、中身を把握したいときは、同じ手順を手で踏めます。

手でMCPサーバーを登録するコマンドは次のとおりです。

claude mcp remove autocloud -s user 2>/dev/null
claude mcp add-json -s user autocloud \
  '{"type":"http","url":"https://geminicloudassist.googleapis.com/mcp/autocloud","timeout":1800000,"oauth":{"clientId":"<CLIENT_ID>"}}' \
  --client-secret
claude mcp get autocloud

--client-secretを付けるとシークレットを対話入力で渡せるので、シェル履歴に残りません。timeoutが1800000ミリ秒、つまり30分なのは、Operatorの呼び出しが長くかかるためです。登録後のclaude mcp get autocloudは、認証前ならNeeds authenticationとScope: Userを返すのが期待値です。認証は/mcpでautocloudを選んでAuthenticateするか、シェルからclaude mcp login autocloudで行います。通るとConnectedになります。

Scope:がLocalやProjectになっていたら、古いエントリが先に効いています。claude mcp remove autocloud -s localなどで消してから確認し直してください。

試すだけなら、アクセストークンでも動く

OAuthのログインが通せないときや、先に試したいときの代替が用意されています。

gcloud auth application-default login
claude mcp remove autocloud -s user 2>/dev/null
claude mcp add-json -s user autocloud "{\"type\":\"http\",\"url\":\"https://geminicloudassist.googleapis.com/mcp/autocloud\",\"timeout\":1800000,\"headers\":{\"Authorization\":\"Bearer $(gcloud auth application-default print-access-token)\"}}"

注意点が3つあります。

• トークンはApplication Default Credentialsのものを使う。普通のgcloud auth print-access-tokenのトークンはサーバーに拒否される
• 約1時間で失効し、更新されない。呼び出しが失敗したらadd-jsonの行をやり直す
• トークンは~/.claude.jsonに平文で保存される

日常的に使うなら、自動で更新されるOAuth方式のほうが手間がかかりません。Google Cloud認証まわりの切り分けはcredentials expiredの直し方も参考になります。

Operatorエージェントとプロジェクトの指定

Operatorは、あなたのOperatorエージェントがあるプロジェクトで動きます。エージェントがまだないと、呼び出しは「personal operator agent for project … has not been initialized yet」で失敗します。Cloud Consoleのhttps://console.cloud.google.com/autocloud/home?project=<AGENT_PROJECT>でCreate operator agentを押して作ります。作った直後は、応答まで数分かかることがあります。

エージェントIDは通常は不要です。IDを付けない呼び出しは、対象プロジェクトにある個人のOperatorエージェントに届きます。IDはユーザーごと、プロジェクトごとなので、他人のものや別プロジェクトのIDを使うと「The caller does not own agent …」になります。

自分のIDを知りたいときは、Claudeに次のように頼みます。

プロジェクト <AGENT_PROJECT> の最近のcloud operatorセッションを一覧して、エージェントIDを教えて

各セッションのcontextIdはprojects/<AGENT_PROJECT>/locations/global/agents/<AGENT_ID>/sessions/<SESSION_ID>の形で、IDはその中に入っています。

障害調査を頼むときの流れ

セットアップの最後に、/cloud-operator:preferencesで運用上の好みを保存します。既定のプロジェクト、リージョン、命名、変更ポリシー、セキュリティ、コストなどの聞き取りがあり、~/.config/cloud-operator/preferences.mdに保存されます。あとから/cloud-operator:preferences always use europe-west4のように1件だけ足すこともできます。

動作確認には、Operatorにしか答えられない質問が向いています。たとえば次のとおりです。

プロジェクト <AGENT_PROJECT> で動いているCloud Runサービスと、そのリージョンを教えて

Claudeがcloud-operator:autocloud-operatorスキルを起動し、ask_cloud_operatorを呼べば成功です。呼び出しには数分かかることがあります。

障害調査では、たとえば次のように頼みます。

本番プロジェクトで、昨夜から checkout サービスの5xxが増えている。
直近のデプロイとログを見て、根本原因の候補を挙げて

この文面は一例です。出力の中身はプロジェクトの状況次第なので、ここでは掲載しません。

スキルが呼び出しをどう整えるか

autocloud-operatorスキルの記述から、挙動が分かる点を挙げます。

• 1つの論理的な依頼につき呼び出しは1回。最大30分かかるため、遅くてもキャンセル・再試行・二重実行はしない
• projectはprojects/<project_id>の形で、ユーザーが指定したもの、設定の既定値、gcloud config get-value projectの順に決める。それでも決まらなければ質問する
• Operatorはローカルのファイルシステムを見られない。そのためエラーログや参照ファイルの全文を、見出しにパスを付けて依頼に添える
• 認証情報ファイル(.env・サービスアカウントキーJSON・kubeconfig・*.tfstate)は送らない。パスワードやトークンは<REDACTED>に置き換え、置き換えたことをユーザーに伝える
• 続きの質問には前回の応答のcontext_idを渡す。プロジェクトが変わるときは新しいセッションを始める
• 401・403のときは、autocloudの再認証を案内する

生成されたTerraformやYAMLは、チャットに貼るだけで終わらせず、ワークスペースにファイルとして書き出します。既存ファイルの変更では、ローカルを基準にした差分を見せ、修正の依頼なら適用します。レビューだけの依頼なら、差分を見せたうえで適用してよいかを尋ねます。

つまずきと直し方

オンボーディングガイドの表から、遭遇しやすいものを抜き出します。

ルートのプラグインgemini-cloud-assist-mcpと、このcloud-operatorプラグインは同時に入れないでください。どちらも同じルーティングスキルを持ち、同じ依頼を取り合います。Claude Codeではcloud-operatorのほうがルートのものを置き換える位置づけで、インストーラーがルートのプラグインを外します。

他のクライアントとの違い、gcloud MCPとの使い分け

同じリポジトリのREADMEには、Antigravity向けのmcp_config.jsonと、Cursor向けのOAuth設定も載っています。Antigravityはサーバーをgoogle_credentialsで認証する設定を書くだけです。Cursorは自分のプロジェクトでデスクトップアプリ向けのOAuthクライアントを作り、リダイレクトURLをURI://anysphere.cursor-mcp/oauth/callbackにします。Claude Codeだけはプラグインが登録と設定の聞き取りを肩代わりするので、手作業は少なめです。

Google Cloudを操作するMCPサーバーは、性格がはっきり分かれます。

READMEは、Google Cloud利用規約とデータ処理規約が、このMCPサーバーのソフトウェアのどの部分にも適用されないと注記しています。組織で使う前に、法務やセキュリティの確認を通してください。IAMで制御するGoogle Cloudのホスト型MCPサーバー群を使う場合は、IAMでの権限制御を併せて見てください。

アップデートと削除

更新はインストーラーを再実行してClaude Codeを再起動するだけです。サーバー登録、サインイン、設定は残ります。削除はbash -s -- --uninstallを付けて実行します。プラグインとautocloudサーバー、サインインが消えます。~/.config/cloud-operator/の設定ファイルは残ります。

まとめ

Gemini Cloud Assist MCPは、gcloudを叩く道具ではなく、Google Cloudの調査を丸ごと任せる相手です。そのぶん、許可リスト、OAuthクライアント、Operatorエージェントの準備が前段にあります。まず許可リストの登録を済ませ、Desktop型のOAuthクライアントで/cloud-operator:setupを通せば、あとは自然文で障害調査を頼めます。Private Previewなので、ツールの形が変わる前提で、運用に組み込むのは挙動を確かめてからにしてください。