Scouter MCP

scouter-mcp

韓国語のドキュメントについては、README.ko.md を参照してください。

Scouter Collector に TCP 経由で直接接続し、XLogs、カウンター、オブジェクトを照会する stdio MCP サーバーです。AI が Scouter のメトリクスをすばやく調査し、根本原因を診断できるようにすることを目的としています。各結果には txid / gxid / objName / endTimeIso が含まれており、これらをキーとして OpenSearch や Datadog などの他のオブザーバビリティツールと相互分析できます。

アーキテクチャ

Java 17 を使用しています。scouter-common を再利用し、scouter.webapp の net/server クラスを scouter.mcp.client パッケージに移植しています。MCP では Java SDK 2.0.0 の stdio トランスポートを使用します。Collector に対するすべての操作は読み取り専用です。

ビルド

./gradlew shadowJar
# output: build/libs/scouter-mcp-<version>-all.jar

.mcpb バンドルはリリース CI でのみ生成されます（この jar をラップします）。ローカルビルドで生成されるのは jar のみです。

登録（Claude Code、Claude Desktop など）

単一の Collector の場合は、ワンクリックでセットアップできる GitHub Release の .mcpb バンドルをインストールするか、.mcp.json.example をコピーして fat jar（リリースからダウンロードするか、ローカルでビルドしたもの）を指定し、認証情報を設定してください。複数の Collector については、複数の Collector を参照してください。

環境変数	説明
SCOUTER_COLLECTOR_HOST	Collector のホスト
SCOUTER_COLLECTOR_PORT	Collector の TCP ポート（デフォルトは 6100）
SCOUTER_USER	ログインユーザー
SCOUTER_PASSWORD	ログインパスワード
SCOUTER_TZ	タイムゾーン（例：Asia/Seoul）
SCOUTER_LOCALE	ユーザー向けメッセージのロケール：en または ko。未設定の場合は JVM のデフォルトから判定されます（JVM の言語が韓国語の場合のみ韓国語、それ以外は英語）
SCOUTER_INCLUDE_BIND_PARAMS	get_xlog_detail の SQL バインドパラメーターを制御するオペレーター用キルスイッチ（デフォルトは true）。false に設定すると、呼び出しごとの引数にかかわらず、サーバー側でバインドパラメーターを除去します。LLM がこれを再有効化することはできません。バインド値に PII が含まれる可能性がある場合に使用してください。

複数の Collector

公式リリースには 1 つの .mcpb バンドル（ワンクリックインストール、単一の Collector 用）と、スタンドアロンの fat jar が含まれています。.mcpb は認証情報セットが 1 つのサーバーを 1 つだけ定義するため、2 つの Collector を同時に登録することはできません。通常、複数の Collector では接続設定全体（ホスト／ポート および ユーザー／パスワード）が異なるため、jar を直接使用し、Collector ごとにエントリーを 1 つ追加してください。

1. GitHub Release から scouter-mcp-<version>-all.jar をダウンロードします。
2. クライアント設定（.mcp.json ／ claude_desktop_config.json）に Collector ごとに mcpServers エントリーを 1 つ追加し、すべて同じ jar を指定したうえで、それぞれに専用の env セットを設定します。これにより、認証情報を個別に分離できます。

{
  "mcpServers": {
    "scouter-prod": {
      "command": "java",
      "args": ["-jar", "/ABSOLUTE/PATH/scouter-mcp-<version>-all.jar"],
      "env": {
        "SCOUTER_COLLECTOR_HOST": "prod-collector", "SCOUTER_COLLECTOR_PORT": "6100",
        "SCOUTER_USER": "prod-user", "SCOUTER_PASSWORD": "***", "SCOUTER_TZ": "Asia/Seoul"
      }
    },
    "scouter-stg": {
      "command": "java",
      "args": ["-jar", "/ABSOLUTE/PATH/scouter-mcp-<version>-all.jar"],
      "env": {
        "SCOUTER_COLLECTOR_HOST": "stg-collector", "SCOUTER_COLLECTOR_PORT": "6100",
        "SCOUTER_USER": "stg-user", "SCOUTER_PASSWORD": "***", "SCOUTER_TZ": "Asia/Seoul"
      }
    }
  }
}

その後、AI が Collector 間の処理をオーケストレーションします。

ツール（14）

