cisco-umbrella-mcp

Cisco Umbrella MCP Service: un servidor MCP HTTP sin estado que envuelve la Cisco Umbrella REST API v2 (Umbrella clásico, no el producto más reciente Secure Access/SASE), limitado a los 10 endpoints que MSPbots usa actualmente: informes de actividad DNS/proxy/firewall/AMP-retrospective, equipos en itinerancia (roaming computers), descubrimiento de aplicaciones (app-discovery: aplicaciones/protocolos/categorías de aplicaciones), lista de clientes del proveedor gestionado y el resumen de la consola del proveedor.

Stack tecnológico: Python 3.12 + uv + FastMCP (Starlette/Uvicorn)

Cuándo usaría esto un agente

Cisco Umbrella protege la red de un cliente en la capa DNS/web: bloquea dominios maliciosos, filtra contenido web por categoría y registra la actividad de red. Un agente debería recurrir a este MCP para solicitudes como:

• "¿Se ha consultado o bloqueado recientemente este dominio en la red de este cliente?" → cisco_umbrella_get_activity_dns

• "¿Qué categorías/URLs web se están filtrando o proxyando para este cliente?" → cisco_umbrella_get_activity_proxy

• "¿Hay algún allow/block de firewall en la red de este cliente en el último día?" → cisco_umbrella_get_activity_firewall

• "¿Un archivo que parecía limpio fue marcado después como malware?" → cisco_umbrella_get_activity_amp_retrospective

• "Lista los portátiles en itinerancia de este cliente y su última sincronización/estado" → cisco_umbrella_list_roaming_computers

• "Lista las organizaciones de clientes que gestionamos bajo Cisco Umbrella" / "¿Cuál es nuestro uso de paquetes de Umbrella entre clientes?" → cisco_umbrella_list_customers, cisco_umbrella_get_providers_console

Advertencia: este conjunto de credenciales es una clave de organización raíz de Managed Provider (MSSP), no una credencial por cliente, por lo que las herramientas de actividad/dispositivos por cliente anteriores pueden devolver resultados vacíos en la práctica; consulte Known Gaps a continuación para conocer los detalles verificados.

Related MCP server: cisco-secure-access-mcp

Nota sobre el método de autenticación

La API REST clásica de Cisco Umbrella admite la concesión OAuth2 client_credentials — un intercambio puramente servidor a servidor, sin redirección del navegador del usuario. Un administrador crea un par API Key + Key Secret en el panel de Umbrella (Admin > API Keys), y este servicio intercambia ese par por un token bearer de corta duración (1 hora) en cada llamada (sin refresh token, por lo que no hay caché entre solicitudes — el mismo patrón de "re-login en cada llamada" que 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

Nota sobre la región: la configuración de integración propia de MSPbots para Cisco Umbrella tiene un campo dataCenter (us/eu). Verificado directamente contra la especificación OpenAPI sin procesar incrustada en la propia documentación de desarrolladores de Cisco para los 10 endpoints más el endpoint de auth/token: cada uno de ellos lista exactamente un host, https://api.umbrella.com — no hay un host EU separado para el Umbrella clásico. (El producto más reciente "Secure Access" de Cisco tiene su propio concepto de región, pero es un producto diferente del que este servicio tiene como objetivo.) Por lo tanto, este servicio ignora por completo el valor de dataCenter; no es necesario para ninguno de estos 10 endpoints.

Inicio rápido

# 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

Configuración

Copie .env.example a .env y complete sus valores:

HEADER — Descripción de los parámetros de autorización

En modo gateway, cada solicitud debe incluir las siguientes dos cabeceras HTTP:

Configuración de Claude Desktop

Añada a 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"
      }
    }
  }
}

Modos de transporte

stdio (Claude Desktop / CLI)

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

HTTP — un solo inquilino

$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 / multiinquilino

$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

Herramientas disponibles (10)

from_/to aceptan milisegundos de época, ISO-8601 o un desplazamiento relativo (p. ej. "-1days", "-7days", "now"), según las convenciones de la API de informes de Umbrella. (from_ lleva un guion bajo final porque from es una palabra reservada de Python — se asigna internamente al parámetro de consulta literal from).

Known Gaps

