kubesense-mcp

KubeSense MCP

KubeSense の各クエリスキルが基盤として利用するツールレイヤーです。このスキルは共有コントラクト（フィールド名、WHERE 構文、出力形式）を担うため、シグナルごとのスキルで毎回定義し直す必要はありません。

ルーティング

ユーザーの質問…	参照先
ログ、エラーメッセージ、grep	kubesense-logs
レイテンシ、p99、リクエスト、スパン、障害が発生したホップ	kubesense-traces
CPU、メモリ、ディスク、PromQL	kubesense-metrics
実行中のもの、Pod の再起動、変更内容	kubesense-infra
アラート — 一覧表示、調査、作成	kubesense-alerts

接続

kubeapi が /api グループの外部にマウントされた /mcp で、Streamable HTTP 経由で提供します。REST API と同じ認証情報を使用します。

# API key — recommended for agents, does not expire
claude mcp add --scope user --transport http kubesense \
  https://<your-kubesense-host>/mcp \
  --header "x-api-key: <your-api-key>"

# JWT access token — expires
claude mcp add --scope user --transport http kubesense \
  https://<your-kubesense-host>/mcp \
  --header "Authorization: Bearer <access-token>"

稼働確認: GET /mcp_health。認証済みのユーザーを確認するには、get-current-user を呼び出します。引数は不要で、負荷が軽く、リクエストの認証情報から解決されます。

RBAC は、ツール呼び出しごとに logs、traces、infrastructure（メトリクス + ノード／Pod）、alerts の各モジュールに対して解決されます。権限エラーにはモジュール名が示されます。analyze-telemetry は、サブクエリがアクセスするすべてのモジュールを解決します。

サーバー側で MCP_LOG_LEVEL=debug を設定すると、グローバルなログレベルを上げずに、呼び出しごとの引数ペイロードをログに記録できます。

ツール（38）

検出 — クエリを実行する前に呼び出します

ツール	返される内容
get-trace-or-log-fields	指定ウィンドウ内のログまたはトレースのフィールドカタログ
get-available-metrics	メトリクス名
get-metric-labels	1 つのメトリクスのラベル名

クエリ

ツール	返される内容
search-logs	生ログの行（デフォルトは 10 件）
search-traces	生スパンの行（デフォルトは 10 件）
analyze-logs	集計されたログ系列
analyze-traces	集計されたスパン系列
analyze-metrics	PromQL の結果
analyze-telemetry	1 回の呼び出しで複数のクエリと数式を実行
get-distributed-trace	1 つの trace_id の完全なスパンツリー
execute-sql	ログまたはトレースに対する生の ClickHouse SELECT の結果行
validate-sql	SQL クエリのドライラン判定と、実行される SQL
validate-spl	SPL クエリのドライラン判定と、コンパイル後の SQL
execute-spl	ログに対する SPL パイプラインの結果行

execute-sql / validate-sql は、analyze-* では表現できない結合、CTE の連鎖、ウィンドウ関数、集計値間の算術演算に使う最後の手段です。他のツールと同じカタログラベルに加え、検出では一覧表示されないフィールドもいくつか受け取ります。スコープが制限されたロールでは拒否されます。kubesense-sql を参照してください。

フィルターが SQL を使う理由になることはありません。条件が where 文字列（Advanced クエリ言語）に収まる場合は、search-* / analyze-* を使ってください。サーバーはインデックスを使うようにコンパイルしますが、SQL は型指定どおりに実行されるため、SQL での単純な body LIKE '%…%' はウィンドウ内のすべてのログ行をスキャンします。

execute-spl / validate-spl は、Logs エクスプローラーのパイプ形式の SPL 言語で、ログのみを対象とします。まず検証してください。SPL のパーサーは未知のフィールドと未知の関数を受け入れるため、名前が間違っていてもコンパイルされ、execute-spl でスキャンのコストが発生した後に初めて失敗します。また、SPL はストレージの列名（level、pod_name、cluster）を受け取ります。これは、ここにある他のすべてのツールで必要なカタログラベルとは逆です。さらに、パーサーは未知のフィールドや関数も受け入れるため、クエリを実行する前に不具合を見つけるには検証が唯一の方法です。kubesense-spl を参照してください。

インベントリ — kubesense-infra を参照

list-clusters · list-nodes · get-node-detail · list-pods · get-pod-detail · list-workloads · get-workload-detail · list-issues · get-infra-issues · get-recent-changes

アラート — kubesense-alerts を参照

list-alerts（外部 Alertmanager） · list-active-alerts（ネイティブストア、発報中） · list-alert-rules（ルール定義） · get-alert-details · get-alert-history · list-notification-channels · find-investigation-for-alert

ID

get-current-user — username、name、email、role、auth_type を返します。なお、username と email は頻繁に異なります。list-alert-rules の created_by など、所有者を示すフィールドはユーザー名と照合されます。

検証 — ドキュメントをチェックし、何も保存しません

validate-alert-json · validate-dashboard-json