名前	目的	主な入力
list_objects	オブジェクト／エージェントの一覧表示	objType?、nameLike?（大文字小文字を区別しない）
search_xlog	XLog の検索（レイテンシ／エラー）	from、to、objNameLike?、objHash?、service?、login?、ip?、desc?、minElapsedMs?、onlyError?、limit?（デフォルトは 20、最大 200）
get_service_summary	サービスごとの集計（件数／平均／最大／p95／エラー率）、上位 50 件	from、to、search_xlog と同じフィルター
get_summary	コレクターの日次事前集計統計（上位 50 件の SQL／サービス／エラーなど。スキャンなし）	category（service/sql/apiCall/ip/userAgent/error/alert）、from、to（最大 31 日）、objType?、objNameLike?、objHash?
get_xlog_detail	XLog の詳細（SQL／バインドパラメーター）	txid、date?／at?、includeBindParams?（デフォルトは true）
get_xlog_by_gxid	分散トランザクションのグループ	gxid、date?／at?
get_counter	カウンターの時系列（同日、完全な解像度）	objNameLike|objHashes|objType、counter、from、to
get_counter_stat	長期間のカウンター統計（5 分解像度、最大 31 日）	objNameLike|objHashes|objType、counter、from、to
list_counters	objType で利用可能なカウンターの一覧表示	objType
list_alerts	過去のコレクターアラート	from、to、level?、object?、key?、limit?
get_active_services	現在実行中のサービス	objNameLike|objType|objHash
list_threads	JVM スレッド一覧（状態ヒストグラム＋CPU 使用率上位 50 件）	objNameLike|objHash（稼働中インスタンスは最大 5 件）
get_thread_detail	ACTIVE トランザクションの実行中スレッド（スタック／ロック所有者／現在の SQL）	txid（必須、アクティブなもの）、id?、objNameLike|objHash
get_object_env	エージェント JVM のシステムプロパティ（シークレットはマスク）	objNameLike|objHash、keyLike?

あいまいな対象指定（objNameLike）

ユーザーはアプリ名の一部（「shop-order-api」など）を指定しますが、実際の objName には k8s ポッド名が含まれています （/shop-order-api-deployment-5f4b8c7d9-abcde/shop-order-api1）。そのため、objHash はデプロイのたびに変わり、 1 つのアプリが複数のインスタンスにまたがります。これを解決するのが objNameLike です。大文字小文字を区別しない部分文字列で 一致するすべてのインスタンス（稼働中のものを優先し、最大 20 件）を特定し、それらを横断してクエリを実行します。 objHash は一切不要です。XLog の検索／サマリーでは、特定対象の解決時にコレクターの日次オブジェクト DB も結合するため、 クエリ対象の期間中にデプロイで置き換えられたポッドも見つかります。一致するものがない場合、エラーは NOT_FOUND となり、 実際の objName を一覧にした candidates ヒントが返されるため、呼び出し側は 1 ステップで指定を修正できます。

大まかなサービスクエリ

Scouter のサービス名は /api/order/.../search-order-info-grade<POST> のような形式ですが、ユーザーは「GET orderDetail」や 「order info grade」と入力します。service フィルターはこのような入力を正規化します。HTTP メソッドはどの位置からでも 抽出され（GET x、x POST、貼り付けた <POST> など）、空白区切りの複数語はサーバー側で最長のトークンにフォールバックし、 明示的な * パターンは変更せずにそのまま渡されます。サーバー側の照合では引き続き大文字小文字が区別されます。そのため、 パターンに一致するものがない場合は、同じ期間を service フィルターなしで（範囲を制限して）再スキャンし、クエリのトークンに 大文字小文字を区別せず一致する実際のサービス名を、トラフィックの多い順に serviceCandidates として返します。名前を正確に指定して 1 回再試行すれば解決します。

service／login／ip／desc はデフォルトで部分一致を使用します（サーバー側の StrMatch）。そのため、 search-order-info-grade のような短いトークンでも /api/order/ext/order-info/search-order-info-grade<POST> に一致します。 objNameLike／login／ip／desc はサーバー側フィルターとして扱われるため、フィルターなしの場合の 5 分間のウィンドウ上限が緩和されます。 list_counters も objNameLike を受け付け、objType を特定するため、ユーザーが Scouter の型分類を把握する必要はありません。

すべてのツールには readOnlyHint が設定されています。diagnose_root_cause MCP プロンプトでは、レイテンシ／エラーの調査に推奨される ツールの順序を提示します。

リソース／トークン安全ポリシー

本番環境の Scouter では、5 分間に数十万件の XLog が生成されることがあるため、search_xlog ではガードレールを適用しています（scouter.mcp.policy.Limits を参照してください）。

