Product Overview¶
Product: AI-Bridge for Cisco UC Version: v202604 Author: Pierre SOURDEAU Last Updated: April 2026
Project Overview¶
What is AI-Bridge for Cisco UC¶
AI-Bridge for Cisco UC is a Model Context Protocol (MCP) server that bridges AI/LLM platforms to Cisco Unified Communications on-premises infrastructure. It enables any MCP-compatible AI agent — such as Claude Desktop, GitHub Copilot, Cursor, or custom LLM-based tools — to interact directly with Cisco UC systems through a secure, authenticated, and auditable interface.
The server exposes Cisco UC operations (AXL/SOAP, RIS, SSH) as MCP tools, along with guided workflows as MCP prompts and reference documentation as MCP resources. AI agents consume these capabilities using the standard MCP protocol over Streamable HTTP transport.
Key value proposition:
- Empower Cisco UC administrators with AI-assisted operations: configuration queries, security audits, health checks, report generation, and troubleshooting — all driven by natural language through an AI agent.
- No Cisco UC expertise required in the AI model — the MCP server provides all the context, tools, and domain-specific prompts the AI needs to interact correctly with CUCM, IMP, and CUC systems.
- Production-grade security — enterprise authentication, RBAC, credential encryption, audit trail, and air-gapped deployment support.
AI-Bridge for Cisco UC is developed and published by Pierre SOURDEAU.
- Contact: contact@sourdeau.com
- Support: support@sourdeau.com
- License: Proprietary — see
LICENSE
Deployment Model (Air-Gapped, No Cloud Dependency)¶
AI-Bridge for Cisco UC is designed for fully on-premises, compatible with air-gapped deployment:
- No cloud dependency — the server runs entirely on the customer's infrastructure. No data is sent to any external service. No telemetry, no analytics, no phone-home mechanism.
- No outbound connections — the server only connects to the Cisco UC nodes explicitly configured by the administrator (AXL over HTTPS, SSH). It never initiates connections to the internet.
- Offline licensing — licenses are RS256-signed JWT files issued offline by the editor and installed locally. No license server or online activation is required.
- Offline upgrades — upgrade packages are delivered as signed
.tar.gzarchives. Integrity is verified via DNS-published SHA-256 checksums and RSA-PSS digital signatures. - Offline AI operation — the MCP protocol runs over the local network between the AI agent and the MCP server. If the AI agent itself runs locally (e.g., a local LLM), the entire chain operates without any internet connectivity.
- Reverse proxy support (optional) — a web reverse proxy (e.g., Nginx, Apache, HAProxy) can be placed in front of the MCP server for TLS termination, load balancing, or network segmentation. The server's transport security layer (Host/Origin validation) is compatible with proxied requests when
MCP_SERVER_SECURITY_ALLOWED_HOSTSis configured accordingly. - Standalone with multi-instance redundancy — each AI-Bridge instance is a standalone server with no inter-instance communication or shared state. For high availability, multiple instances can be deployed behind a load-balancing reverse proxy. Each instance must share the same
.envconfiguration, RSA key pair, license file, and client directories (e.g., via shared storage or synchronized deployment). The reverse proxy distributes incoming MCP requests across instances.
This architecture makes AI-Bridge suitable for regulated environments, government networks, and any organization where data sovereignty and network isolation are requirements.
Standard deployment model:
┌─────────────────────────────────────────────────────────────────────────────┐
│ Customer Network │
│ │
│ ┌─────────────┐ ┌──────────┐ ┌─────────────┐ │
│ │ LLM │ API │ AI Agent │ │ Web │ │
│ │ (OpenAI, │◄──────►│ (Claude, │───────►│ Reverse- │ │
│ │ Anthropic, │ │ Copilot,│ │ Proxy │ │
│ │ Local LLM) │ │ etc.) │ │ (optional) │ │
│ └─────────────┘ └──────────┘ └──────┬──────┘ │
│ Cloud or Local │ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ AI-Bridge │ │
│ │ Instance 1 │ │
│ │ (MCP Server) │ │
│ └──────┬───────┘ │
│ │ │
│ ┌──────┴─────┐ │
│ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ │
│ │ CUCM │ │ IMP │ │
│ └──────────┘ └──────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Redundant deployment model (optional):
┌──────────────────────────────────────────────────────────────────────────────┐
│ Customer Network │
│ │
│ ┌─────────────┐ ┌──────────┐ ┌─────────────┐ │
│ │ LLM │ API │ AI Agent │ │ Web │ │
│ │ (OpenAI, │◄──────►│ (Claude, │───────►│ Reverse- │ │
│ │ Anthropic, │ │ Copilot,│ │ Proxy / │ │
│ │ Local LLM) │ │ etc.) │ │Load Balancer│ │
│ └─────────────┘ └──────────┘ └──────┬──────┘ │
│ Cloud or Local ┌────┴────┐ │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ AI-Bridge │ │ AI-Bridge │ │
│ │ Instance 1 │ │ Instance 2 │ │
│ │ (MCP Server) │ │ (MCP Server) │ │
│ └───┬──────┬───┘ └───┬──────┬───┘ │
│ │ ┌────────────────┐ │ │
│ │ │ Shared Storage │ │ │
│ │ │ (/secrets │ │ │
│ │ │ and /clients │ │ │
│ │ │ directories) │ │ │
│ │ └────────────────┘ │ │
│ │ │ │
│ └────────────┬─────────────┘ │
│ │ │
│ ┌─────┴─────┐ │
│ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ │
│ │ CUCM │ │ IMP │ │
│ └──────────┘ └──────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
Supported Products & Versions¶
AI-Bridge for Cisco UC currently supports the following Cisco UC products:
| Product | Full Name | Multi-Cluster | Query Protocols | Supported Versions |
|---|---|---|---|---|
| CUCM | Cisco Unified Communications Manager | ✅ | AXL/SOAP RIS SSH |
14 15 |
| IMP | Cisco IM & Presence Service | ✅ | AXL/SOAP SSH |
14 15 |
Multi-cluster support: the server can manage credentials and execute operations against multiple independent clusters simultaneously.
Protocol details:
- AXL (Administrative XML Layer) — SOAP-based API for CUCM and IMP administration. Supports all standard AXL operations (
get,list,add,update,remove) as well as raw SQL queries (executeSQLQuery,executeSQLUpdate). - RIS (Real-time Information Service) — RisPort70 SOAP interface for querying device registration status on CUCM (phones, gateways, trunks, media resources).
- SSH — Secure Shell access to the Cisco VOS (Voice Operating System) CLI for platform-level commands (
show,utils,file).
Add-ons Compatibility Matrix¶
AI-Bridge for Cisco UC supports a modular add-on system. Add-ons are AI-guided workflows (MCP prompts) that leverage the server's tools and embedded reference resources to perform complex multi-step operations.
| Add-on | Description | CUCM | IMP | Status |
|---|---|---|---|---|
| Security Audit | Automated configuration security audit based on Cisco Security Guide Release 15. Report with PDF export. | ✅ | ✅ | GA |
| Health Check | System health verification | 🔜 | 🔜 | Planned |
| Best Practices | Configuration compliance validation against Cisco and industry best practices. | 🔜 | 🔜 | Planned |
| Troubleshooting | AI-powered diagnostic assistance | 🔜 | 🔜 | Planned |
| Certificate Renewal | Automated certificate lifecycle management: inventory, expiry monitoring, CSR generation, renewal workflow. | 🔜 | 🔜 | Planned |
| Upgrade | Upgrade planning: version compatibility checks, pre-upgrade audit, COP file management, scheduling. | 🔜 | 🔜 | Planned |
Built-in modules:
| Module | Description |
|---|---|
| Reports | Markdown report generation with 9 chart types (pie, bar, donut, radar, gauge, treemap, grouped bars, waterfall, severity matrix) and PDF export via WeasyPrint. |
| Infra | HTTP endpoints for health check, Prometheus metrics, server status, and OAuth token management. |
| License Verification | RS256-signed JWT license verified at startup and monitored periodically by a background watchdog. |
| Automatic Backups | Periodic encrypted backups (RSA-4096 + AES-256-GCM) with local retention, optional SFTP export, and interactive restore. |
| Packaged-Upgrades | Signed package-based upgrade system with --dry-run preview, .env key merge, and automatic pre-upgrade backup. |
Standards & RFC Compliance Summary¶
AI-Bridge for Cisco UC implements a comprehensive set of industry standards across its security, authentication, cryptography, and transport layers, including:
- OAuth 2.0 / 2.1 — RFC 6749 (Authorization Framework), RFC 6750 (Bearer Tokens), RFC 7009 (Token Revocation), RFC 7617 (HTTP Basic Auth), RFC 8414 (Server Metadata Discovery), RFC 9068 (JWT Access Tokens), RFC 9700 / BCP 212 (Security Best Practices)
- JWT & Cryptography — RFC 7519 (JWT), RFC 7518 (JWA / RS256), RFC 8017 (RSA-PSS & RSA-OAEP), RFC 2898 / RFC 8018 (PBKDF2), NIST FIPS 180-4 (SHA-256), NIST SP 800-38D (AES-256-GCM)
- TLS & HTTP Security — RFC 5280 (X.509), RFC 8446 / RFC 5246 (TLS 1.3 / 1.2), RFC 9110 (HTTP Semantics), RFC 6585 (HTTP 429)
- Logging & Integrity — RFC 8259 (JSON), RFC 5424 (Syslog Levels), CWE-117 (Log Injection Prevention), RFC 4251–4254 (SSH/SFTP)
For the complete compliance matrix with implementation details, see the Reference page.
Supported Versions & End-of-Life Policy¶
AI-Bridge for Cisco UC follows a calendar-based versioning scheme: vYYYYMM (e.g., v202604 for the April 2026 release).
Current release status:
| Release | Status | End of Life |
|---|---|---|
| v202604 | ✅ GA (General Availability) | TBD |
| v202605 | 🔜 Alpha (Next) | TBD |
Support policy:
- GA releases receive security patches, bug fixes, and compatibility updates.
- End of Life (EOL) dates are announced at least 12 months in advance.
- Only the latest GA release is actively supported. Customers are encouraged to upgrade promptly using the built-in upgrade system.
- License validity is version-agnostic — a valid license continues to work across upgrades.
For feature requests, bug reports, or EOL inquiries, contact via email.
Architecture & Design¶
High-Level Architecture Diagram¶
The following diagram illustrates the full internal architecture of AI-Bridge for Cisco UC, from the AI agent connection through the security layers down to the Cisco UC backends:
┌──────────────────────────────────────────────────────────────────────────────────────────────┐
│ AI Agent (MCP Client) │
│ Claude Desktop / GitHub Copilot / Cursor / Custom │
└────────────────────────────────────────────┬─────────────────────────────────────────────────┘
│
│
┌──────────────────────────────────────────────────────────────────────────────────────────────┐
│ WEB Reverse-Proxy │
│ (optional) │
└────────────────────────────────────────────┬─────────────────────────────────────────────────┘
│
│ MCP over Streamable HTTP (HTTPS)
▼
┌──────────────────────────────────────────────────────────────────────────────────────────────┐
│ AI-Bridge for Cisco UC (MCP Server) │
│ │
│ ┌──────────┐ ┌────────────────────────────────────────────────────────────────┐ ┌──────────┐ │
│ │ │ │ Transport & Security Layer │ │ │ │
│ │ AUDIT │ │ TLS 1.2+ │ DNS Rebinding │ Host/Origin/Content-Type │ │ Watch- │ │
│ │ │ └────────────────────────────────────────────────────────────────┘ │ dogs │ │
│ │MIDDLEWARE│ ┌────────────────────────────────────────────────────────────────┐ │ │ │
│ │ │ │ Authentication & Authorization │ │──────────│ │
│ │ → │ │ JWT (RS256) │ OAuth 2.1 │ RBAC Profiles │ Rate Limit │ Fail2Ban│ │ │ │
│ │ │ └────────────────────────────────────────────────────────────────┘ │ License │ │
│ │ app.log │ │ │ │
│ │ audit.log│ ┌───────────────┬───────────────┬───────────────┬───────────────┐ │ Integrity│ │
│ │ │ │ │ │ │ │ │ │ │
│ │ │ │ CUCM Module │ IMP Module │ Common Module │ Infra Module │ │ Backup │ │
│ │ │ │ │ │ │ │ │ │ │
│ │ │ │ │ │ Reports │ HTTP Routes │ │ │ │
│ │ │ │ │ │ Charts │ /health │ │ │ │
│ │ │ │ │ │ PDF Export │ /metrics │ │ │ │
│ │ │ │ │ │ │ /status │ │ │ │
│ │ │ │ │ │ │ /token │ │ │ │
│ │ │ │ │ │ │ /revoke │ │ │ │
│ └──────────┘ └──────┬────────┴──────┬────────┴───────────────┴───────────────┘ └────┬─────┘ │
│ │ │ │ │
└─────────────────────┼───────────────┼────────────────────────────────────────────────┼───────┘
│ │ │
│ │ │
│ SSH/HTTPS │ SSH/HTTPS │ SFTP
▼ ▼ ▼
┌────────────┐ ┌────────────┐ ┌────────────┐
│ CUCM │ │ IMP │ │ SFTP │
│ AXL/SOAP │ │ AXL/SOAP │ │ Server │
│ RIS/SOAP │ │ SSH │ │ │
│ SSH │ │ │ │ │
└────────────┘ └────────────┘ └────────────┘
MCP Protocol & Streamable HTTP Transport¶
AI-Bridge for Cisco UC implements the Model Context Protocol (MCP) — an open standard for connecting AI agents to external tools and data sources. The server uses the Streamable HTTP transport, which operates over standard HTTPS.
How it works:
- The AI agent sends an HTTP POST request to the MCP endpoint (e.g.,
https://host:port/mcp/). - The server authenticates the request via the
Authorization: Bearer <token>header (JWT or OAuth 2.1 access token). - The MCP protocol payload contains the requested operation: tool call, prompt retrieval, or resource read.
- The server executes the operation, enforces RBAC, and returns a structured MCP response.
- For long-running operations, the server uses Server-Sent Events (SSE) streaming within the HTTP response.
Key properties:
| Property | Value |
|---|---|
| Transport | Streamable HTTP (configurable via MCP_SERVER_TRANSPORT) |
| Protocol | HTTPS (TLS 1.2+ mandatory) |
| Authentication | Bearer token (JWT RS256 or OAuth 2.1) |
| Content-Type | application/json |
| Endpoint path | Configurable via MCP_SERVER_URL_PATH (default: /mcp/) |
| Host / Port | Configurable via MCP_SERVER_HOST / MCP_SERVER_PORT |
FastMCP Server Structure¶
AI-Bridge for Cisco UC is built on top of FastMCP (fastmcp Python library), which provides the MCP protocol implementation, tool registration, prompt handling, resource serving, and Uvicorn-based ASGI server.
Mount-based modular architecture:
Product modules (CUCM, IMP, ...) are mounted as independent FastMCP sub-servers using namespaces. Each module registers its own tools, prompts, and resources, which are then exposed under a namespace prefix:
This design ensures:
- Namespace isolation — tool names, resource URIs, and prompt names are prefixed with the module namespace (e.g.,
cucm_,imp_,common_,infra_). - Conditional loading — product modules are mounted only if the license entitles them and is not expired.
- Independent development — each module has its own
tools.py,prompts.py,resources.py, andlib.py.
ASGI middleware chain:
Requests flow through the following middleware stack before reaching MCP handlers:
- TransportSecurityASGIMiddleware — DNS rebinding protection, Host/Origin validation (optional,
.env-configurable). - Uvicorn TLS — TLS termination with the configured certificate.
- AuditLoggingMiddleware — Logs all MCP tool invocations to
audit.log. - AuditingJWTVerifier — JWT signature verification, client resolution, RBAC profile enforcement.
Product Module Architecture¶
Each product module (CUCM, IMP, CUC) follows a standardized structure under servers/<product>/:
servers/<product>/
├── __init__.py # Exports: <product>_tools, <product>_resources, <product>_prompts, ...
├── tools.py # MCP tool definitions (@mcp.tool decorated functions)
├── prompts.py # MCP prompt definitions (guided workflows)
├── prompts_custom.py # Custom per-client prompts (loaded from clients/<name>/custom/)
├── prompts_security.py # Security audit prompt (add-on)
├── resources.py # MCP resource definitions (embedded reference documents)
├── lib.py # Module-specific helpers (AXL session management, SSH, etc.)
├── axl-schemas/ # AXL WSDL/XSD per CUCM version (14.0, 15.0)
├── ris-schemas/ # RIS WSDL (CUCM only)
└── resources/ # Embedded reference documents (CLI guide, security guide chapters)
Tool registration pattern:
Each tool is a Python async function decorated with @mcp.tool(), with Pydantic-validated input parameters.
Protocol adapters (in lib.py per module):
- AXL — Uses
zeep(SOAP client) with dynamically loaded WSDL/XSD schemas matching the target CUCM/IMP version. - RIS — Uses
zeepwith the RisPort70 WSDL for real-time device registration queries (CUCM only). - SSH — Uses
paramikofor VOS CLI command execution with trust-on-first-use fingerprint verification.
Library Layer Overview¶
The lib/ directory contains all shared, cross-cutting infrastructure code used by the main server and all product modules. It includes 25+ self-contained Python modules covering: authentication, cryptography, credential management, TLS, licensing, integrity verification, backup, rate limiting, logging, input validation, and more.
Each library module has a single responsibility and is documented independently. For the complete list with descriptions, see the Reference page.
Startup Sequence¶
When the server starts (python ai-bridge-for-cisco-uc.py), the following steps execute in strict order. Any failure at a critical step aborts the startup.
| Step | Action |
|---|---|
| 1 | Create secrets/ directory |
| 2 | Initialize logging |
| 3 | File integrity verification |
| 4 | TLS certificate resolution (self-signed or CA-signed) |
| 5 | License verification |
| 6 | Client synchronization |
| 7 | Configure authentication verifier |
| 8 | Create MCP instance |
| 9 | Mount common module |
| 10 | Mount product modules; CUCM, IMP, ... (if licensed) |
| 11 | Start License Watchdog thread |
| 12 | Start Integrity Watchdog thread |
| 13 | Start Backup Watchdog thread |
| 14 | Mount infra module |
| 15 | Configure transport security middleware |
| 16 | Start HTTPS ASGI server |
Watchdog Subsystems¶
AI-Bridge runs three independent background watchdog threads that monitor the system continuously after startup:
| Watchdog | Default Interval | Trigger Action on Failure | Configuration Keys |
|---|---|---|---|
| License Watchdog | 24 hours | SIGTERM → graceful shutdown (license expired) |
Interval embedded in license payload |
| Integrity Watchdog | 24 hours | SIGTERM → graceful shutdown (tampered files) |
INTEGRITY_CHECK_INTERVAL_HOURS |
| Backup Watchdog | 24 hours | Log error, continue running | BACKUP_INTERVAL_HOURS, BACKUP_ENABLED |
License Watchdog — Periodically re-verifies the license file. If the license transitions from GRACE to EXPIRED, it sends SIGTERM to the process, triggering a graceful shutdown.
Integrity Watchdog — Re-runs the SHA-256 manifest verification and RSA-PSS signature check. If any source file has been modified since startup, the server is terminated immediately. This detects runtime tampering.
Backup Watchdog — Creates encrypted backup archives (RSA-4096 + AES-256-GCM) at the startup then at the configured interval. Backups include client data, secrets, configuration, and logs. Optionally exports to an SFTP server. Non-critical — failures are logged but do not stop the server.
All watchdogs are stopped cleanly during graceful shutdown via atexit and SIGTERM handlers.
Project Directory Structure¶
AI-Bridge-for-Cisco-UC/
├── ai-bridge-for-cisco-uc.py # Main entry point — server startup, module mounting
├── .env # Environment configuration (not in repo — generated by setup wizard)
├── manifest.json # SHA-256 hashes of all source files
├── manifest.sig # RSA-PSS signature of manifest.json
├── pyproject.toml # Project metadata, Ruff configuration
├── requirements.txt # Runtime Python dependencies
├── requirements-dev.txt # Development dependencies (pytest, ruff, pip-audit, ...)
├── LICENSE # Proprietary license text
├── CHANGELOG.md # Version history
├── SECURITY.md # Vulnerability reporting policy
├── README.md # Project overview
│
├── lib/ # Shared library layer
│ ├── auth.py # JWT verifier, RBAC enforcement
│ ├── backup.py # Encrypted backup engine + watchdog
│ ├── credentials.py # Per-client credential encryption
│ ├── crypto.py # Fernet key derivation, encryption helpers
│ ├── integrity.py # Manifest verification + watchdog
│ ├── license.py # License verification + watchdog
│ ├── tls.py # TLS certificate management
│ ├── ... # (25+ modules — see Reference)
│ └── editor_public.pem # Editor's RSA public key (manifest signature verification)
│
├── servers/ # Product modules (MCP sub-servers)
│ ├── cucm/ # CUCM module — tools, prompts, resources, AXL/RIS schemas
│ ├── imp/ # IMP module — tools, prompts, resources, AXL schemas
│ ├── cuc/ # CUC module (planned) — resources only
│ ├── common/ # Common module — report tools, charts, PDF export
│ └── infra/ # Infra module — HTTP routes (/health, /metrics, /status, OAuth)
│
├── profiles/ # RBAC profile definitions (JSON)
│ ├── admin.json # Full access
│ ├── operator.json # Read-only + limited write
│ └── auditor.json # Read-only, audit-focused
│
├── clients/ # Per-client isolated data directories
│ ├── _default/ # Template for new clients
│ │ └── custom/ # Custom prompt templates
│ └── <client_name>/ # One directory per AUTH_CLIENTS entry
│ ├── secrets/ # Encrypted credentials, client-specific keys
│ ├── reports/ # Generated reports (Markdown, PDF)
│ └── custom/ # Custom per-client prompt files
│
├── secrets/ # Server-level secrets (mode 0700)
│ ├── rsa_private.pem # RSA-4096 private key (JWT signing, backup encryption)
│ ├── rsa_public.pem # RSA-4096 public key (JWT verification)
│ ├── license.jwt # License file (RS256-signed JWT)
│ ├── server-ca-signed.crt # CA-signed TLS certificate (optional)
│ ├── server-ca-signed.key # CA-signed TLS private key (optional)
│ └── token_blacklist.json # Persistent revoked token JTI list
│
├── certs-trust-store/ # Custom CA certificates for Cisco UC HTTPS verification
├── backups/ # Encrypted backup archives (.enc + .sha256 sidecar)
├── logs/ # Log files (app.log, audit.log)
├── scripts/ # Administrative CLI scripts
│ ├── backup_restore.py # Interactive backup restore
│ ├── rotate_rsa_keys.py # RSA key rotation
│ ├── show_tech.py # Support bundle generation
│ ├── update_manifest.py # Manifest regeneration
│ ├── export_mcp_definitions.py # Export all MCP tool/prompt/resource definitions
│ └── ... # Other utilities
│
├── tests/ # Test suite
│ ├── conftest.py # Shared pytest fixtures
│ ├── unit/ # Unit tests
│ └── integration/ # Integration tests (live UC equipment)
│
├── upgrade/ # Upgrade staging directory
└── docs/
└── admin-guide.md # Full administration guide