MCP サーバー

Yagra は、MCP のツール群を最初から公開しています。 すると AI のクライアント — Claude Code、Claude Desktop、その他 MCP に対応したアシスタント — から、 今の監視の状態を普通の言葉で尋ねられます。

たとえば「落ちているノードは？」「アクティブなアラートを要約して」「edge-router-1 の直近 1 時間の CPU を見せて」「異常検知を実行して、おかしいところを教えて」といった具合です。

概要

サーバーが公開するのは、41 個のツールです。内訳は読み取りが 38 個、書き込みが 3 個です。

読み取りのツールが見るのは、WebUI と同じデータです。トラブルシュート の 3 種は、WebUI が実行するのと同じオンデマンド分析を実行します。どちらも、保存済みの履歴を読んで 結果を返すだけです。

3 つの書き込みツールが作用するのは、監視のシステムです。ネットワークそのものではありません。 ネットワーク機器を設定したり変更したりするツールは、設計上存在しません。

指針となる決まりは、読み取りの同等性です。WebUI で見られるものは、MCP のクライアントからも 見られます。 新しい読み取りエンドポイントは、対応するツールと一緒に出荷するか、ツールを持たない 理由を書いたうえで出荷します。

この決まりは、書き込みには当てはめません。 書き込みができるのは、下の 3 つで固定です。

ツール	何をするか	必要な最小ロール
get_fleet_summary	フリートの健全性サマリ: 状態ごとのノード数、アクティブアラート数	Viewer
list_nodes	ロールアップした状態付きのノード一覧（検索可能）	Viewer
get_node_status	1 ノードの完全なステータス: サマリ、アクティブアラート、インターフェース、そのノードに SNMP ポーリングが設定されているか	Viewer
list_node_metrics	ノードが実際に持っているメトリクスと、それぞれが届いているか、どう読むか（ゲージかカウンターか、ノードごと・インターフェースごと・表の行ごとのどれか）。query_metrics の前に聞きます	Viewer
list_node_groups	フォルダツリー（地図座標付き。フォルダごとの健全性集計も任意で取得可能）	Viewer
get_prefix_gaps	フォルダの機器が持っているのに IP プレフィックスに無いサブネットと、それぞれが出る理由	Viewer
get_site_prefix_gaps	同じ比較を全サイトについて一度に。サイトごとの状態と抜け。抜けは 2,000 件までで、サイトの間で分ける	Viewer
get_subnet_overlaps	複数の拠点が持っているアドレス範囲。同じ範囲が 2 拠点にあるもの、ある拠点の範囲が別の拠点の範囲に含まれるもの。それぞれに状態と手がかりが付く	Viewer
get_active_alerts	アクティブアラート（新しい順。ノードと重大度で絞り込み可能）	Viewer
get_alert_history	直近のアラート発報とクリア（ページング付き）	Viewer
alert_trends	アラートの時間的傾向: 常習犯ノード、直近の状態遷移、曜日×時刻のヒートマップ	Viewer
list_suppressions	メンテナンスウィンドウとミュート — 今アラートを黙らせているもの	Viewer
query_metrics	ノードのメトリクス時系列 — 最新値、範囲、またはレート³	Viewer
get_interface_series	1 インターフェースのトラフィック・パケットレート・エラー・破棄・光レベルの履歴（共通の時間軸に整列）	Viewer
get_interface_thresholds	1 インターフェースに届くしきい値ルールを 6 つのスコープ段すべてから集め、そのうちどれが効いているか	Operator
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
list_wireless_aps	Yagra が監視している無線コントローラ配下の AP: 状態・接続端末数・どのコントローラが報告しているか（ノードにしたかどうかに関係なく）	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	直近の分析ジョブ（WebUI の一覧と同じく、ツール・状態・開始時刻で絞れる）、または定期実行スケジュールの一覧	Viewer
search_analysis_findings	全実行にまたがるトラブルシュート分析結果の検索（ノード・フォルダ・重大度・期間）	Viewer
get_system_health	section= で Yagra 自身の状態: ポーラー一覧、ポーリングループの計数、どのポーラーがどのノードを持つか、直近のコア⇄ポーラー断、ストア別の到達性、ホストリソース、転送の配送状況、保管中の認証情報が今も復号できるか、稼働バージョン、有効な任意ティア	Viewer¹
get_report_runs	直近のレポート実行とその結果	Viewer
get_audit	誰が何を変更・確認したか	View-audit
get_notification_deliveries	通知の配信ログ。配信ごとに届いたかどうかと、失敗したならどちら側か	Admin
get_config	kind= で Yagra 自身の設定を、領域ごとに 1 つの読み取りとして: しきい値、イベントルールとイベントソース、通知チャネルとルーティングルール、プロファイルと収集テンプレート、ノードの収集メトリクス、分類ルール、MIB カタログ、ノードの URL/DNS チェック、ディスカバリ候補とスキャン、Meraki の組織/ネットワーク/デバイス/ポーリング、NetBox サーバー、転送先、レポート定義とスケジュール、そして保持 / 隣接探索 / 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）だけを報告し、どれかは返しません。