• ストリーミング中に limit またはスキャン上限（調査したパック 5,000 件）に達すると処理を停止して ソケットを閉じます。これにより Collector のスキャン／転送も停止し、サーバー負荷、ネットワーク、MCP ヒープを まとめて制限できます。
• service または objHash のフィルターがない場合、許可される期間は最大 5 分です。期間の絶対上限は 24 時間です。
• limit のデフォルト値は 20 で、上限は 200 です。結果には truncated／scanCapReached と hint が含まれるため、再取得ではなくフィルターを絞り込めます。
• get_service_summary は行を保持せず（サービスごとのカウンターのみを保持するため）、より広い期間を低コストで カバーできるよう、スキャン上限を高く（200,000）設定しています。こちらも scanCapReached／examined を 報告します。
• get_counter は objType ごとのファンアウトをインスタンス 20 件までに制限し、長い時系列データはスパイクや 落ち込みを保持する最小値／最大値方式でダウンサンプリングします（概要の min／max／avg は全時系列から 計算されます）。
• 深夜をまたぐ期間は暦日ごとに分割されます（Collector は XLog／カウンター／アラートを日ごとに分割するため）、 境界のどちら側のデータも失われません。
• 応答テキストの上限：SQL テキストは 1,500 文字、エラーメッセージは 500 文字、スレッドのスタックトレースは 4,000 文字、環境変数の値は 500 文字で切り詰められます。それぞれに元の長さを示す切り詰めマーカーが付きます。 get_xlog_detail のプロファイルステップは 150 件までで、totalSteps／stepsTruncated で示されます。
• 1 回のリクエストで Collector への往復は最大 40 回までです（インスタンス数 x 日ごとの区間数）。クライアント側の フィルター（minElapsedMs／onlyError）によってスキャンした行の 99% を超える件数が除外される場合、 選択性が低いことを示すヒントにより、モデルをサーバー側のフィルターまたは get_summary の利用へ誘導します。
• get_summary／get_counter_stat は Collector の日次事前集計データを読み取ります（スキャンなし）。上限は 31 日で、概要では各カテゴリの上位 50 行を返します。list_threads は稼働中のインスタンスを 5 件まで、 各インスタンスのスレッド行を 50 件までに制限します（状態のヒストグラムは常に全スレッドを対象にします）。
• リクエストごとのテレメトリー（passes／examined／kept／tookMs）は、負荷の事後分析用に、構造化された key=value 形式の行として stderr に記録されます。

国際化

動的なユーザー向け出力（ツールのエラーメッセージ、結果のヒント、注記）のみが、英語と韓国語にローカライズされます。 ローカライズには messages.properties／messages_ko.properties を使用します。静的なスキーマ／ツールの説明と、 構造化された stderr ログ（key=value）は、契約とログ解析の安定性を保つため英語のままです。

セキュリティに関する注意

• Collector に対する読み取り専用の操作です（書き込みコマンドは公開されていません）。
• 認証情報は環境変数のみを通じて渡されます（ファイルや引数に平文で含めることはありません）。 最小権限の読み取り専用 Scouter アカウントを推奨します。
• 通信は暗号化されていない TCP です（Scouter プロトコルは TLS に対応していません）。SHA-256 パスワードダイジェスト、 セッショントークン、すべての XLog／カウンターデータが暗号化されずにネットワークを通過します。信頼できるネットワーク内でのみ実行するか、 SSH／VPN 経由でトンネルしてください。Collector のポートをパブリックインターネットに公開しないでください。
• get_xlog_detail のバインドパラメーターには PII が含まれる可能性があります。SCOUTER_INCLUDE_BIND_PARAMS=false を設定すると、 サーバー側で除去できます（LLM が再度有効にすることはできません）。上記の環境変数テーブルを参照してください。 get_thread_detail のライブバインド値（SQLActiveBindVar）にも、同じ無効化スイッチが適用されます。
• get_object_env は、キー名に password／secret／token／credential／private のいずれかが含まれる値を 必ずマスキングします。これはサーバー側のポリシーであり、LLM が解除することはできません。
• stdout は JSON-RPC 専用のため、すべてのログは stderr のみに出力されます。

ライセンス／通知

scouter.mcp.client パッケージは、Scouter v2.20.0 のクライアントコードを移植したものです（Apache License 2.0）。 詳細は NOTICE を参照してください。

既知の制限事項

1. search_xlog／get_service_summary の minElapsedMs／onlyError／limit は、Collector にこれらのネイティブパラメーターがないため、 クライアント側で適用されます。truncated=true はヒューリスティック（返却件数 == limit）であり、誤検知の可能性があります。
2. セッションの有効期限切れ（INVALID_SESSION）が発生すると、クライアントは再ログインしてリクエストを一度再試行します。2 回目も 失敗した場合は SCOUTER_AUTH_FAILED が返されます（無限に再試行することはありません）。上流の 2 秒間隔の時間差 更新デーモンはまだ移植されていないため、長時間実行されるプロセスでは、リアルタイムの相対クエリにわずかなずれが生じることがあります。 絶対エポック（履歴）クエリには影響しません。
3. list_alerts／get_active_services は上流プロトコルから移植され、スモークテスト（SmokeIT）を通じて Collector に対して検証されています。フィールドの対応範囲は Collector のバージョンによって異なる場合があります。