Community MCP Server for Cisco Secure Access

A Model Context Protocol (MCP) server that exposes Cisco Secure Access API operations as agent-callable tools over Streamable HTTP.

Repository: https://github.com/CiscoDevNet/secure-access-mcp-community

Overview

This server provides Cisco Secure Access tools for destination list management, domain investigation, access policy inspection, reports, activity, and infrastructure inventory. MCP-compatible clients can discover the tools, inspect their schemas, and call them from natural language prompts.

Protocol: Streamable HTTP
Default URL: http://127.0.0.1:8000/mcp
Python: 3.10+ (Python 3.11 or newer recommended)

Tools (72)

Destination Lists Management (Read)

Destination Lists Management (Write)

Domain Investigation

Access Rules (Policies)

Reports - Summary & Totals

Reports - Top Aggregations

Reports - Summaries by Dimension

Reports - Time Series

Reports - Granular Activity

Infrastructure

Project Structure

secure-access-mcp-community/
├── cisco_secure_access_mcp/
│   ├── __init__.py
│   ├── __main__.py          # Entry point: python -m cisco_secure_access_mcp
│   ├── auth.py              # OAuth2 client credentials token manager (cache, refresh, retry)
│   ├── client.py            # Async Cisco Secure Access REST client (pool, retries, paginate, audit logs)
│   ├── logging_config.py    # Structured JSON logging + secret redaction
│   ├── security.py          # Auth, rate limit, payload limit, request IDs (ASGI middleware)
│   ├── server.py            # FastMCP Streamable HTTP server + security wiring
│   └── tools/
│       ├── all_tools.py     # MCP tool definitions
│       └── destination_lists.py
├── README.md
├── requirements.txt
├── .env.example
└── mcp_config.example.json

Prerequisites

• Python 3.10+ (Python 3.11 or newer recommended)
• Cisco Secure Access API key and secret with the scopes needed for the tools you plan to use:
  • Policies: destination lists and access rules
  • Investigate/Security: domain categorization and risk information
  • Reports: activity, summaries, top destinations, threats
  • Deployments/Admin: roaming computers, internal networks, tunnels

Installation

Option A: uv (recommended)

uv is a fast Python package and project manager. If you don't have it yet:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# or: brew install uv / pipx install uv

Clone the repository, create a Python 3.11 environment, and install dependencies:

git clone https://github.com/CiscoDevNet/secure-access-mcp-community.git
cd secure-access-mcp-community

# Create a virtual environment pinned to a supported interpreter.
# uv downloads Python for you if it is not installed locally.
uv venv --python 3.11

# Install dependencies from requirements.txt into the environment.
uv pip install -r requirements.txt

Run the server without manually activating the venv:

uv run python -m cisco_secure_access_mcp

uv run automatically uses the project's .venv, so you do not need to source anything. You can still activate it the traditional way (source .venv/bin/activate) if you prefer.

Option B: venv + pip

git clone https://github.com/CiscoDevNet/secure-access-mcp-community.git
cd secure-access-mcp-community
python3.11 -m venv venv
source venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

If python3.11 is not available, use any Python 3.10+ interpreter. The mcp package is not available for Python 3.9, so python3 -m venv venv can fail on systems where python3 still points to Python 3.9.

Configuration

Copy the example environment file and fill in your credentials:

cp .env.example .env

Usage

Generate a strong client token, then run the server (authentication is required by default):

export SECURE_ACCESS_API_KEY="your-api-key"
export SECURE_ACCESS_API_SECRET="your-api-secret"
export MCP_AUTH_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
python -m cisco_secure_access_mcp

MCP clients must then send Authorization: Bearer $MCP_AUTH_TOKEN on every request.

With uv (no manual venv activation needed):

export SECURE_ACCESS_API_KEY="your-api-key"
export SECURE_ACCESS_API_SECRET="your-api-secret"
export MCP_AUTH_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
uv run python -m cisco_secure_access_mcp

No-auth testing mode (not recommended)

For isolated local experimentation only, you can start the server without client→server authentication. The server refuses to start without either MCP_AUTH_TOKEN or this flag, and refuses the no-auth mode on any non-loopback host:

# NOT RECOMMENDED: anyone who can reach the port can use your Cisco credentials.
MCP_ALLOW_NO_AUTH=true python -m cisco_secure_access_mcp

A prominent warning is printed and logged at startup while in this mode.

The server listens at:

http://127.0.0.1:8000/mcp

To use a different host or port:

HOST=0.0.0.0 PORT=8080 python -m cisco_secure_access_mcp

Use 127.0.0.1 for local-only access. Use 0.0.0.0 only when you intentionally need LAN or remote access, preferably behind HTTPS and access controls.