³ query_metrics はノード単位の問い合わせなので、ノード単位の答えがあるときだけ答えます。 インターフェース単位・部品単位に系列が分かれているメトリクスは、ゲージであればノード内の 最大値に畳みます。応答の note にその旨と、その最大値がどちら向きかを書きます。光の受信 レベルのように小さいほうが異常なメトリクスでは、最大値は最悪のポートではなく一番健全な ポートを指すからです。インターフェース単位のカウンタは断り、答えられるツールの名前を返します — 1 本のインターフェースなら get_interface_series、フリート全体なら top_interfaces です。

表の行ごとに系列が分かれているメトリクス（メモリプール、CPU、センサー）は、行ごとに読めます。 latest の応答は、rows に各行のキー・名前・最新値を並べます。そのキーを row に渡すと、どの モードでもその行だけを読めます。行を 1 つ指定すれば系列は 1 本なので、畳みません。行ごとの カウンタは、row で行を指定しない限り断ります。

エンドポイントの場所

既定で有効です。設定は要りません。 逆に外したい場合は、コアに YAGRA_ENABLE_MCP=false を設定して 再起動してください。/mcp は未マウントになり、リクエストは 404 を返します。

エンドポイントは API ポートの上にあります。場所は次の 2 つです。

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

どちらも使えます。いずれも Streamable HTTP のトランスポートです。前者をおすすめします。 WebUI のコンテナが /mcp をコアへ中継するので、通信が暗号化されるからです。

まだ最初の自己署名証明書のままの環境では、それを信頼させられないクライアントは、コアの平文ポートに 逃げるしかありません。設定 ▸ TLS 証明書で正式な証明書を取り込むことが、TLS の URL をどこからでも 使えるようにする条件です。

無効にしているときは、そもそもこのパスが存在しません（404）。以前とバイト単位で同じ状態です。公開 ダッシュボードのオプションを有効にしていても、MCP は常に認証を求めます。

URL が 2 つある＝Host も 2 つ

中継は、クライアントが送ってきた Host をそのまま転送します。ですから YAGRA_MCP_ALLOWED_HOSTS が見る値は、2 つの URL で違います。

これをコアのアドレス（10.0.0.5:8080）に固定した環境は、https://yagra.example.com/mcp に接続する クライアントを拒否します。その名前を一覧に足すまで、通りません。

守りの要は認証です。ですからサーバーは、既定ではどんな Host ヘッダーも受け付けます。クライアント が使えるホスト名をさらに限りたい場合は、YAGRA_MCP_ALLOWED_HOSTS にカンマ区切りの一覧を設定して ください。

サーバー自身の動きは、コアの Prometheus メトリクスに出ます。ツールの呼び出しはツール別・結果別に 数え、認証の失敗は別に数えます。

ですから「アシスタントがエンドポイントを叩きすぎている」「失効済みのトークンがまだ試されている」 といったことが、Yagra の他のすべてと同じやり方で見えます。

トークンの発行

手順は 4 つです。WebUI に管理者でサインインする → 設定 ▸ API トークン ▸ API トークンを作成 → ロールを選ぶ → 1 回だけ表示される 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 トークンは人が操作しないクライアント向けで、同じ画面から失効させられます。

クライアントへの登録

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

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 拡張には出てきません。拡張が読むのは、user スコープとプロジェクトの .mcp.json だけだからです。

また 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 なので、 クライアントなしでスモークテストできます。

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"}'

到達性

AI のクライアントは、HTTP の呼び出しをあなたのマシンから行います。モデルプロバイダのクラウド からではありません。

ですからデスクトップや CLI のアシスタントに必要なのは、同じ LAN か VPN を通じて <yagra-host>:8080 に届くことだけです。インターネットへ内向きに公開する必要はありません。

例外は、ホスト型のコネクタを使う場合です（claude.ai の Web アプリ、Gemini の Web アプリ、Vertex AI のエージェント）。これらは上に書いたとおり、公開された HTTPS で /mcp に届く必要があります。

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

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