Claude Media
Claude Codeのgroundcoverプラグインで本番障害を調べる
Claude CodeMCPClaude連携チュートリアル

Claude Codeのgroundcoverプラグインで本番障害を調べる

groundcoverプラグインは公開MCPサーバーとdiscovery・gcql-advancedの2つのskillsを束ね、権限内の監視データから障害を調べます。導入、OAuth、調べ方の流れ、安全面まで。

読了目安 約13分

groundcoverプラグインは、Claude Codeを監視基盤groundcoverのデータにつなぎ、本番障害の調査とgcQL(groundcoverのクエリ言語)の組み立てを任せるためのプラグインです。中身は公開MCPサーバーへの接続設定と、discovery・gcql-advancedという2つのskillsだけで、認証情報は持ちません。

マーケットプレイスの掲載ページには「Anthropic verified」の表示があり、説明文は「権限のあるgroundcoverの観測データで本番の問題を調べ、高度なgcQLクエリを組み立てる」です。ここでは導入、OAuthの接続、障害調査の進め方、データの扱いまでを順に説明します。

このプラグインに入っているもの

Claude Codeのプラグインは、skillsやMCPサーバーを1つにまとめて配る仕組みです。groundcoverプラグインのリポジトリは、構成が小さいのが特徴です。

中身

プラグインの構成

  • MCP接続設定

    .mcp.json に、https://mcp.groundcover.com/api/mcp へのHTTP接続が1件だけ書かれています。ツールの一覧はコピーせず、Claudeが接続時にサーバーから取得します。

  • discovery

    フィールド名や値、エンティティ、メトリクスを確かめてから読み取り専用のクエリを書くためのskillです。

  • gcql-advanced

    複数パイプ、集計、数式、結合、サブクエリなど、単純でないgcQLを組み立てるためのskillです。

プラグインのバージョンは0.1.0で、変更履歴には2026年9月3日付の初回リリースとして「Claude CodeとCowork向けの初期版」「OAuthで公開MCPサーバーに接続」「discoveryとgcql-advancedを同梱」の3点だけが載っています。ライセンスはMITです。

MCPサーバーとskillsが同じパッケージで届く点は、プラグイン同梱のMCPサーバーと同じ型です。自分で claude mcp add を打つ必要はありません。

入れる前に知っておく認証とデータの範囲

接続先は https://mcp.groundcover.com/api/mcp の1か所だけです。トークンやヘッダーを .mcp.json に書く運用ではなく、ユーザーごとにgroundcoverのOAuthで認証します。

README上、すべてのツール呼び出しは、そのユーザーが持つワークスペースの所属、バックエンドへのアクセス、RBACのロール、データスコープのフィルターの範囲に収まります。Claudeが自分の判断で権限を広げることはありません。つまり、groundcover上で見えない障害データは、Claude Codeからも見えません。

もう1点、書き込みの有無です。

  • 直接のクエリツールは、顧客のリソースや外部システムを変更しません
  • 非同期の調査ツールは、非公開の実行状態(retained agent-run state)を作ったり取り消したりできますが、モニター・インシデント・パイプライン・デプロイ・ワークロードは変更できません

調査用であって、障害対応そのものを自動実行するプラグインではない、という設計です。

インストールする

READMEには、ディレクトリへの掲載先ごとに2通りのコマンドが載っています。どちらを使うかは、Anthropicが承認した掲載先で決まります。

# コミュニティディレクトリ
/plugin marketplace add anthropics/claude-plugins-community
/plugin install groundcover@claude-community
 
# Anthropicのパートナー/公式ディレクトリ
/plugin install groundcover@claude-plugins-official

どちらか一方が通れば足ります。Coworkの場合は、プラグインディレクトリでgroundcoverを探す形です。マーケットプレイスの仕組みはプラグインとマーケットプレイスの解説にまとめています。

手順

導入から最初のクエリまで

  1. 1

    プラグインを入れる

    上のコマンドのどちらかを実行します。

  2. 2

    /mcp を開く

    一覧からgroundcoverを選び、OAuthの画面でgroundcoverにログインします。

  3. 3

    調べたい範囲を伝える

    アカウントに複数のワークスペースやバックエンドがある場合、Claudeは推測せず「どれを使うか」を質問します。

  4. 4

    調べさせる

    障害の症状と時間帯を日本語で伝えます。

