コンテンツにスキップ
Yagra

MCP サーバー

Yagra はオプトインで MCP のツール群を公開でき、 AI クライアント — Claude Code、Claude Desktop、その他 MCP 対応のアシスタント — から稼働中の 監視状態を自然言語で問い合わせられます。例: 「落ちているノードは？」、「アクティブなアラートを 要約して」、「edge-router-1 の直近 1 時間の CPU を見せて」、「アノマリー検知を実行して 異常を教えて」。

概要

Section titled “概要”

サーバーが公開するのは 34 個のツール（読み取り 31 個、書き込み 3 個）です。読み取りツールが 見るのは WebUI と同じデータで、トラブルシュートの 3 種は WebUI が 実行するのと同じオンデマンド分析を実行します — いずれも保存済みの履歴を読んで分析結果を返すだけ です。3 つの書き込みツールが作用するのは監視システムであって、ネットワークそのものでは ありません。ネットワーク機器を設定・変更するツールは、設計上存在しません。

指針となる規約は読み取り同等です。WebUI で見られるものは MCP クライアントからも見られます。 新しい読み取りエンドポイントは、対応するツールと一緒に出荷されるか、ツールを持たない理由を書いた うえで出荷されます。この規約は書き込みには適用しません — 書き込みができるのは下の 3 つで固定です。

ツール 何をするか 必要な最小ロール
get_fleet_summary フリートの健全性サマリ: 状態ごとのノード数、アクティブアラート数 Viewer
list_nodes ロールアップした状態付きのノード一覧（検索可能） Viewer
get_node_status 1 ノードの完全なステータス: サマリ、アクティブアラート、インターフェース Viewer
list_node_groups フォルダツリー（地図座標付き。フォルダごとの健全性集計も任意で取得可能） Viewer
get_active_alerts アクティブアラート（新しい順。ノードと重大度で絞り込み可能） Viewer
get_alert_history 直近のアラート発報とクリア（ページング付き） Viewer
alert_trends アラートの時間的傾向: 常習犯ノード、直近の状態遷移、曜日×時刻のヒートマップ Viewer
list_suppressions メンテナンスウィンドウとミュート — 今アラートを黙らせているもの Viewer
query_metrics ノードのメトリクス時系列 — 最新値、範囲、またはレート Viewer
get_interface_series 1 インターフェースのトラフィックとエラーの履歴（共通の時間軸に整列） Viewer
top_metrics 任意のメトリクスでフリート横断にノードをランキング Viewer
top_interfaces スループット・エラー・破棄・変化量でフリート横断にインターフェースをランキング Viewer
fleet_throughput 指定期間のフリート全体のトラフィック集計 Viewer
get_neighbors ノードが何と接続されているか（CDP/LLDP）。現在の状態と変更履歴 Viewer
get_topology kind= で、根本原因の帰属付きの依存関係グラフ、導出した接続グラフ links、それに対するオペレーターの判断 overrides、比較結果 shadow Viewer
list_discovered_endpoints ルータの ARP キャッシュから得た、ネットワーク上に居るが監視していないホスト Viewer
top_flows 1 ノードまたはフリート横断のトップフロー: トーカー、会話、ポート、プロトコル、AS Viewer
flow_fanout 送信元ごとのファンアウト — 異なる宛先とポートの数（スキャン／ワームの兆候） Viewer
search_events パッシブイベントの検索: syslog、トラップ、Webhook Viewer
event_stats パッシブイベントの切り分け用統計: 最も騒がしいノード、重大度の内訳、一致しなかったシグネチャ Viewer
run_analysis オンデマンドのトラブルシュート分析を実行し、分析結果を待ちます Operator
get_analysis_findings 分析ジョブとその分析結果を id で取得します Viewer
list_analyses 直近の分析ジョブ、または定期実行スケジュールの一覧 Viewer
search_analysis_findings 全実行にまたがるトラブルシュート分析結果の検索（ノード・フォルダ・重大度・期間） Viewer
get_system_health section= で Yagra 自身の状態: ポーラー一覧、ポーリングループの計数、どのポーラーがどのノードを持つか、直近のコア⇄ポーラー断、ストア別の到達性、ホストリソース、転送の配送状況、保管中の認証情報が今も復号できるか、稼働バージョン、有効な任意ティア Viewer¹
get_report_runs 直近のレポート実行とその結果 Viewer
get_audit 誰が何を変更・確認したか View-audit
get_config kind= で Yagra 自身の設定を 28 種類の読み取りとして: しきい値、イベントルールとイベントソース、通知チャネルとルーティングルール、プロファイルと収集テンプレート、ノードの収集メトリクス、分類ルール、MIB カタログ、ノードの URL/DNS チェック、ディスカバリ候補とスキャン、Meraki の組織/ネットワーク/ポーリング、転送先、レポート定義とスケジュール、そして保持 / 隣接探索 / LLM / ロール / OIDC / LDAP の各設定 種別による²
fleet_state_history 一定期間におけるフリートの状態構成の推移 Viewer
get_dns_chain DNS 監視の解決チェーン Viewer
run_rca LLM による 1 インシデントの解説 — WebUI の「このインシデントを説明」と同じもの Operator
ack_alert 書き込み。 アクティブアラートを確認（ACK）する、またはその確認を取り消す Operator
open_maintenance 書き込み。 1 ノードのメンテナンスウィンドウを開始する Operator
poll_now 書き込み。 1 ノードをスケジュール外で即時ポーリングする Admin

