Cisco Umbrella MCP Server

MCP server for Cisco Umbrella's NextGen REST API - deployment inventory, admin, policy, reporting, and investigate visibility - for AI assistants and the WYRE Conduit gateway.

Authentication

Create an API Key in the Umbrella admin console (Admin > API Keys, or Console Settings > API Keys on a Multi-org/MSP console) to receive an API Key and API Secret pair.

The secret is shown only once at creation time and cannot be retrieved later - store it somewhere safe immediately.

This server exchanges that pair for a short-lived (1-hour) Bearer access token via POST /auth/v2/token (grant_type=client_credentials, HTTP Basic auth), and handles the exchange and its refresh on expiry internally. Callers only ever need to supply the long-lived API Key/Secret below.

A note on a real discrepancy in Cisco's own documentation: Cisco's published Postman collection (CiscoDevNet/cloud-security, Umbrella/PostmanExamples/umbrella-external-postman-collection.json) encodes the token request as a bare GET with no body, while Cisco's DevNet "Getting Started" and "Quickstart" prose docs both independently specify POST with a grant_type=client_credentials form body. This server follows the prose docs (POST), since two independent doc pages agree and it matches the standard OAuth2 client_credentials flow Cisco names explicitly - but this was not verified against a live credential pair. If token exchange 401s against a real account, try a bare GET with no body before assuming the credentials are bad.

Configuration

Tools

Deployments

• umbrella_list_networks - list registered public-IP network identities.
• umbrella_list_internal_networks - list internal (RFC1918) network identities.
• umbrella_list_sites - list Umbrella sites.
• umbrella_list_virtual_appliances - list virtual appliances and their status.
• umbrella_list_roaming_computers - list roaming-client-enrolled computers.
• umbrella_get_internal_domains - get all internal domains configured to bypass Umbrella DNS.

Admin

• umbrella_list_roles - list administrative roles.
• umbrella_list_users - list admin console users.
• umbrella_get_user - get a specific admin console user.
• umbrella_list_api_keys - list configured API keys.

Policies

• umbrella_list_destination_lists - list destination (allow/block) lists.
• umbrella_list_destinations - list destinations within a specific destination list.

Reports

• umbrella_top_destinations - most-requested destinations, optionally by traffic type (dns/proxy/firewall).
• umbrella_total_requests - total request counts, optionally by traffic type.
• umbrella_top_categories - most-requested content/security categories.
• umbrella_activity - raw activity log, optionally by traffic type.
• umbrella_identities - identities (roaming/network/mobile/AD users) with traffic summaries.
• umbrella_appdiscovery_applications - discovered cloud applications.
• umbrella_appdiscovery_app_identities - identities observed using a discovered application.
• umbrella_appdiscovery_app_risk - risk details for a discovered application.
• umbrella_api_usage_summary / umbrella_api_usage_requests / umbrella_api_usage_responses / umbrella_api_usage_keys - API usage reporting.

Investigate

• umbrella_domain_categorization - content/security categorization for a domain.
• umbrella_domain_risk_score - Cisco's risk score for a domain.
• umbrella_domain_security_score - detailed security scoring signals for a domain.
• umbrella_top_most_seen_domains - the top million most globally-popular domains.
• umbrella_get_samples - malware/file samples for a domain, IP, or URL.
• umbrella_domain_volume - DNS query volume over time for a domain.
• umbrella_domain_resource_records - passive DNS resource records for a domain.

Every Reports/Investigate/Deployments/Admin/Policies list tool that Cisco's docs don't fully enumerate the filter set for accepts an optional additionalParams object, passed through verbatim as extra query-string parameters (e.g. categories, identityids, verdict, domains on Reports endpoints) - documented Cisco filters this client doesn't model as first-class arguments.

Scope

This is a v1, read-only surface: this server only implements GET endpoints across Deployments, Admin, Policies, Reports, and Investigate. Explicitly deferred, all real endpoints in Cisco's own Postman collection, out of scope for now:

• Add/remove internal domains (POST/DELETE /deployments/v2/internaldomains)
• Add/remove tunnels (POST/DELETE /deployments/v2/tunnels)
• Add tags and tag/untag devices (POST /deployments/v2/tags*)
• Create/delete users (POST/DELETE /admin/v2/users)
• Create API keys (POST /admin/v2/apiKeys)
• Add/remove destinations on a destination list (POST/DELETE /policies/v2/destinationlists/{id}/destinations)
• Update an App Discovery application's label (PATCH /reports/v2/appDiscovery/applications/{id})

These are provisioning/mutation actions, out of scope for a read-only monitoring connector - consistent with how other connectors in this wave (Printix, WatchGuard Cloud) deferred provisioning-heavy writes. They can be added as a follow-up if a write-capable v2 is ever needed.

Also explicitly out of scope: the Legacy Umbrella Reporting v1/v2 APIs (different auth, different host - investigate.api.umbrella.com / management.api.umbrella.com) and any Multi-org/MSP child-organization switching via the X-Umbrella-OrgId header - real, documented Cisco behavior, but not covered in enough concrete request/response detail (whether it applies to the token request, every subsequent request, or both) to implement with confidence without a live credential pair to verify against.

Development

npm install
npm run build
npm test
npm run lint   # tsc --noEmit

Docker

docker build -t cisco-umbrella-mcp .
docker run -p 8080:8080 \
  -e CISCOUMBRELLA_API_KEY=... \
  -e CISCOUMBRELLA_API_SECRET=... \
  cisco-umbrella-mcp