Cisco Secure Access MCP Server

A production-ready Model Context Protocol (MCP) server that wraps the Cisco Secure Access REST API. Enables AI agents to investigate threats, pull reports, manage security policies, and administer deployment infrastructure through a standardized interface.

Summary

Cisco Secure Access (formerly Cisco Umbrella / Secure Web Gateway) provides DNS-layer security, web filtering, and Zero Trust network access. This MCP server bridges that platform to AI agents, enabling:

• Threat Investigation -- Look up domains, IPs, URLs, and user activity observed by Cisco's DNS resolvers
• Security Reports -- Pull activity, threat, and destination analytics with flexible time ranges
• Policy Management -- Create/update destination lists, access rules, security profiles, and DLP policies
• Domain Blocking -- One-tool block/unblock domains with automatic list management
• VPN & Device Control -- List active VPN sessions, disconnect users, revoke device certificates
• Infrastructure Admin -- Manage sites, networks, connectors, tunnel groups, and identity endpoints

The server implements the Streamable HTTP transport per the MCP specification, runs as a single Python process, and handles OAuth 2.0 token management automatically.

Time Format (IMPORTANT)

Cisco Secure Access API uses Unix epoch timestamps in milliseconds. This server converts automatically.

All time-accepting tools support three input formats:

| Format | Example | Converted to | |---|---|---| | ISO 8601 | 2025-01-15T08:30:00Z | 1736928600000 | | Relative | 24h, 7d, 30m, 900s | epoch ms from now | | Keyword | now | current epoch ms | | Epoch ms | 1735689600000 | passed through |

Architecture

+-------------+   JSON-RPC 2.0    +------------------+   OAuth2 + REST    +--------------------+
| MCP Client  | <----------------> | MCP Server       | <----------------> | Cisco Secure Access|
| (AI Agent)  |   Streamable HTTP | FastAPI +         |   api.sse.cisco.com| API                |
|             |   POST /mcp       | Tool Handlers     |                    |                    |
+-------------+                   +------------------+                    +--------------------+
                                      |
                                 +------------+
                                 | Token Cache|
                                 | per session|
                                 +------------+

Quick Start

Option 1: Docker Compose (Recommended)

cd cisco-secure-access-mcp

# Configure credentials
cp .env.example .env
# Edit .env with your Cisco API key and secret

# Build and run
docker compose up --build -d

# Check health
curl http://localhost:3000/health

Option 2: Direct Docker

docker build -t cisco-mcp-server .

docker run -d --name cisco-mcp \
  -p 3000:3000 \
  -e CISCO_API_KEY=your_key_here \
  -e CISCO_API_SECRET=your_secret_here \
  cisco-mcp-server

Option 3: Native Python

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

export CISCO_API_KEY=your_key_here
export CISCO_API_SECRET=your_secret_here
python server.py

Configuration

| Variable | Required | Description | Default | |---|---|---|---| | CISCO_API_KEY | Yes | OAuth client ID from Cisco portal | -- | | CISCO_API_SECRET | Yes | OAuth client secret | -- | | CISCO_ORG_ID | No | Child org ID for multi-org setups | Parent org | | MCP_SERVER_PORT | No | Listen port | 3000 | | MCP_SERVER_HOST | No | Bind address | 0.0.0.0 | | LOG_LEVEL | No | DEBUG, INFO, WARNING, ERROR | INFO |

Get credentials from the Cisco Secure Access portal: Admin > API Keys > Create New Key.

Available Tools (18)

Investigation & Forensics

| Tool | Description | |---|---| | investigate_domain | DNS query history, IPs, threats for a domain | | investigate_ip | Domains, threats, geo-location for an IP address | | investigate_url | Categorization, threat status for a specific URL | | investigate_user_activity | Complete user history: DNS, web, blocks, threats |

Reports & Analytics

| Tool | Description | |---|---| | get_activity_report | DNS queries, web requests, connection data | | get_top_threats | Most frequent threat categories and sources | | get_top_destinations | Most visited domains, IPs, and URLs | | get_top_identities | Most active users by request volume | | get_top_ips | Most contacted external IP addresses | | get_summary_report | Aggregate traffic volume and threat counts | | get_threat_types | Breakdown: malware, phishing, C2, etc. | | get_report | Generic handler: app_discovery, metering, api_usage, dlp_events |

Domain Blocking

| Tool | Description | |---|---| | add_domain_to_block_list | Block a domain (creates list if needed) | | remove_domain_from_block_list | Unblock a domain from a list |

VPN & Device Management

