Cisco Secure Access

A community Model Context Protocol (MCP) server for Cisco Secure Access.

It exposes the Secure Access REST API to MCP-compatible AI clients (Cursor, Claude Desktop, VS Code GitHub Copilot, etc.) as a curated catalog of tools grouped by Cisco's own resource categories: Admin, Deployments, Investigate, Policies, and Reports.

Status: v1.1 + composites batches 1 & 2 — 5 categories / 44 modules / 185 tools. See install.md for the build journal and per-phase progress.

---

Why a community DevNet server

This repo is structured to be hosted as a Cisco DevNet community MCP server, following the CiscoDevNet/devnet-template layout. The standard template files (AGENTS.md, CODE_OF_CONDUCT.md, CONTRIBUTING.md, LICENSE, README.md, SECURITY.md) are present and conform to that template.

In addition, install.md is a working journal that captures every step taken to build the server, troubleshooting notes, and any tools we add as enhancements. It is intentionally kept in-tree so future contributors can see the reasoning trail.

---

Quick start

# 1. Clone and install (using uv)
git clone https://github.com/sdntechforum/Secure_Access.git
cd Secure_Access
uv sync

# 2. Provide your Cisco Secure Access API credentials via environment variables
#    (Admin > API Keys in the Secure Access dashboard)
export SECURE_ACCESS_API_KEY=...
export SECURE_ACCESS_API_SECRET=...

# 3. Run the server (stdio transport, default)
uv run cisco-secure-access-mcp

For client configuration (Cursor / Claude Desktop / VS Code), Docker usage, the full list of tools, and the list of supported environment variables, see AGENTS.md.

---

Authentication at a glance

• OAuth 2.0 Client Credentials Flow against POST https://api.sse.cisco.com/auth/v2/token.
• Bearer token cached in memory and refreshed shortly before its 1-hour expiry.
• Credentials read from environment variables only — never from CLI flags or committed files.
• Multi-org / MSSP supported via SECURE_ACCESS_ORG_ID (sent as X-Umbrella-OrgId).
• A separate, optional Key Admin credential pair gates the small set of tools that manage other API keys.

See Cisco Secure Access — API Authentication for how to mint API keys.

---

Tool catalog

The full catalog of every MCP tool exposed by this server — grouped by Cisco's category taxonomy (Admin / Deployments / Investigate / Policies / Reports), with API path, signature, one-line description, and live verification status for each module — lives in TOOLS.md.

At a glance: 185 tools across 5 categories / 44 modules. 0 prompts, 0 resources — this is a tools-only MCP server.

To regenerate the catalog directly from the registered code (no hand-maintained list to drift):

python scripts/dump_catalog.py            # human-readable text
python scripts/dump_catalog.py --json     # machine-readable JSON

To re-run the live verification (requires a Cisco Secure Access API key

• secret):

pytest -m integration tests/integration/test_list_coverage.py -v

Status note for community evaluators: as of 2026-05-04 a coverage sweep against a real Secure Access tenant found that ~32 of 47 reachable list endpoints return 404 no Route matched, indicating the v1.1 API_BASE paths in many tool modules don't match the live Cisco surface. The auth + client + retry layers are bulletproof (every 2xx exercised them end-to-end), and Admin/Deployments/ Investigate/Policies/Reports each have at least one verified working module. See install.md Phase 9 (2026-05-04 follow-up) and TOOLS.md for which modules are verified vs. need a path fix. Contributions welcome.

---

Repo layout

.
├── AGENTS.md              # Install + tool catalog + env vars (read this first if you're an AI agent)
├── CODE_OF_CONDUCT.md     # Cisco DevNet template (unchanged)
├── CONTRIBUTING.md        # Cisco DevNet template (project name filled in)
├── LICENSE                # Apache-2.0 (Cisco DevNet template)
├── README.md              # this file
├── SECURITY.md            # Cisco DevNet template (project name filled in)
├── TOOLS.md               # Full tool catalog (185 tools, per-module verification status)
├── install.md             # Build journal — phases, troubleshooting, enhancements
├── pyproject.toml         # Package metadata + entry point
├── Dockerfile             # Optional secondary distribution
├── .env.example           # Documented env vars; NEVER real secrets
├── scripts/
│   └── dump_catalog.py    # Generates TOOLS.md content from the live registry
├── src/cisco_secure_access_mcp/
│   ├── server.py          # FastMCP entrypoint (stdio default)
│   ├── auth.py            # OAuth2 client-credentials + token cache
│   ├── client.py          # httpx-based REST client (TLS-only, retry-aware)
│   ├── config.py          # Env-var loading + validation
│   ├── errors.py          # SDK / HTTP errors → MCP errors
│   ├── logging.py         # Structured JSON logs with secret redaction
│   ├── registry.py        # Discovers and registers tools from each category
│   └── tools/
│       ├── admin/         # admin_*  — Admin Resources
│       ├── deployments/   # deploy_* — Deployments Resources
│       ├── investigate/   # investigate_* — Investigate Resources (v1.1)
│       ├── policies/      # policy_*  — Policies Resources
│       └── reports/       # report_*  — Reports Resources (v1.1)
└── tests/
    ├── unit/              # Offline; mock HTTP and clock
    └── integration/       # Opt-in; requires real DevNet sandbox credentials

---

Running the tests

# Unit tests only — fast, fully offline (default)
uv run pytest

# Live smoke tests against a real Secure Access tenant — opt-in only
export SECURE_ACCESS_API_KEY=...
export SECURE_ACCESS_API_SECRET=...
# optional: SECURE_ACCESS_ORG_ID, SECURE_ACCESS_BASE_URL
uv run pytest -m integration tests/integration

The smoke tests are read-only by design: they exercise list/get endpoints across each category (and one Investigate domain-categorization call against cisco.com) and never mutate the org. Override the test domain with SECURE_ACCESS_INTEGRATION_TEST_DOMAIN=example.com if needed.

---

Security

This repo follows the security rules in .cursor (parameterization, no hardcoded credentials, structured logging with redaction, TLS 1.2+ enforcement, distroless-style container hardening, etc.). To report a vulnerability, see SECURITY.md.

---

License

Apache License 2.0 — see LICENSE.