すべての書き込み — および起動されたすべての分析 — は、それを行ったトークンに紐づけて監査ログに 記録されます。

¹ get_system_health はセクションごとに必要な権限が異なり、WebUI と完全に一致します: 大半は view、転送状況は manage-config、認証情報の健全性は manage-credentials です。読み取り専用は 「誰でも読める」という意味ではありません。 レポート実行と状態推移は、REST エンドポイントと同様、 グループスコープ付きトークンに対してフリート全体を見せるのではなく拒否します。

² get_config も kind ごとに同じ仕組みです — それぞれ対応する REST エンドポイントと同じ権限を要求するので、同じツールから Viewer にはロール行列が返り、しきい値のルールセットは拒否されます: OIDC と LDAP は manage-users、14 種類は manage-config、残りは view です。保管中のシークレットは返しません — ノードの URL チェックは認証情報が紐づいているか（has_credential）だけを報告し、どれかは返しません。

サーバーの有効化

Section titled “サーバーの有効化”

既定は無効です。コアに YAGRA_ENABLE_MCP=true を設定して（docker-compose.yml のコメントを 外すか、deploy 用 compose なら .env に追記）再起動します。するとエンドポイントは API ポート 上の次の場所で提供されます。

https://<yagra-host>/mcp              # WebUI の TLS エッジ経由（推奨）
http://<yagra-host>:8080/mcp          # core の API ポート直（平文）

どちらも使え、いずれも Streamable HTTP トランスポートです。前者を推奨します — WebUI コンテナが /mcp をコアへプロキシするので、通信が暗号化されます。まだブートストラップの自己署名証明書の ままの環境では、それを信頼させられないクライアントはコアの平文ポートに退避するしかありません。 設定 ▸ TLS 証明書で正式な証明書を取り込むことが、TLS の URL をどこからでも使えるようにする条件です。 無効時はパスがマウントされず（404）、以前とバイト単位で同一です。公開ダッシュボードのオプションが 有効であっても、MCP は常に認証を必須とします。

ゲートとなるのは認証なので、サーバーは既定でどの Host ヘッダーも受理します。クライアントが使える ホスト名をさらに固定したい場合は、YAGRA_MCP_ALLOWED_HOSTS にカンマ区切りのリストを設定します。

サーバー自身の活動はコアの Prometheus メトリクスに現れます。ツール呼び出しはツール別・結果別に 数えられ、認証失敗は別に数えられます — アシスタントがエンドポイントを叩きすぎている、失効済みの トークンがまだ試されている、といったことが Yagra の他のすべてと同じやり方で見えます。

トークンの発行

Section titled “トークンの発行”

WebUI に管理者でサインインし → 設定 ▸ API トークン ▸ API トークンを作成 → ロールを選び → 一度だけ 表示される yat_… の値をコピーします。これが AI クライアントが送る Bearer トークンです。

  • Viewer（閲覧者） — 読み取り専用のアシスタント向け: run_analysis を除くすべての読み取り ツールが使えます。トラブルシュート分析の実行は Operator の操作（アラートの確認と同じ権限） なので、Viewer トークンは過去のジョブと分析結果を閲覧できますが、新しく起動することはできません。
  • Operator（オペレーター） — 上記すべてに加えて、分析の起動、アラートの確認（ack_alert）、 メンテナンスウィンドウの開始（open_maintenance）ができます。
  • Admin（管理者） — すべて。poll_now も含みます。これは、Yagra が何をいつポーリングするかを 変える他の操作と同じ権限を必要とします。

トークンはノードグループに限定することもでき、すべてのツールがそれを尊重します。一覧や検索は 絞り込まれた結果が返り、ランキングや履歴もフィルタされ、範囲外のノードについて尋ねたツールは 「存在しない ID」とまったく同じ応答を返します。1 つだけ、絞り込むのではなく省略する値が あります — event_stats の「一致しなかったシグネチャ」のランキングはノードをまたいで集計されており、絞り込むための 帰属情報が残っていないため、スコープ付きトークンには空の結果と理由を示す注記が返ります。ロール・ 権限・スコープはユーザーと SSOで説明しています。

