cisco-umbrella-mcp

Cisco Umbrella MCP Service — Cisco Umbrella REST API v2（新しい Secure Access/SASE 製品ではなく、クラシック Umbrella）をラップするステートレスな HTTP MCP サーバーで、MSPbots が現在使用している 10 個のエンドポイントに限定されています：DNS/プロキシ/ファイアウォール/AMP レトロスペクティブのアクティビティレポート、ローミングコンピュータ、アプリディスカバリ（アプリケーション/プロトコル/アプリケーションカテゴリ）、マネージドプロバイダーの顧客リスト、プロバイダーコンソールのサマリー。

技術スタック： Python 3.12 + uv + FastMCP (Starlette/Uvicorn)

エージェントがこれをいつ使用するか

Cisco Umbrella は DNS/Web レイヤーで顧客のネットワークを保護します。悪意のあるドメインをブロックし、カテゴリ別に Web コンテンツをフィルタリングし、ネットワークアクティビティをログに記録します。エージェントは次のようなリクエストに対してこの MCP を使用する必要があります：

• "このドメインは最近この顧客のネットワーク上でクエリまたはブロックされましたか？" → cisco_umbrella_get_activity_dns

• "この顧客に対してどの Web カテゴリ/URL がフィルタリングまたはプロキシされていますか？" → cisco_umbrella_get_activity_proxy

• "この顧客のネットワークで過去 1 日間にファイアウォールの許可/ブロックはありましたか？" → cisco_umbrella_get_activity_firewall

• "クリーンに見えたファイルが後でマルウェアとしてフラグ付けされましたか？" → cisco_umbrella_get_activity_amp_retrospective

• "この顧客のローミングラップトップとその最終同期/ステータスを一覧表示" → cisco_umbrella_list_roaming_computers

• "Cisco Umbrella で管理している顧客組織を一覧表示" / "顧客全体での Umbrella パッケージ使用量は？" → cisco_umbrella_list_customers、cisco_umbrella_get_providers_console

注意： この認証情報セットは Managed Provider (MSSP) のルート組織キーであり、顧客ごとの認証情報ではないため、上記の顧客ごとのアクティビティ/デバイスツールは実際には空で返される可能性があります。検証済みの詳細については、下記の既知のギャップを参照してください。

Related MCP server: cisco-secure-access-mcp

認証方法に関する注意

Cisco Umbrella のクラシック REST API は OAuth2 client_credentials グラント をサポートしています。これは純粋なサーバー間の交換であり、ユーザーのブラウザリダイレクトはありません。管理者は Umbrella ダッシュボード（Admin > API Keys）で API Key + Key Secret のペアを作成し、このサービスはそのペアを毎回の呼び出しで短命（1 時間）のベアラートークンと交換します（リフレッシュトークンがないため、リクエスト間のキャッシュはありません。covedataprotection-mcp/webroot-mcp/logmein-mcp と同じ「呼び出しごとに再ログイン」パターンです）。

POST https://api.umbrella.com/auth/v2/token
Authorization: Basic base64(apiKey:keySecret)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

リージョンに関する注意： MSPbots の Cisco Umbrella 統合設定には dataCenter フィールド（us/eu）があります。Cisco 自身の開発者ドキュメントに埋め込まれている生の OpenAPI 仕様を、10 個すべてのエンドポイントと認証/トークンエンドポイントについて直接検証しました：それらのすべてが正確に 1 つのホスト https://api.umbrella.com をリストしています — クラシック Umbrella には別の EU ホストはありません。（Cisco の新しい「Secure Access」製品には独自のリージョン概念がありますが、これはこのサービスが対象とする製品とは異なります。）したがって、このサービスは dataCenter 値を完全に無視します。これらの 10 個のエンドポイントのいずれにも必要ありません。

クイックスタート

# Install dependencies
cd D:\claude\project\cisco-umbrella-mcp
uv sync

# Run in stdio mode (for Claude Desktop)
$env:UMBRELLA_API_KEY="your_api_key"
$env:UMBRELLA_KEY_SECRET="your_key_secret"
uv run cisco-umbrella-mcp

設定

.env.example を .env にコピーして、値を入力してください：

HEADER 認証パラメータの説明

Gateway モードでは、各リクエストに以下の 2 つの HTTP Header を含める必要があります：

Claude Desktop のセットアップ

claude_desktop_config.json に追加：

{
  "mcpServers": {
    "cisco-umbrella": {
      "command": "uv",
      "args": ["run", "--directory", "D:/claude/project/cisco-umbrella-mcp", "cisco-umbrella-mcp"],
      "env": {
        "UMBRELLA_API_KEY": "your_api_key",
        "UMBRELLA_KEY_SECRET": "your_key_secret"
      }
    }
  }
}

トランスポートモード

stdio（Claude Desktop / CLI）

$env:UMBRELLA_API_KEY="your_api_key"
$env:UMBRELLA_KEY_SECRET="your_key_secret"
uv run cisco-umbrella-mcp

HTTP — シングルテナント