どちらも document（JSON オブジェクト、または JSON オブジェクトを含む文字列）を受け取り、すべてのスキーマ上の問題を path / rule / message として一度に報告します。path は修正する値への JSON Pointer です。読み取り専用で、何度でも無料で呼び出せます。手作業で作成したものは、作成する前、または引き渡す前に、対応する検証ツールに通してください。

書き込み — 状態を変更します

create-alert · create-dashboard

どちらも書き込みアノテーションが付与され、ユーザーの承認を必要とします。呼び出す前に、作成しようとしている内容を正確に伝えてください。それぞれ上記のツールと同じスキーマで検証し、同じ検出結果で拒否するため、先に検証しておけば拒否ではなく修正につなげられます。

発見を優先するルール

名前を推測してはいけません。 フィールド、メトリクス、クラスター、ラベルのいずれもです。

logs / traces:  get-trace-or-log-fields  →  search-* / analyze-*
metrics:        get-available-metrics     →  get-metric-labels  →  analyze-metrics
clusters:       list-clusters             →  anything with a "clusters" filter

ここで特に重要な理由は2つあります。

1. フィールド名が拒否されると、正しいラベル名を示すエラーが返されます。これは便利ですが、再試行する前にエラーを読む場合に限ります。
2. 間違ったクラスター名やメトリクス名はエラーになりません。空の結果が返され、「値がゼロ」と見分けがつきません。

クエリで使用するものと同じ時間範囲をget-trace-or-log-fieldsに渡してください。属性キーは時間範囲ごとに異なります。

フィールド名の契約

ログ／トレースの入力（where、required_fields、group_by_fields、fields、sort_by）で受け付けられるのはカタログのラベルのみです。ストレージのカラム名は拒否されます。

field "pod_name" is a storage column; use the catalog label "instance" instead
  (call get-trace-or-log-fields to see all labels)

unknown field "service" for signal=logs; call get-trace-or-log-fields to discover
  valid fields (attributes carry an @ prefix)

概念	ログ	トレース
重大度／結果	type（ERROR — 大文字）	status（error — 小文字）
Pod	instance	instance
コンテナ	container	container
ノード	node	node_name
サービス識別子	利用不可 — workloadを使用	service
ワークロード	workload	workload
HTTPメソッド	—	method
HTTPステータス	—	status_code
エンドポイント	—	resource
スパンの役割	—	role
プロトコル	—	protocol
メッセージ本文	body	利用不可
レイテンシ	—	duration

非表示だが使用可能なフィールドや、すべてのストレージマッピングを含むシグナルごとの完全な一覧は、**references/field-catalog.md**にあります。

警告

2つのシグナルでは、node／node_nameと重大度の名前および大文字・小文字が異なり、serviceはトレースにしかありません。一方のシグナルのフィールド名をもう一方に流用するのは、最もよくある失敗です。

列挙値の大文字・小文字は、検出結果の**enum_values列から読み取ってください。example**列から読み取ってはいけません。例の生成では、複数の列挙フィールド（ログのtype、トレースのmethod、protocol、status_code）について、空欄が黙って返されます。

WHEREの構文

type = ERROR AND namespace = production
status = error AND role = server
namespace IN (production, staging)
NOT (env_type = dev)
body ILIKE "%timeout%"
duration > 500
@user.id = abc-123

パーサーが受け付ける演算子： = != < > <= >= LIKE ILIKE SUBSTR_ILIKE IN — AND／OR／NOTおよび括弧と組み合わせて使用します。

警告

検出結果のoperators列は、実際より多くの演算子を表示します。HAS_TOKEN、HAS_ALL、HAS_ANY、LIKE_AND、ILIKE_LOG、IS_IP_ADDRESS、EXISTは凡例に記載されていますが、WHERE文字列で使える構文はありません。body HAS_TOKEN oomは構文解析エラーになります。exist(@field)はどちらのシグナルでも動作しません（サーバーが値を伴うEXISTを出力し、バリデーターが拒否します）。動作する存在確認の方法はありません。

引用符。 引用符なしの値に使用できるのは、英字、数字、_、.、-のみです。スラッシュ、コロン、%、スペースを含む値は、二重引用符で囲む必要があります。

resource = "/api/v1/checkout"           ✓
timestamp > "2026-07-30T10:00:00Z"      ✓
resource = /api/v1/checkout             ✗ parse error

NOT INはリーフ演算子ではありません。 NOT (namespace IN (kube-system, default))のように記述してください。

属性はWHEREでは@を付けますが、ログに限ります。トレースでは、@attrによるフィルターは不明なフィールドとして拒否されます（サーバー側の不具合です。ツールの説明には反対の記載があります）。トレース属性は、{"field": "db.system", "is_attribute": true}を使えば、group_by_fields／fields／required_fields／sort_byでは引き続き使用できます。どちらのシグナルでも、ここでは@は不要です。

durationはミリ秒で入力し、ナノ秒で出力します。詳しくはkubesense-tracesを参照してください。

ツールの選び方