| Tool | Description | |---|---| | list_vpn_connections | Current VPN user sessions | | disconnect_vpn_user | Terminate a specific VPN session | | revoke_device_certificates | Revoke device access certificates |

Generic Resource Management

| Tool | Description | |---|---| | manage_resource | CRUD for all Admin/Policies/Deployments resources |

manage_resource accepts:

• domain: admin, policies, deployments
• resource: resource slug (see lists below)
• operation: list, create, update, delete
• resource_id: required for update/delete
• resource_params: attributes dict for create/update
• params: query parameters for list operations

Available resources per domain:

admin: api_keys, user_devices, vpn_connections, integrations, alert_rules, tenants, threat_intel_feeds, tenant_controls, s3_bucket_key

policies: destination_lists, application_lists, access_rules, network_objects, security_feeds, security_profiles, content_categories, application_categories, ips_profiles, dlp_rules, do_not_decrypt, private_resources

deployments: tunnel_groups, tunnel_regions, connector_groups, connectors, roaming_computers, swg_device_settings, internal_domains, sites, networks, internal_networks, network_devices, dns_forwarders, identity_endpoints, virtual_appliances

Usage Examples

Investigate a suspicious domain

{"tool": "investigate_domain", "arguments": {"domain": "suspicious-site.com", "limit": 20}}

Get threat report for last 7 days

{"tool": "get_top_threats", "arguments": {"start_time": "7d", "end_time": "now", "limit": 50}}

List all deployment sites

{"tool": "manage_resource", "arguments": {"domain": "deployments", "resource": "sites", "operation": "list"}}

Block a malware domain

{"tool": "add_domain_to_block_list", "arguments": {"domain": "malware.example.com"}}

Create a new site definition

{
  "tool": "manage_resource",
  "arguments": {
    "domain": "deployments",
    "resource": "sites",
    "operation": "create",
    "resource_params": {"name": "office-1", "ipAddresses": ["10.0.0.0/24"]}
  }
}

Disconnect a compromised user VPN

{"tool": "disconnect_vpn_user", "arguments": {"user_id": "compromised-user"}}

Update a destination list

{
  "tool": "manage_resource",
  "arguments": {
    "domain": "policies",
    "resource": "destination_lists",
    "operation": "update",
    "resource_id": "list-abc123",
    "resource_params": {"name": "blocked-sites", "entries": ["bad.com"]}
  }
}

Error Handling

• 429 Rate Limited: Automatic exponential backoff retry (up to 3 attempts)
• 5xx Server Errors: Automatic retry with backoff (up to 3 attempts)
• 401/403 Auth Errors: Returned immediately with clear diagnostic message
• Token Expiry: Automatic refresh 5 minutes before TTL expires
• Connection Pooling: httpx client with 20 max connections, 10 keepalive

Best Practices

Security

1. Never hardcode credentials. Always use .env files or environment injection via Docker secrets, Kubernetes secrets, or cloud secret managers.
2. Rotate API keys regularly. Use manage_resource with domain=admin, resource=api_keys to create/delete keys.
3. Use scoped API keys. Request only the permissions your use case needs.
4. Run as non-root. The Docker image uses a dedicated appuser account.
5. Restrict network access. Bind to 127.0.0.1 if the MCP client runs locally, or use a VPN/firewall for remote access.

Deployment

1. Use health checks. The /health endpoint enables container orchestration liveness checks.
2. Set resource limits. In docker-compose, add deploy.resources.limits for CPU/memory.
3. Enable structured logging. Set LOG_LEVEL=DEBUG for troubleshooting, INFO for production.
4. Monitor token usage. API key creation tracks scopes and usage patterns via get_report with report_type=api_usage.

Operational

1. Prefer manage_resource for CRUD. Covers 50+ endpoints with a single tool. Use dedicated tools only when convenience matters (e.g., add_domain_to_block_list).
2. Use relative time offsets. 24h, 7d, 30m are simpler than ISO 8601 for most queries.
3. Paginate large result sets. Use limit and offset parameters for list operations.
4. Handle rate limits gracefully. The server retries automatically, but design your workflow to space out high-volume queries.
5. Backup destination lists. Before modifying block lists, list the current entries first.

Multi-Org Support

For organizations with child orgs, set CISCO_ORG_ID to the child organization's ID. The server adds the X-Umbrella-OrgId header automatically to all API requests.

Testing

pip install pytest pytest-asyncio
pytest test_server.py -v

Covers: epoch time conversion, tool registration, endpoint mapping, API retry logic, token caching, transport layer, and all 18 tool handlers.

License

MIT