Cisco Umbrella MCP Server
Read-only MCP server for querying Cisco Umbrella deployments, admin data, policies, reports, and Investigate intelligence.
List deployment inventory: networks, internal networks, sites, virtual appliances, roaming computers, and internal domains.
List admin roles, admin users, a specific user, and API keys.
List destination lists and the destinations within a list.
Query reports: top destinations/categories, total requests, raw activity, identities, App Discovery applications/identities/risk, and API usage summaries/logs/keys.
Investigate domains: categorization, risk score, security score, top-seen domains, malware samples, DNS volume, and passive DNS records.
Use paging/limits and
additionalParamspassthrough on many list/report tools.Read-only only; provisioning and mutation actions are explicitly out of scope.
Provides read-only access to Cisco Umbrella's NextGen REST API, enabling visibility into deployments, admin users and roles, policies, reporting data, and domain investigation such as categorization, risk scores, security scores, and passive DNS.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Cisco Umbrella MCP Server what is the risk score for example.com?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Related MCP server: ThousandEyes MCP
Configuration
Copy .env.example and set the variables below. The stdio transport reads CISCOUMBRELLA_* and does not use CONDUIT_S2S_SECRET.
Env var | Description |
| API Key from the Umbrella admin console. Required for stdio and |
| API Secret paired with the API Key. Shown only once at creation. Required for stdio and |
|
|
|
|
| Required for HTTP. HMAC secret checked against |
| Set to exactly |
| Bind address when |
| HTTP port. Defaults to |
|
|
/health and /healthz stay unauthenticated and do not read credentials.
HTTP authentication
With MCP_TRANSPORT=http and CONDUIT_S2S_SECRET set, every /mcp request must include X-Gateway-S2S. The check is verifyS2sHeader in src/s2s-verify.ts: the header value is t=<unix seconds>,v1=<hex>, where the hex is HMAC-SHA256 of the literal string t=<unix seconds> keyed with CONDUIT_S2S_SECRET (64 lowercase hex characters). The timestamp must be within 300 seconds of the server clock. A missing or invalid header is HTTP 401, before vendor credentials are read. An empty secret refuses to start unless MCP_ALLOW_INSECURE_DEV=1. A known placeholder (replace-with-a-real-secret, your-s2s-secret, changeme, change-me, placeholder, secret, example, replace-me, s2s-secret, any case) refuses to start even with that flag, so a copied example cannot forge the header.
TS=$(date +%s)
SIG=$(printf 't=%s' "$TS" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
curl -sS http://127.0.0.1:8080/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H "X-Gateway-S2S: t=${TS},v1=${SIG}" \
-H "X-CiscoUmbrella-Api-Key: $CISCOUMBRELLA_API_KEY" \
-H "X-CiscoUmbrella-Api-Secret: $CISCOUMBRELLA_API_SECRET" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'In AUTH_MODE=gateway, /mcp also requires both X-CiscoUmbrella-Api-Key and X-CiscoUmbrella-Api-Secret. Those headers are the only credential source for that request. A request missing either one returns 401 and does not fall back to CISCOUMBRELLA_* in the process environment.
AUTH_MODE=env still requires a valid X-Gateway-S2S header, then uses CISCOUMBRELLA_API_KEY and CISCOUMBRELLA_API_SECRET from the environment.
Request limits
HTTP request bodies are capped at 256 KiB (262144 bytes). After the
X-Gateway-S2Scheck passes, aContent-Lengthabove the cap returns 413 with a JSON-RPC error; bodies withoutContent-Lengthare capped by the MCP SDK transport. Unauthenticated requests still get 401 first.tools/callarguments are capped at 10,000 elements (every array item and object key at any depth). Larger inputs return anisErrortool result and are never dispatched.
These limits address CVE-2026-111768 / GHSA-46jr-4wx8-v453 (memory exhaustion during validation) and GHSA-f897-62hf-6gxq (no request body / batch cap).
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 --noEmitDocker
The image listens on 0.0.0.0 inside the container (MCP_HTTP_HOST) and defaults to AUTH_MODE=gateway. Startup still refuses to run without a real CONDUIT_S2S_SECRET. Publish the port on loopback. In gateway mode, Umbrella credentials arrive on each request as headers; they are not read from the environment.
docker build -t cisco-umbrella-mcp .
docker run \
-e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
-p 127.0.0.1:8080:8080 \
cisco-umbrella-mcpCompose refuses to start when CONDUIT_S2S_SECRET is unset, defaults AUTH_MODE to gateway, publishes 127.0.0.1:8080:8080, and does not set CISCOUMBRELLA_API_KEY, CISCOUMBRELLA_API_SECRET, or env_file:
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose upSingle-tenant HTTP (AUTH_MODE=env) still requires the S2S secret, then uses CISCOUMBRELLA_API_KEY and CISCOUMBRELLA_API_SECRET. It is separate from the gateway Compose service above.
docker run \
-e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
-e AUTH_MODE=env \
-e CISCOUMBRELLA_API_KEY=... \
-e CISCOUMBRELLA_API_SECRET=... \
-p 127.0.0.1:8080:8080 \
cisco-umbrella-mcpLocal HTTP without a secret is development-only. It binds 127.0.0.1 (including when MCP_HTTP_HOST is localhost or ::1) and logs a warning. A non-loopback MCP_HTTP_HOST makes startup exit. The container image sets MCP_HTTP_HOST=0.0.0.0, so the bypass inside Docker also needs -e MCP_HTTP_HOST=127.0.0.1. Do not publish that port off loopback.
MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm run start:httpAvailable Tools
31 toolsumbrella_activityC
Raw activity (request-level) log over a time range, optionally broken down by traffic type.
Inputs: to (required), from (required), limit, offset, +2 more.
umbrella_api_usage_keysB
API usage broken down by API key over a date range.
Inputs: to (required), from (required).
umbrella_api_usage_requestsC
Detailed API request log over a date range.
Inputs: to (required), from (required).
umbrella_api_usage_responsesC
Detailed API response log over a date range.
Inputs: to (required), from (required).
umbrella_api_usage_summaryC
Summary of this organization's Umbrella API usage over a date range.
Inputs: to (required), from (required).
umbrella_appdiscovery_app_identitiesB
List the identities (users/devices) observed using a specific discovered application.
Inputs: appId (required), limit, offset, additionalParams.
umbrella_appdiscovery_applicationsC
List cloud applications discovered in this organization's traffic (App Discovery).
Inputs: limit, offset, additionalParams.
umbrella_appdiscovery_app_riskA
Get risk details for a specific discovered application. Cisco's own Postman collection lists this endpoint under both "App Details" and "App Risk Details" - they are the same URL.
Inputs: appId (required).
umbrella_domain_categorizationC
Get the content/security categorization for a domain.
Inputs: domain (required).
umbrella_domain_resource_recordsB
Get passive DNS resource records (historical DNS resolutions) for a domain.
Inputs: domain (required).
umbrella_domain_risk_scoreC
Get Cisco's risk score for a domain (higher = riskier).
Inputs: domain (required).
umbrella_domain_security_scoreB
Get detailed security scoring signals for a domain (DGA score, perplexity, entropy, Secure Rank, etc).
Inputs: domain (required).
umbrella_domain_volumeB
Get DNS query volume over time for a domain.
Inputs: domain (required).
umbrella_get_internal_domainsA
Get all internal domains configured to bypass Umbrella DNS resolution.
Inputs: limit, offset, additionalParams.
umbrella_get_samplesA
Get malware/file samples associated with a domain, IP, or URL.
Inputs: domainIpOrUrl (required).
umbrella_get_userB
Get a specific Umbrella admin console user by user ID.
Inputs: userId (required).
umbrella_identitiesA
List identities (roaming computers, networks, mobile devices, AD users) with traffic summaries, filtered by one or more identity types.
Inputs: identityTypes (required), limit, offset, additionalParams.
umbrella_list_api_keysB
List all API keys configured for this Umbrella organization.
Inputs: no named parameters.
umbrella_list_destination_listsA
List all destination lists (allow/block lists) configured for this Umbrella organization.
Inputs: limit, offset, additionalParams.
umbrella_list_destinationsA
List the destinations (domains/URLs/IPs) contained in a specific destination list.
Inputs: destinationListId (required), limit, offset, additionalParams.
umbrella_list_internal_networksA
List internal (RFC1918) networks registered for internal-network identities.
Inputs: limit, offset, additionalParams.
umbrella_list_networksA
List Cisco Umbrella networks (public IP identities) registered to this organization.
Inputs: limit, offset, additionalParams.
umbrella_list_roaming_computersA
List all roaming computers enrolled via the Umbrella roaming client.
Inputs: limit, offset, additionalParams.
umbrella_list_rolesA
List all administrative roles available in this Umbrella organization.
Inputs: no named parameters.
umbrella_list_sitesB
List Umbrella sites (logical groupings of virtual appliances/internal networks).
Inputs: limit, offset, additionalParams.
umbrella_list_usersB
List all admin console users for this Umbrella organization.
Inputs: limit, offset, additionalParams.
umbrella_list_virtual_appliancesA
List all Umbrella virtual appliances (on-prem DNS forwarders) and their status.
Inputs: limit, offset, additionalParams.
umbrella_top_categoriesC
Report of the most-requested content/security categories over a time range.
Inputs: to (required), from (required), limit, offset, +1 more.
umbrella_top_destinationsB
Report of the most-requested destinations (domains) over a time range, optionally broken down by traffic type.
Inputs: to (required), from (required), limit, offset, +2 more.
umbrella_top_most_seen_domainsA
Get Cisco's list of the top million most globally-popular domains.
Inputs: no named parameters.
umbrella_total_requestsA
Total DNS/proxy/firewall request counts over a time range, optionally broken down by traffic type.
Inputs: to (required), from (required), limit, offset, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 31 tools
Most tools are tied to distinct Umbrella entities, but several clusters overlap: umbrella_identities overlaps with the individual network/roaming-computer listers, the four api_usage_* tools are near-variants of the same log, and the domain risk/security/categorization lookups can be confused. Descriptions disambiguate most cases, but an agent will need to read carefully.
All tools share the umbrella_ prefix and consistent snake_case, with recognizable list_/get_/top_ verbs in most entries. The domain_* and appdiscovery_* names are noun-style rather than verb-first, but the resource grouping is predictable.
31 tools is over the 25-tool comfort threshold and will bloat the tool picker even though they are grouped logically. Several families (api_usage_*, appdiscovery_*, domain_*) could be consolidated into fewer parameterized tools.
Read-only coverage is broad: networks, identities, appliances, reports, app discovery, API usage, and domain intelligence are all represented. However, the entire surface is list/get/report-oriented; there are no create/update/delete operations for destination lists, users, networks, or sites, so management workflows dead-end.
Maintenance
Related MCP Connectors
Lets AI agents analyze API metrics, request logs, and traces, and manage apps and alerts.
Query your team's drift, vulnerability, and upgrade data from any AI assistant. OAuth 2.1, 51 tools.
Ask your AI assistant about your logs, traces, security events, robot runs and video. Read-only.
1Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceProvides read-only access to Umbrella Cost finops platform, enabling natural language querying of multi-cloud cost data, optimization recommendations, anomaly detection, and budget tracking across AWS, Azure, and GCP.-
- AlicenseNot gradedqualityFmaintenanceEnables AI assistants to query Cisco ThousandEyes v7 API for network monitoring data including tests, agents, alerts, dashboards, and test results (network, page-load, web-transactions, path visualization) for faster troubleshooting through natural language.2Apache 2.0
- AlicenseBqualityDmaintenanceEnables AI assistants to manage and monitor UniFi Network Controllers through natural language. Provides 25 read-only tools for discovering devices and clients, viewing security configurations, analyzing network statistics, and exporting configuration data.41MIT
- AlicenseNot gradedqualityDmaintenanceEnables secure, read-only monitoring of Cisco Meraki networks, allowing AI agents to query real-time information on organizations, networks, devices, clients, and traffic without risk of configuration changes.MIT