Architecture - Cisco Secure Access MCP Server

🏗️ System Overview

The MCP server acts as an intelligent bridge between AI agents and the Cisco Secure Access platform. It translates natural language requests into API calls, handles authentication, and provides semantic search over documentation.

🔐 OAuth with Dynamic Client Registration (DCR)

The MCP server implements OAuth 2.0 with DCR and PKCE for secure authentication. This allows AI agents to dynamically register as OAuth clients and obtain tokens without pre-registration.

→
Dynamic Client Registration (DCR) — AI agents can register themselves as OAuth clients at runtime via POST /oauth/register, receiving a client_id and client_secret.
→
PKCE Authorization Flow — Proof Key for Code Exchange prevents authorization code interception attacks. The agent generates a code verifier/challenge pair for each authorization request.
→
Protected Resource Metadata — Standard OAuth discovery endpoints (/.well-known/oauth-protected-resource) allow agents to discover authentication requirements automatically.
→
Header-Based Auth — For simpler integrations, agents can pass Cisco API credentials directly via X-Cisco-Client-Id and X-Cisco-Client-Secret headers.

🐍 API Wrapping with Python SDK

The MCP server wraps the Cisco Secure Access APIs using an auto-generated Python SDK, providing type-safe access to all platform operations.

→
Auto-Generated SDK — The Python SDK is generated from the official OpenAPI specification, ensuring complete API coverage and type safety.
→
SDK Adapter Layer — Each SDK method is wrapped as an MCP tool with proper input validation, error handling, and response formatting.
→
Hierarchical Tool Discovery — Tools are organized into 15 categories (Policies, Users, Reports, etc.) so agents can discover relevant operations without overwhelming context.
→
OAuth2 Client Credentials — The SDK handles token acquisition and refresh automatically using client credentials flow.

87

API Classes

598

Data Models

1,248+

Total Methods

📚 Documentation Search with Sentence Transformers

The MCP server includes a semantic search capability over Cisco Secure Access documentation, powered by sentence transformer embeddings.

→
Vector Embeddings — Documentation pages are chunked and embedded using sentence transformers (all-MiniLM-L6-v2), creating dense vector representations for semantic matching.
→
500+ Indexed Documents — The entire Cisco Secure Access documentation corpus is indexed, including API references, configuration guides, and troubleshooting articles.
→
Semantic Search Tool — AI agents can search documentation using natural language queries via the search_documentation tool, receiving relevant excerpts with source links.
→
Context Augmentation — Search results provide agents with domain knowledge to answer questions and make informed decisions about API operations.

🔗 Key Endpoints

→
/mcp — MCP JSON-RPC endpoint (streamable-http transport)
→
/.well-known/oauth-protected-resource — Protected resource metadata for OAuth discovery
→
/.well-known/oauth-authorization-server — Authorization server metadata
→
/oauth/register — Dynamic client registration endpoint
→
/oauth/authorize — PKCE authorization endpoint
→
/oauth/token — Token exchange endpoint