read thedocs.

Cisco Umbrella is a cloud-delivered security platform: DNS-layer security, a secure web gateway, a cloud-delivered firewall, and — as a separately-licensed add-on — the Investigate threat-intelligence dataset. MSPs use it to enforce web and DNS policy, inspect traffic, and hunt threats across their client organizations.

Connecting Umbrella to StackJack gives your AI assistant a family of 233 umb_ MCP tools — MCP (Model Context Protocol) tools are the standardized commands an AI assistant can call through StackJack. With them, your AI can:

• Deploy and manage networks, IPsec tunnels, sites, virtual appliances, roaming computers, network devices, internal networks, and internal domains
• Control policy — read and edit destination (allow/block) lists and application lists, and attach or detach identities on deployment policies
• Report on DNS, proxy, and firewall activity — top destinations, identities, and threats, request/category/bandwidth aggregations and summaries, App Discovery (shadow IT), and your own API-key usage
• Administer the org — users, roles, and API keys
• Manage provider consoles — the Managed Providers (Multi-Org/MSP) console and the Service-Provider/MSSP console: partner customer CRUD, packages and subscriptions, trial lifecycle, delegated access-requests, console branding, and provider-wide reporting
• Investigate (Pro, license-gated) domains, IPs, and files against Cisco's threat-intelligence graph: WHOIS (history, by-nameserver, by-email, search), passive DNS, BGP routes, subdomains, co-occurrences, risk scores, and sample analysis
• Act (on Pro plans) — create, update, and delete the deployment, policy, admin, and provider-console objects above

How StackJack authenticates to Cisco Umbrella

Umbrella issues API credentials as a pair, created together in the Umbrella dashboard: an API Key (the public identifier) and an API Key Secret (the private secret). StackJack Basic-authenticates that pair to mint a short-lived bearer token from POST https://api.umbrella.com/auth/v2/token, then caches it and re-mints it automatically before it expires — nothing for you to manage. There is no refresh token — recovery is always a fresh token request, so a revoked key fails closed on the next mint.

The base URL is fixed at https://api.umbrella.com for commercial orgs. (Umbrella for Government customers are on a separate host.) StackJack stores that default for you, so you normally leave the URL field blank.

One StackJack Umbrella credential maps to exactly one Umbrella organization. The org is chosen when you create the API key, and Umbrella's operational endpoints carry no org parameter — so a single key/secret backs the whole connector for one org. The Managed Providers (Multi-Org/MSP) console and the Service-Provider/MSSP console customer-management tools are now covered too: they take no org parameter and run through this same single key, but require a provider-tier key carrying the relevant admin.customers / admin.config / reporting scopes (a normal per-org key returns 403). The legacy v1 /serviceproviders/… surface remains out of scope.

Before you begin

• In StackJack: you need a role that can manage connectors — tenant Owner, a co-owner, or an Administrator.
• In Umbrella: you need administrator access to your Umbrella dashboard.
• Decide which scopes you need. The scopes you grant the key at creation gate exactly what StackJack can do — see "Scopes drive tool access" below. Grant at least Deployments (read) even if you don't use Deployments tools, so Test Connection can validate.

Step 1 — Generate API credentials in Cisco Umbrella

1. Sign in to the Umbrella dashboard as an administrator and go to Admin → API Keys.
2. Click Add (or Create Key / the + button). Give the key a name and choose its scopes — grant Read and/or Read/Write on the resource families you want StackJack to manage: Admin, Deployments, Policies, Reports. Add Investigate only if you hold that license. One key can carry every family.
3. Umbrella shows the API Key and API Key Secret once. Copy both immediately — the secret is not shown again, only regenerated.

Scopes drive tool access

A key's scopes decide which tools work. A key granted Read-Only on a family can run that family's read tools (the Free-tier surface) but cannot call its Pro write tools — a write attempt returns 403. If a Pro write tool 403s, re-issue the API key with the family's write scope (for example edit:admin for user and API-key writes); it is not a "connector not configured" error.

Include the Deployments (read) scope even if you don't use Deployments tools. StackJack's Test Connection validates by calling a Deployments endpoint, so a key scoped only to other families (say, Reports-only) will save but show "validation failed" while its in-scope tools still work fine. Adding Deployments read gets you a clean validation result.

Investigate requires a separate license

The roughly 24 umb_investigate_* threat-intelligence tools query Cisco's Investigate graph, which is a separately-purchased Umbrella Investigate add-on (a paid, tiered subscription). Without it — and without the Investigate scope on your key — those tools return 403/404. umb_investigate_samples additionally requires a Cisco Secure Malware Analytics license. Every other tool works with a standard Umbrella subscription. Investigate tools are read-only but ship on the Pro tier.

Step 2 — Add the credentials in StackJack

1. In the StackJack portal, open Connectors.
2. Find the Cisco Umbrella card. Click How To Connect for the same steps inline, or Configure to enter the credentials.
3. Paste the API Key into the API Key field and the API Key Secret into the API Key Secret field. Leave the URL blank to use the commercial cloud (https://api.umbrella.com); set it only for Umbrella for Government.
4. Click Save.

What happens when you save

• The key and secret are stored encrypted in Azure Key Vault — never in the StackJack database, and never shown back to you.
• If this is the first time you configure Umbrella, a Free-tier subscription for the connector is created automatically so its Free tools work right away.
• StackJack immediately live-validates the credentials by minting a token and calling a cheap Deployments read. Validation never blocks the save: you'll either see a success confirmation or a "saved but validation failed" warning with the reason.
• The connector card shows the current connection and validity status from then on.

Plans and available tools

• Free includes the 140 read tools: Deployments, Policies, Reports, and Admin reads — networks, tunnels, sites, devices, destination lists, application lists, deployment policies, activity/aggregation/summary reports, App Discovery, API usage, users, roles, API-key metadata, and the Managed-Provider / Service-Provider console reads (customers, packages, subscriptions, branding, provider reporting).
• Pro adds the 93 remaining tools: the 69 write/action tools (creates, updates, deletes, tag/identity/destination changes, provider-console management, key/credential rotations) plus the 24 Investigate intelligence tools.
• Business offers the same 233-tool set as Pro with a higher monthly call quota — it unlocks no additional tools.

Umbrella has no per-user OAuth (PKCE) sign-in, so there is no per-user attribution — all AI traffic uses the shared key pair on every tier. Current pricing and quotas are shown in the portal's Billing page and at checkout.

Safety note: several Pro tools delete or detach state and are irreversible — for example umb_delete_destination_list, umb_delete_roaming_computer, umb_delete_user, and umb_remove_destinations. Scope your AI's access deliberately: use the tool selections on the MCP Setup page and the Permissions page to enable only the actions you want an AI to take, and consider a read-only-scoped key unless you specifically need write tools.

Rate limits

Umbrella publishes different per-minute limits per API family — some as low as roughly 14 requests/minute for the admin and deployments families, much higher for policies. StackJack paces its Umbrella calls per tenant and honors Umbrella's 429 backoff, so bursts of tool calls queue briefly instead of failing — a long multi-page read may simply take a little longer.

Rotating or replacing the credentials

Umbrella reveals the API Key Secret only at creation, so if you lose it you must rotate rather than look it up:

1. In Umbrella, either rotate the existing key's secret (umb_refresh_api_key, or Refresh in the dashboard) or create a new key with the same scopes and copy its new secret.
2. Immediately update Connectors → Cisco Umbrella → Configure in StackJack with the new pair.

Troubleshooting