Probado contra dos cuentas reales de Managed Provider (MSSP). De las 10 herramientas, solo 2 están confirmadas como funcionales con datos reales verificados; las otras 8 están bloqueadas o sin verificar (los resultados vacíos no demuestran la corrección — solo significan que no se produjo ningún error).

✅ Confirmadas como funcionales (datos reales, no vacíos y validados de forma cruzada):

• cisco_umbrella_get_providers_console — resumen de suscripción real en ambas cuentas de prueba (customerCount: 77 y customerCount: 47 respectivamente).

• cisco_umbrella_list_customers — devolvió 77 organizaciones de clientes reales (nombres de empresas reales) en la cuenta 1. Falló con 403 Access Forbidden en la cuenta 2 — confirmado al decodificar el token de esa cuenta que realmente carece del ámbito admin.customers:read (20 ámbitos en total frente a 76 en la cuenta 1). No es un error de código; es una diferencia real de permisos por clave.

⚠️ Sin verificar — devolvieron resultados bien formados pero vacíos en ambas cuentas, no se ha demostrado su corrección: cisco_umbrella_get_activity_dns, _proxy, _firewall, _amp_retrospective, cisco_umbrella_list_roaming_computers. Se contrastaron las definiciones de parámetros OpenAPI en vivo para Activity DNS directamente con la documentación propia de Cisco (se extrajo la especificación sin procesar, no un resumen) — from/to/limit están exactamente como se implementaron, sin parámetros faltantes o mal nombrados. La explicación probable es que ambas cuentas de prueba son organizaciones raíz de Managed Provider, que no tienen tráfico DNS/proxy/firewall/AMP ni equipos en itinerancia propios — esos datos residen bajo cada organización de cliente gestionado individualmente. Se buscó en la documentación de Cisco un parámetro/cabecera de ámbito "consultar como esta organización de cliente" para el Umbrella clásico — no se encontró ninguno (existe un concepto de ámbito de token "Multi-Org", pero solo para el producto separado Secure Access/SASE, no para el Umbrella clásico). Existe una familia de API "Providers" distinta (/providers/customers/{customerId}/...) que parece ser la ruta prevista para los datos por cliente, pero está fuera del alcance de los 10 endpoints confirmados para esta compilación. Se necesita una credencial real de organización de cliente individual (no a nivel de proveedor) para confirmar realmente estos 5.

• cisco_umbrella_list_applications, _protocols, _application_categories (App Discovery) — confirmado bloqueado, no es un error de código. Reproducido de forma idéntica en ambas cuentas de prueba y mediante curl directo con los mismos tokens (descartando problemas de construcción de solicitudes): 403 Access Forbidden en la cuenta 1, 500/403 en la cuenta 2. Las listas de alcance de ambos tokens incluían reports.appdiscovery:read, por lo que lo más probable es que se trate de una restricción de paquete/derecho (App Discovery como complemento de pago no incluido en el nivel "Umbrella for MSSPs" de ninguna de las cuentas), no de un problema de permisos o de parámetros.

• cisco_umbrella_get_providers_console devuelve un único objeto de resumen de suscripción, no una lista — confirmado mediante ambas pruebas en vivo. A pesar del nombre en plural en la propia lista de API configurada de MSPbots ("Providers Consoles"), verifique esto contra lo que el colector existente de MSPbots espera (matriz vs objeto único).

• La lista de parámetros opcionales del endpoint de descubrimiento de aplicaciones Applications puede no ser completamente exhaustiva (un par de parámetros cerca del final del esquema de ese endpoint no se capturaron por completo durante la investigación) — los documentados aquí (sources, identity, labels, controllable, categories, subcategory, limit, offset) están confirmados como reales; puede haber uno o dos más aún no añadidos.

• El alcance se limita a las 10 operaciones que MSPbots utiliza actualmente (confirmado por el usuario), no a la superficie completa de la API de Umbrella (que también incluye Redes, Dominios Internos, Sitios, Túneles de Red, Políticas, Etiquetado, la API separada de "Providers" para acciones por cliente, y la API de administración de claves para gestionar las propias claves de API).

Referencia de API

• Autenticación de API de Cisco Umbrella

• Documentación de API de Cisco Cloud Security (DevNet)