MCP Client Configuration

Start the server first, then configure your MCP client to connect to the Streamable HTTP URL.

For Streamable HTTP, the recommended setup is to keep Cisco credentials in the server process environment or .env file and keep MCP client configuration URL-only. Clients must also present the bearer token from MCP_AUTH_TOKEN in the Authorization header.

Cursor

Add to Cursor MCP settings (replace YOUR_MCP_AUTH_TOKEN with the value of MCP_AUTH_TOKEN):

{
  "mcpServers": {
    "cisco-secure-access": {
      "url": "http://127.0.0.1:8000/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_AUTH_TOKEN"
      }
    }
  }
}

VS Code Copilot

Add to .vscode/mcp.json or user MCP settings:

{
  "servers": {
    "cisco-secure-access": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_AUTH_TOKEN"
      }
    }
  }
}

MCP Inspector

npx @modelcontextprotocol/inspector http://127.0.0.1:8000/mcp
# Set an "Authorization: Bearer <MCP_AUTH_TOKEN>" header in the Inspector UI,
# or start the server with MCP_ALLOW_NO_AUTH=true for local-only testing.

Example Queries

Once connected, ask an MCP-compatible agent questions like:

Architecture

MCP client
   |
   | Streamable HTTP + Authorization: Bearer <MCP_AUTH_TOKEN>
   v
Security middleware  (auth, rate limit, payload limit, request IDs, access logs)
   |
   v
FastMCP server  (DNS-rebinding / Host + Origin validation)
   |
   v
72 MCP tools  (input validation, destructive-action confirmation, optional PII redaction)
   |
   v
Async Secure Access client  (token cache/refresh, pooling, retries, audit logs)
   |
   v
Cisco Secure Access API

Security

• Client→server authentication (required by default). Every request must carry Authorization: Bearer <MCP_AUTH_TOKEN>; the token is compared in constant time. The server refuses to start without either MCP_AUTH_TOKEN or the explicit MCP_ALLOW_NO_AUTH=true testing flag.
• No-auth testing mode (not recommended). MCP_ALLOW_NO_AUTH=true runs without authentication for isolated local testing only; it is rejected on non-loopback hosts and prints/logs a prominent warning.
• DNS-rebinding protection. Host/Origin validation via FastMCP transport_security, defaulting to the bound host plus loopback names (MCP_ALLOWED_HOSTS / MCP_ALLOWED_ORIGINS).
• DoS protections. Inbound payload size cap (MCP_MAX_REQUEST_BYTES) and per-client-IP rate limiting (MCP_RATE_LIMIT_RPM).
• Auditability. Structured JSON logs (stderr) with per-request correlation IDs (X-Request-ID) for transport requests and outbound Cisco API calls. A redaction filter keeps credentials/tokens out of logs.
• Safer tools. Destructive tools (delete_destination_list, remove_destinations_from_list) use two-stage commit (confirm=true) and carry destructiveHint annotations; write tools validate inputs server-side (allowlists, length/count caps). Optional PII redaction for report/activity outputs via SECURE_ACCESS_REDACT_PII.

Still operator-owned (recommended for production): terminate TLS/mTLS at a reverse proxy in front of this server, prefer a secret manager over .env, and run the process sandboxed/least-privilege. Rate limiting is per-process — enforce limits at the gateway when running multiple workers.

Key Implementation Details

• Streamable HTTP only: the server always starts with transport="streamable-http".
• OAuth2 token management: auth.py caches a single client-credentials token for its full lifetime (≈1 request/hour) and refreshes it ~60s before expiry, with exponential backoff retries on 429/5xx/network errors.
• Connection pooling: client.py keeps one pooled httpx.AsyncClient for the whole server lifetime instead of opening a new connection per request, and closes it on shutdown.
• Automatic retries: rate-limited (429) responses are retried for any method (honoring Retry-After); 5xx and transient network failures are retried only for idempotent reads.
• Pagination: SecureAccessClient.paginate() walks every page (page/limit, capped at 100/page) until a short page, the reported total, an optional max_items cap, or the page-count safety cap is reached.
• User-Agent tracking: every token and API request sends a User-Agent (see get_user_agent() in cisco_secure_access_mcp/__init__.py), overridable via SECURE_ACCESS_USER_AGENT, so Cisco can attribute backend traffic to this MCP server.
• Redirect handling: reports redirects are followed only for HTTPS Cisco-controlled hosts.
• Response limits: large responses are rejected to avoid oversized tool results.
• Credentials: API credentials are read from environment variables or .env, not source code.

Dependencies

License

See LICENSE file for details.