$env:UMBRELLA_API_KEY="your_api_key"
$env:UMBRELLA_KEY_SECRET="your_key_secret"
$env:MCP_TRANSPORT="http"
$env:AUTH_MODE="env"
uv run cisco-umbrella-mcp

HTTP — gateway / マルチテナント

$env:MCP_TRANSPORT="http"
$env:AUTH_MODE="gateway"
uv run cisco-umbrella-mcp
# Each request must include: X-Umbrella-Api-Key and X-Umbrella-Key-Secret headers

利用可能なツール（10）

from_/to は、Umbrella のレポート API の慣例に従い、エポックミリ秒、ISO-8601、または相対オフセット（例："-1days"、"-7days"、"now"）を受け入れます。（from_ に末尾のアンダースコアが付いているのは、from が Python の予約語であるためです。内部的にはリテラルの from クエリパラメータにマッピングされます。）

既知のギャップ

2 つの実在する Managed Provider (MSSP) アカウントでテストしました。10 個のツールのうち、検証済みの実データで動作が確認されているのは 2 つだけです。残りの 8 つはブロックされているか、未検証です（空の結果は正しさを証明するものではなく、エラーが発生しなかったことを意味するだけです）。

✅ 動作確認済み（実在する、空でない、相互検証済みのデータ）：

• cisco_umbrella_get_providers_console — 両方のテストアカウントで実際のサブスクリプションサマリー（それぞれ customerCount: 77 と customerCount: 47）。

• cisco_umbrella_list_customers — アカウント 1 で 77 の実在する顧客組織（実際の会社名）を返しました。アカウント 2 では 403 Access Forbidden で失敗しました。そのアカウントのトークンをデコードして、admin.customers:read スコープが実際に欠如していることを確認しました（合計 20 スコープ vs アカウント 1 の 76 スコープ）。コードのバグではなく、キーごとの実際の権限の違いです。

⚠️ 未検証 — 両方のアカウントで整形式だが空の結果を返し、正しさは証明されていません： cisco_umbrella_get_activity_dns、_proxy、_firewall、_amp_retrospective、cisco_umbrella_list_roaming_computers。Activity DNS のライブ OpenAPI パラメータ定義を Cisco 自身のドキュメントと直接照合しました（要約ではなく生の仕様を取得）— from/to/limit は実装どおり正確で、欠落または誤った名前のパラメータはありません。考えられる説明は、両方のテストアカウントが Managed Provider のルート組織であり、独自の DNS/プロキシ/ファイアウォール/AMP トラフィックやローミングコンピュータを持たないことです。そのデータは各 管理対象顧客 組織の下に個別に存在します。クラシック Umbrella の「この顧客組織としてクエリ」するスコープパラメータ/ヘッダーを Cisco のドキュメントで検索しましたが、見つかりませんでした（「Multi-Org」トークンスコープの概念は存在しますが、それは別の Secure Access/SASE 製品のみで、クラシック Umbrella にはありません）。顧客ごとのデータへの意図された経路と思われる別の「Providers」API ファミリー（/providers/customers/{customerId}/...）がありますが、これはこのビルドで確認された 10 エンドポイントの範囲外です。これら 5 つを実際に確認するには、実際の単一顧客組織の認証情報（プロバイダーレベルではない）が必要です。

• cisco_umbrella_list_applications、_protocols、_application_categories（App Discovery）— ブロックされていることを確認済み。コードのバグではない。 両方のテストアカウントで、また同じトークンを使用した直接の curl でも同一の結果が再現された（リクエスト構築の問題は除外される）：アカウント 1 では 403 Access Forbidden、アカウント 2 では 500/403。両トークンのスコープリストには reports.appdiscovery:read が含まれていたため、これはおそらくパッケージ/エンタイトルメントの制限（App Discovery は有料アドオンであり、どちらのアカウントの「Umbrella for MSSPs」ティアにも含まれていない）であり、権限やパラメータの問題ではない。

• cisco_umbrella_get_providers_console は、リストではなく単一のサブスクリプション概要オブジェクトを返す — 両方のライブテストで確認済み。MSPbots 自身の設定済み API リストでの複数形の名前（「Providers Consoles」）にもかかわらず、これを MSPbots の既存コレクターが期待するもの（配列 vs 単一オブジェクト）と照合して再確認すること。

• Applications アプリディスカバリーエンドポイントのオプションパラメータリストは完全に網羅的ではない可能性がある（調査中にそのエンドポイントのスキーマの末尾付近のパラメータがいくつか完全には取得されなかった）— ここに記載されているもの（sources、identity、labels、controllable、categories、subcategory、limit、offset）は実在が確認されている。追加されていないパラメータが 1 つか 2 つある可能性がある。

• スコープは MSPbots が現在使用している 10 のオペレーション（ユーザー確認済み）に限定されており、Umbrella の全 API サーフェス（Networks、Internal Domains、Sites、Network Tunnels、Policies、Tagging、顧客ごとのアクション用の別の「Providers」API、API キー自体を管理するための Key Admin API も含む）ではない。

API リファレンス

• Cisco Umbrella API Authentication

• Cisco Cloud Security API Documentation (DevNet)