ローカルのチェックアウトで試す

導入前にリポジトリの中身を確かめたいときは、クローンして検証してから、プラグインディレクトリ指定で起動できます。

git clone https://github.com/groundcover-com/claude-plugin-groundcover.git
cd claude-plugin-groundcover
claude plugin validate . --strict
claude --plugin-dir .

起動後に /mcp でOAuthを済ませます。ファイルを書き換えたときは、Claude Codeを再起動するか、起動中のセッションで /reload-plugins を実行すると反映されます。

discoveryは「名前を推測しない」ための手順書

障害調査でよく起きるのは、フィールド名や値を慣例で決め打ちして、空の結果を「障害なし」と読んでしまうことです。discovery のskillは、これを避ける手順を定めています。

最初にやることは、list_workspaces でバックエンドとワークスペースを決めることです。候補が複数残るなら質問し、選んだ tenant_uuid と backend_id を以降の呼び出しすべてに渡します。サーバーは状態を持たないので、1回の選択が次の呼び出しに引き継がれないためです。そのうえで、時間範囲とタイムゾーンを区切り、最初のgcQLを書く前に get_gcql_reference を呼びます。

調査の本体は、次の6段の繰り返しです。

  1. 地形をつかむ(メタデータ検索か、範囲を絞った集計)
  2. 候補を選ぶ(いちばん件数が多い群を自動で重要とみなさない)
  3. 形を知る(利用できるメタデータと、少数の実レコードを見る)
  4. 鍵になる値を調べる(慣例的な名前でも、値を作らない)
  5. 検証済みの名前だけで狭いクエリを作る
  6. 根拠が足りなければ、別のシグナルを1回だけ試して不確かさを報告する

シグナルごとの入口も決まっています。ログなら search_logs_metadata、トレースなら search_traces_metadata、イベントなら search_events_metadata を、対応する query_* ツールの前に使います。ワークロードや名前空間は query_entities で解決してから、他のシグナルと突き合わせます。

結果が空のときの扱いも書かれています。ワークスペース、バックエンド、時間範囲、シグナル、フィールド名、値の綴り、エンティティ名の揺れを順に確かめ、一度に広げるのは1つの軸だけにします。最初に結果が戻った段階が、ずれていた場所の証拠になるという考え方です。

gcql-advancedは「ライブの仕様書」を読ませる

gcql-advanced の要点は、構文を覚え込ませないことです。skill自身が「記憶やコピーした構文リファレンスに頼らない」と書き、サーバーの get_gcql_reference を権威ある情報として扱います。バックエンドによって、使える演算子や引数が変わりうるためです。

組み立ては、1段ずつ足す進め方です。

  1. 最も狭い条件と区切った時間範囲から始める
  2. パイプを足す前に、基本のフィルターだけを流して母集団を確かめる
  3. 集計・別名・数式・並べ替え・件数制限を、1段ずつ追加して中間結果を見る
  4. 複数の集計には明示的な別名を付ける
  5. グループ化の結果は、上限を上げる前にカーディナリティ(種類数)を見る

結合・サブクエリ・count_all_result は、選んだシグナルとツールで正確な形がリファレンスにあるときだけ使います。クエリが失敗したら、サーバーのエラーメッセージを残したまま直前に動いた段へ戻り、1か所ずつ変えます。空になったら discovery に切り替え、名前を推測しません。

本番障害を調べさせるプロンプトの例

READMEは、動作確認用に次の3つの依頼を挙げています。

  • 「checkoutサービスのエラーについて、直近30分で使えるフィールドと値を調べて」
  • 「5xxのログをサービスとデプロイバージョンでグループ化し、20件超のグループだけに絞るgcQLを組み立てて」
  • 「直近で発火したモニターを、ログとトレースに突き合わせて調べて。システムは変更しないで」

