Content
# cisco-secure-access-mcp
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`](./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`](https://github.com/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`](./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
```bash
# 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`](./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](https://developer.cisco.com/docs/cloud-security/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](./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):
```bash
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):
```bash
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`](./install.md) Phase 9 (2026-05-04
> follow-up) and [`TOOLS.md`](./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
```bash
# 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`](./SECURITY.md).
---
## License
Apache License 2.0 — see [`LICENSE`](./LICENSE).