質問	ツール
「最近のエラーを表示して」	search-logs
「過去1時間のエラー数」	analyze-logs、row_count
「checkout の p99 レイテンシ」	analyze-traces、duration の p99
「このリクエストが失敗した理由」	get-distributed-trace
「CPU 使用率」	get-available-metrics → analyze-metrics
「パーセンテージでのエラー率」	数式を使った analyze-telemetry
「何が実行中か／何が壊れているか／何が変わったか」	インベントリツール — 通常なら複数回のクエリが必要な内容を1回の呼び出しで取得

search-* をページ分割するのではなく、analyze-* で集計してください。 件数の計算に生の行を読み込むのは時間がかかり、トークンも大幅に多く消費します。また、クラスターをまたぐページ分割スキャンは時間バケット優先で並べられるため、すべてのデータを取得できる保証もありません。

すべての analyze-* の query_type：range = 時系列（傾向）、instant = シリーズごとの1つの値（合計、現在の状態、上位N件）。

時間範囲は RFC3339 形式です（2026-07-30T10:00:00Z）。まず狭い範囲（15～30分）から始め、必要に応じて広げてください。探索ツールとインベントリツールは、どちらもデフォルトで過去1時間を対象にします。

複数データソースへのクエリと数式

analyze-telemetry は1回の呼び出しで複数のクエリを実行し、それらを組み合わせます。比率、エラー率、パーセンテージを取得する唯一の方法です。

{
  "from_time": "2026-07-30T10:00:00Z",
  "to_time": "2026-07-30T11:00:00Z",
  "query_type": "instant",
  "queries": {
    "A": { "selectedMode": "traces", "value_operation": "row_count" },
    "B": { "selectedMode": "traces", "where": "status = error", "value_operation": "row_count" },
    "C": { "query_type": "formula", "expression": "(B/A)*100" }
  }
}

クエリには1文字のラベルを割り当てます。数式のエントリでは "query_type": "formula" を使い、他のラベルを参照する expression を指定します。シグナルをまたぐ例については、references/multi-query.md を参照してください。

出力の読み方

トークンの節約を考慮して設計された、3種類の形式があります。

TSV（search-*、すべてのインベントリツールとアラート一覧ツール） — # key=value 形式のメタデータ行、続いてヘッダー行、その後にレコードごとの行が並びます。空のセルはフィールドが存在しないことを示します。## name 行は名前付きのサブテーブル（例：## services、## silences）の開始を示します。

列指向 JSON（すべての analyze-*） — results はクエリラベルをキーにします。

• range：共通の timestamps 配列（Unix 秒。出力は1回のみ）を持ち、各シリーズには位置に対応した値のみの values 配列が含まれます。values[i] は timestamps[i] の値で、null はそのバケットにデータがないことを示します。
• instant：timestamps はなく、各シリーズには単一のスカラー値 value が含まれます。
• total_series／truncated は、上位N件の上限を適用する前に存在したゼロ以外のシリーズ数を示します。

サブテーブル付きレコード（get-*-detail） — スカラー値は field<TAB>value の行、ネストされた配列は ## name 形式の TSV ブロック、マップはコンパクトな JSON で表されます。空のフィールドは省略されます。

タイムスタンプは常にミリ秒精度の RFC3339 UTC 形式です。from_time／to_time が受け付ける形式とまったく同じなので、セルの値をカーソルとしてそのままコピーできます。

ページネーション

search-logs／search-traces に page や offset はありません。to_time を狭めてページを進めます。時間範囲は半開区間なので、カーソル行は繰り返されません。

ページ内で最も古いタイムスタンプ（ログでは timestamp、トレースでは start_timestamp）を取得し、その値をそのまま次の to_time に渡します。ミリ秒精度も正確にコピーしてください。

インベントリツールとアラートツールは、page／page_size（デフォルトは50）または limit／offset を使った標準的なページネーションに対応しています。

網羅的な生データのスキャンが信頼できない理由となる並び順の注意点については、シグナルごとのスキルを参照してください。数値を求める場合は、できる限り集計を優先してください。

ルール

1. クエリを実行する前に検出してください。フィールド、メトリクス、クラスターを確認します。推測してはいけません。
2. get-trace-or-log-fields には、クエリに使用するものと同じ時間範囲を渡してください。
3. カタログにあるラベルのみを使用してください。フィールドエラーが発生した場合は、提示されたラベルを読み取り、同じ名前で再試行しないでください。
4. シグナル間でフィールド名を使い回してはいけません（node と node_name、type と status の違いに注意してください。service はトレース専用です）。
5. 列挙値の大文字・小文字は、example ではなく enum_values に従ってください。
6. WHERE で使用できる演算子は = != < > <= >= LIKE ILIKE SUBSTR_ILIKE IN のみです。/、:、%、またはスペースを含む値は引用符で囲んでください。x NOT IN (...) ではなく、NOT (x IN (...)) を使用してください。
7. value_operation は row_count です。count は使用しないでください。
8. 数値には analyze-* を使用し、レコードの読み取りには search-* のみを使用してください。
9. 比率とパーセンテージには、数式とともに analyze-telemetry を使用してください。
10. 結果が空でもゼロとは限りません。値を報告する前に、名前を確認し、時間範囲を広げてください。
11. create-alert は状態を変更します。作成する内容を伝え、まず list-notification-channels を呼び出してください。そうしないと、誰にも通知されません。