3つめの「システムは変更しないで」は、読み取り専用の設計を会話でも明示する書き方です。実際に障害を調べるときは、症状・時間帯・範囲を最初に固定しておくと、discovery の最初の段が短くなります。例えば次のような形です。

本番のcheckoutサービスで、14:00〜14:30(JST)に5xxが増えた。
/groundcover:discovery で使えるフィールドを確かめてから、
デプロイバージョン別・エンドポイント別の件数を出して。
同じ時間帯のモニターとトレースも突き合わせて。何も変更しない。

/groundcover:discovery と /groundcover:gcql-advanced は、Claudeが自動で選ぶだけでなく、スラッシュコマンドとして直接呼ぶこともできます。

調査の手順をCLAUDE.mdに固定する

毎回同じ前提を打つのが面倒なら、プロジェクトの CLAUDE.md に調査の約束事を書いておく方法があります。次の断片は、プラグインの設計に合わせた一例です。

## 本番障害の調査(groundcover)
- クエリの前に、必ずワークスペースとバックエンドを確認し、選択をこちらに伝える
- 時間範囲は必ず明示し、タイムゾーンはJSTとする
- フィールド名と値は discovery で確かめたものだけを使う
- 結果が空のときは、原因を推測する前に discovery に戻る
- 非同期の調査ツールの結論は、直接のクエリで裏付けてから報告する
- 調査中はシステムを変更しない

5行目は、discovery のskillにある「RCAやログ分析の非同期ツールは要約には役立つが、検証済みの事実として示す前に直接クエリの証拠が要る」という指針をそのまま運用ルールにしたものです。

テレメトリは「信頼できないデータ」として扱われる

ログやトレースには、秘密情報、個人情報、ペイロードの断片、攻撃者が仕込んだ文字列が混じりえます。2つのskillは、返ってきたテレメトリを信頼できないデータとして扱い、抜粋を最小限にし、秘密や個人情報は伏せるよう定めています。

特に重要なのは、返ってきた値を、ユーザーの明示的な承認なしにシェルコマンドやコード実行、変更を伴う操作へ埋め込まない、という点です。ログの1行がそのままコマンドになる事故を避けるための線引きです。結果が部分的な場合も、件数や完全性の項目、上限の警告を確認し、サンプリングや切り詰めがあれば答えの中で明示します。

うまくいかないとき

READMEのトラブルシューティングは4項目です。

症状対処
プラグインの検証が通らない対処Claude Codeを更新し、パッケージのルートで claude plugin validate . --strict を再実行
MCPが切断された対処/mcp でgroundcoverを選び、OAuthをやり直す。トークンやヘッダーを .mcp.json に足さない
データが出ない、範囲が想定と違う対処ワークスペースとバックエンドを列挙し、対象を明示して選び、クエリの前にdiscoveryを実行
ローカルの変更が反映されない対処claude --plugin-dir . で再起動するか、/reload-plugins を実行

サーバーは状態を持たない設計です。ワークスペースとバックエンドの選択を毎回の呼び出しに渡す手順が抜けると、見ている範囲がずれます。

問い合わせ先はpartners@groundcover.comと記載されています。ドキュメント、プライバシーポリシー、利用規約、セキュリティ体制のページへのリンクもREADMEにあります。

同じ観測系のプラグインとの違い

監視まわりのプラグインでも、向き先が違います。Dash0プラグインは、Claude Code自身のセッションをトレースとして外へ送る側です。groundcoverプラグインは逆に、本番システムのテレメトリをClaude Codeへ引き込んで読ませる側にあたります。コードの計装を任せる用途なら、Logfireプラグインのようにアプリ側へ手を入れるタイプもあります。

まとめ

groundcoverプラグインは、接続設定1件とskills2つで、本番障害の調べ方を「名前を確かめてから、1段ずつ狭める」型に揃えます。権限はgroundcoverのOAuthとRBACの範囲に収まり、直接のクエリは何も変更しません。

導入前に確かめる価値があるのは、自分のアカウントのワークスペースとバックエンドの構成です。複数あるなら、CLAUDE.md に選択の手順を書いておくと、調査のたびにスコープがぶれません。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →