cisco-umbrella-mcp

Cisco Umbrella MCP Service — это статeless HTTP MCP-сервер, оборачивающий Cisco Umbrella REST API v2 (классический Umbrella, а не более новый продукт Secure Access/SASE), ограниченный 10 эндпоинтами, которые MSPbots использует в настоящее время: отчёты об активности DNS/proxy/firewall/AMP-retrospective, роуминг-компьютеры, обнаружение приложений (приложения/протоколы/категории приложений), список клиентов управляемого провайдера и сводка консоли провайдера.

Технологический стек: Python 3.12 + uv + FastMCP (Starlette/Uvicorn)

Когда агенту следует использовать этот сервис

Cisco Umbrella защищает сеть клиента на уровне DNS/веба — он блокирует вредоносные домены, фильтрует веб-контент по категориям и регистрирует сетевую активность. Агенту следует обращаться к этому MCP для запросов вроде:

• «Был ли этот домен запрошен или заблокирован в сети этого клиента в последнее время?» → cisco_umbrella_get_activity_dns

• «Какие веб-категории/URL фильтруются или проксируются для этого клиента?» → cisco_umbrella_get_activity_proxy

• «Были ли разрешения/блокировки файрвола для сети этого клиента за последний день?» → 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

Примечание о методе аутентификации

Классический REST API Cisco Umbrella поддерживает грант OAuth2 client_credentials — чисто серверный обмен, без перенаправления через браузер пользователя. Администратор создаёт пару API Key + Key Secret в панели Umbrella (Admin > API Keys), и этот сервис обменивает эту пару на кратковременный (1 час) bearer-токен при каждом вызове (без refresh-токена, поэтому кэширования между запросами нет — тот же паттерн «повторный вход при каждом вызове», что и в 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). Проверено напрямую по исходной спецификации OpenAPI, встроенной в документацию разработчика Cisco, для всех 10 эндпоинтов плюс эндпоинт auth/token: каждый из них указывает ровно один хост, https://api.umbrella.com — отдельного EU-хоста для классического Umbrella не существует. (В более новом продукте 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 каждый запрос должен содержать следующие два HTTP-заголовка:

Настройка 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 принимают эпохальные миллисекунды, ISO-8601 или относительное смещение (например, "-1days", "-7days", "now"), в соответствии с соглашениями отчётного API Umbrella. (from_ имеет завершающее подчёркивание, потому что from — зарезервированное слово Python; внутри он сопоставляется с литеральным параметром запроса from.)

Известные пробелы

Протестировано на двух реальных учётных записях Managed Provider (MSSP). Из 10 инструментов только 2 подтверждённо работают с проверенными реальными данными; остальные 8 либо заблокированы, либо не проверены (пустые результаты не доказывают корректность — они просто означают, что ошибка не возникла).

✅ Подтверждённо работают (реальные, непустые, перекрёстно проверенные данные):

• cisco_umbrella_get_providers_console — реальная сводка подписки на обеих тестовых учётных записях (customerCount: 77 и customerCount: 47 соответственно).

• cisco_umbrella_list_customers — вернул 77 реальных организаций клиентов (реальные названия компаний) на учётной записи 1. На учётной записи 2 завершился ошибкой 403 Access Forbidden — подтверждено декодированием токена этой учётной записи, что ей действительно не хватает области admin.customers:read (всего 20 областей против 76 на учётной записи 1). Это не ошибка кода, а реальное различие в разрешениях между ключами.

⚠️ Не проверены — вернули корректно сформированные, но пустые результаты на обеих учётных записях, корректность не доказана: cisco_umbrella_get_activity_dns, _proxy, _firewall, _amp_retrospective, cisco_umbrella_list_roaming_computers. Определения параметров OpenAPI для Activity DNS были перекрёстно сверены напрямую с документацией Cisco (извлечена исходная спецификация, а не сводка) — from/to/limit реализованы точно так, как описано, отсутствующих или неправильно названных параметров нет. Вероятное объяснение: обе тестовые учётные записи — это корневые организации Managed Provider, у которых нет собственного прямого DNS/proxy/firewall/AMP-трафика или роуминг-компьютеров — эти данные находятся в каждой отдельной организации управляемого клиента. В документации Cisco был выполнен поиск параметра/заголовка ограничения области «запрос от имени организации этого клиента» для классического Umbrella — ничего не найдено (концепция ограничения области токена «Multi-Org» существует, но только для отдельного продукта Secure Access/SASE, а не для классического Umbrella). Существует отдельное семейство API «Providers» (/providers/customers/{customerId}/...), которое выглядит как возможный предполагаемый путь к данным конкретного клиента, но оно выходит за рамки подтверждённых для этой сборки 10 эндпоинтов. Для фактического подтверждения этих 5 инструментов требуются реальные учётные данные организации отдельного клиента (не уровня провайдера).

• cisco_umbrella_list_applications, _protocols, _application_categories (App Discovery) — подтверждено, что заблокировано, это не ошибка кода. Воспроизводится идентично на обоих тестовых аккаунтах и при прямом вызове через curl с теми же токенами (что исключает проблемы с формированием запроса): 403 Access Forbidden на аккаунте 1, 500/403 на аккаунте 2. Списки областей действия обоих токенов включали reports.appdiscovery:read, так что это, скорее всего, ограничение пакета/лицензии (App Discovery как платный дополнительный модуль не входит ни в один из тарифов «Umbrella for MSSPs» обоих аккаунтов), а не проблема прав доступа или параметров.

• cisco_umbrella_get_providers_console возвращает один объект сводки по подписке, а не список — подтверждено обоими живыми тестами. Несмотря на множественное число в собственном сконфигурированном списке API в MSPbots («Providers Consoles»), перепроверьте это на соответствие тому, что ожидает существующий коллектор MSPbots (массив или одиночный объект).

• Список необязательных параметров конечной точки обнаружения приложений Applications может быть не полностью исчерпывающим (пара параметров ближе к концу схемы этой конечной точки не была полностью зафиксирована в ходе исследования) — задокументированные здесь (sources, identity, labels, controllable, categories, subcategory, limit, offset) подтверждены как реальные; возможно, есть ещё один-два, которые пока не добавлены.

• Область действия ограничена 10 операциями, которые MSPbots использует в настоящее время (подтверждено пользователем), а не всей поверхностью API Umbrella (которая также включает Networks, Internal Domains, Sites, Network Tunnels, Policies, Tagging, отдельный API «Providers» для действий по каждому клиенту и Key Admin API для управления самими ключами API).

Справочник по API

• Cisco Umbrella API Authentication

• Cisco Cloud Security API Documentation (DevNet)