REST API の通常のログインセッショントークンでも動きますが、こちらは期限切れに なります。API トークンは無人のクライアント向けで、同じ画面から失効できます。

クライアントへの登録

Section titled “クライアントへの登録”

Claude Code（CLI / VS Code 拡張） — すべてのプロジェクト・ディレクトリで使えるよう --scope user を付けます。

Terminal window
claude mcp add --scope user --transport http yagra http://<yagra-host>:8080/mcp \
  --header "Authorization: Bearer yat_your_token"

--scope user を付けないと claude mcp add は local スコープに入り、CLI では見えても VS Code 拡張は local スコープのサーバーを読み込みません（拡張が読むのは user スコープと プロジェクトの .mcp.json だけです）。そのため拡張の /mcp には出てきません。また MCP サーバーは セッション開始時に読み込まれるので、追加後はウィンドウをリロード／新しいセッションを開始して ください。その後 /mcp に yagra が connected として並ぶはずです。ノード一覧やアラートの要約を 頼んでみてください。

Claude Desktop — Desktop は mcp-remote ヘルパー経由でリモートの HTTP サーバーへ橋渡しします。 claude_desktop_config.json（Settings ▸ Developer ▸ Edit config）に以下を追加し、Desktop を 再起動してください。

{
  "mcpServers": {
    "yagra": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "http://<yagra-host>:8080/mcp",
        "--header", "Authorization: Bearer yat_your_token"
      ]
    }
  }
}

Gemini CLI — ~/.gemini/settings.json（またはプロジェクトローカルの .gemini/settings.json）にサーバーを追加します。httpUrl キーで Streamable HTTP トランスポートが 選択されます。

{
  "mcpServers": {
    "yagra": {
      "httpUrl": "http://<yagra-host>:8080/mcp",
      "headers": { "Authorization": "Bearer yat_your_token" }
    }
  }
}

gemini を再起動すると、/mcp に Yagra のツールが一覧されます。VS Code の Gemini Code Assist も 同じ settings.json を読みます。

claude.ai（Web）/ Team / Enterprise — Yagra をカスタムコネクタ （Settings ▸ Connectors）として追加します。これは /mcp が Anthropic のサーバーから到達できる こと、すなわち公開 HTTPS URL（たとえばリバースプロキシや Cloudflare Tunnel でフロントする）を 前提とします — LAN/VPN のみのアドレスではここでは繋がりません。Gemini の Web アプリ / Vertex AI エージェントのコネクタにも、同じ公開 HTTPS の要件が当てはまります。

任意の MCP クライアント / curl での簡易確認 — トランスポートは HTTP 上の素の JSON-RPC なので、 クライアントなしでスモークテストできます。

Terminal window
curl -sN http://<yagra-host>:8080/mcp \
  -H "Authorization: Bearer yat_your_token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

到達性

Section titled “到達性”

AI クライアントは HTTP 呼び出しを、モデルプロバイダのクラウドではなくあなたのマシンから 行います — デスクトップや CLI のアシスタントに必要なのは、同じ LAN または VPN 経由で <yagra-host>:8080 へネットワーク到達できることだけです。ホスト型のコネクタ（claude.ai の Web アプリ、あるいは Gemini の Web アプリ / Vertex AI エージェント）を使いたい場合を除き、インター ネットへのインバウンド公開は不要です。ホスト型コネクタは上記のとおり公開 HTTPS で /mcp に 到達できる必要があります。

プライバシーとセキュリティの注意点

Section titled “プライバシーとセキュリティの注意点”
  • ツールの結果は会話のコンテキストになります。 AI は稼働中の監視データ — ノード名、アドレス、 アラート — を読み、クラウドホスト型のアシスタントではそのデータが接続先のモデルプロバイダへ 送られます。ツールの出力は、自分の境界を出ていくデータとして扱ってください。
  • デバイスの認証情報はどのツール結果にも決して含まれません。 SNMP コミュニティ、SNMPv3 の 認証情報、ポーリング先の API キーは保存時に暗号化されたままで、あらゆるレスポンスの形から 除外されています。
  • トークンは最小権限に保ってください。 質問に答えるだけのアシスタントには Viewer トークンが 適切な既定です。アラート・メンテナンス・分析に対して操作させたいときにだけ Operator を 付与してください。
  • 不要になったら失効させてください。 クライアントがもう必要としなくなったら、 設定 ▸ API トークンからトークンを削除します。ただちに使えなくなります。
  • すべての書き込みは監査されます。 ack_alert、open_maintenance、poll_now はいずれも、 その操作を行ったトークンに紐づけて監査エントリを記録します — WebUI 自身の操作が残すのと同じ 証跡です。