Reference¶
Last update: June 4, 2026
This page is the comprehensive technical reference for AI-Bridge for Cisco UC — MCP tools, prompts, resources, HTTP endpoints, audit log events, error types, standards compliance, and glossary.
MCP Tools Reference¶
All tools use the namespace prefix of their module. The AI agent's RBAC profile determines which tools are accessible. Tools not permitted by the active profile return a ProfilePermissionError.
CUCM Module¶
| Tool | Description | Minimum Profile |
|---|---|---|
cucm_store_credentials |
Store CUCM AXL (HTTPS/REST) credentials for a host | admin, operator |
cucm_os_store_credentials |
Store OS Admin CLI (SSH) credentials for a CUCM host | admin, operator |
cucm_update_credentials |
Update CUCM AXL credentials for a host | admin, operator |
cucm_os_update_credentials |
Update OS Admin CLI credentials for a CUCM host | admin, operator |
cucm_delete_credentials |
Delete CUCM AXL credentials for a host | admin |
cucm_os_delete_credentials |
Delete OS Admin CLI credentials for a CUCM host | admin |
cucm_os_trust_fingerprint |
Trust or reject the SSH host fingerprint for a CUCM node | admin |
cucm_list_credentials |
List configured CUCM hosts (AXL + OS + phone) for the current client | admin, operator, auditor |
cucm_get_version |
Get the CUCM version of a node (via AXL) | admin, operator, auditor |
cucm_list_axl_operations |
Introspect the AXL WSDL — list available SOAP operations, optionally filtered | admin, operator, auditor |
cucm_axl_call |
Execute an AXL SOAP operation (get, list, add, update, remove, do, SQL, …) |
Per profile AXL allowlist |
cucm_download_axl_toolkit |
Download AXL WSDL/XSD schemas from a CUCM node into the local schemas cache | admin |
cucm_download_ris_toolkit |
Download RIS WSDL schemas from a CUCM node into the local schemas cache | admin |
cucm_risport_query |
Query real-time device registration status via RIS (RisPort70) | Per profile RIS allowlist |
cucm_os_run_command |
Execute a VOS CLI command via SSH on a CUCM node | Per profile SSH allowlist |
cucm_check_connectivity |
Check AXL, RIS and SSH connectivity to a CUCM host — returns per-service latency | admin, operator, auditor |
cucm_phone_store_credentials |
Store phone web access credentials (HTTP Basic) for screenshot capture | admin, operator |
cucm_phone_update_credentials |
Update phone web access credentials | admin, operator |
cucm_phone_delete_credentials |
Delete phone web access credentials | admin |
cucm_phone_screenshot |
Capture a screenshot from a Cisco IP Phone display (returns PNG) | admin, operator, auditor |
AXL / RIS schema management
cucm_download_axl_toolkit and cucm_download_ris_toolkit pull WSDL/XSD files directly from the CUCM publisher. Schemas must be downloaded before the corresponding AXL or RIS operations can be used for that CUCM version.
IMP Module¶
| Tool | Description | Minimum Profile |
|---|---|---|
imp_store_credentials |
Store IMP AXL (HTTPS/REST) credentials for a host | admin, operator |
imp_os_store_credentials |
Store OS Admin CLI (SSH) credentials for an IMP host | admin, operator |
imp_update_credentials |
Update IMP AXL credentials for a host | admin, operator |
imp_os_update_credentials |
Update OS Admin CLI credentials for an IMP host | admin, operator |
imp_delete_credentials |
Delete IMP AXL credentials for a host | admin |
imp_os_delete_credentials |
Delete OS Admin CLI credentials for an IMP host | admin |
imp_os_trust_fingerprint |
Trust or reject the SSH host fingerprint for an IMP node | admin |
imp_list_credentials |
List configured IMP hosts (AXL + OS) for the current client | admin, operator, auditor |
imp_get_version |
Get the IMP version of a node (via AXL) | admin, operator, auditor |
imp_list_axl_operations |
Introspect the AXL WSDL — list available SOAP operations, optionally filtered | admin, operator, auditor |
imp_axl_call |
Execute an AXL SOAP operation | Per profile AXL allowlist |
imp_download_axl_toolkit |
Download AXL WSDL/XSD schemas from an IMP node into the local schemas cache | admin |
imp_os_run_command |
Execute a VOS CLI command via SSH on an IMP node | Per profile SSH allowlist |
imp_check_connectivity |
Check AXL and SSH connectivity to an IMP host — returns per-service latency | admin, operator, auditor |
CUC Module¶
| Tool | Description | Minimum Profile |
|---|---|---|
cuc_store_credentials |
Store CUPI (REST) credentials for a CUC host | admin, operator |
cuc_os_store_credentials |
Store OS Admin CLI (SSH) credentials for a CUC host | admin, operator |
cuc_update_credentials |
Update CUPI credentials for a CUC host | admin, operator |
cuc_os_update_credentials |
Update OS Admin CLI credentials for a CUC host | admin, operator |
cuc_delete_credentials |
Delete CUPI credentials for a CUC host | admin |
cuc_os_delete_credentials |
Delete OS Admin CLI credentials for a CUC host | admin |
cuc_os_trust_fingerprint |
Trust or reject the SSH host fingerprint for a CUC node | admin |
cuc_list_credentials |
List configured CUC hosts (CUPI + OS) for the current client | admin, operator, auditor |
cuc_get_version |
Get CUC product version via GET /vmrest/version/product |
admin, operator, auditor |
cuc_cupi_list |
Paginated CUPI listing — GET /vmrest/<resource> with optional query/sort/page |
Per profile CUPI allowlist |
cuc_cupi_call |
Arbitrary CUPI REST call (GET / POST / PUT / DELETE under /vmrest/) |
Per profile CUPI allowlist |
cuc_os_run_command |
Execute a VOS CLI command via SSH on a CUC node | Per profile SSH allowlist |
cuc_check_connectivity |
Check CUPI and SSH connectivity to a CUC host — returns per-service latency | admin, operator, auditor |
CUPI vs AXL
Cisco Unity Connection does not expose AXL/SOAP. All provisioning and read
operations go through CUPI (Cisco Unity Provisioning Interface, REST at
https://<host>:8443/vmrest/). There is no WSDL toolkit to download and no
cluster abstraction — credentials and operations are managed per host.
Common Module¶
| Tool | Description |
|---|---|
common_write_report |
Write content to a Markdown report. Modes: create, append, overwrite, resume, insert_after |
common_read_report |
Read report content (chunked for large files) |
common_export_report_pdf |
Export a Markdown report to PDF via WeasyPrint |
Report modes
create— fails if file exists; prevents accidental overwriteappend— adds content at the end of an existing fileoverwrite— replaces file content entirelyresume— resumes an in-progress report from the last written sectioninsert_after— inserts content after a specified anchor section
Infra Module¶
These tools are available regardless of license tier and require only a valid Bearer token.
| Tool | Description |
|---|---|
infra_init_session |
MANDATORY first call — returns the full tool/prompt catalogue and the client's effective RBAC matrix |
infra_health |
Liveness/readiness probe — status, ready, license state, server name, uptime |
infra_metrics |
Raw Prometheus metrics (counters, gauges, histograms) for the MCP server |
infra_server_status |
Full server status — server, license, backup, requests (per-category counters), security (TLS, OAuth) |
infra_list_available_products |
Licensed products vs. the calling client's product scope (and the out-of-scope diff) |
infra_get_my_permissions |
Authoritative RBAC matrix for the calling client (per product / per service allowlists & rate limits) |
infra_list_prompts |
List all available prompts (filtered by RBAC product scope) |
infra_get_prompt |
Retrieve the full content of a prompt by name |
infra_list_docs |
List all available MCP resources/docs (filtered by RBAC product scope) |
infra_get_doc |
Retrieve the full content of a doc/resource by name |
Prompt and doc tools for non-prompt clients
Most MCP clients do not support the native prompts/list / prompts/get or resources/list / resources/read capabilities.
The infra_list_prompts / infra_get_prompt and infra_list_docs / infra_get_doc tools provide the same content via standard MCP tools,
ensuring all clients can access procedures, audit workflows and reference guides regardless of their native capability support.
MCP Prompts Reference¶
Prompts are guided multistep workflows. The AI agent loads a prompt and follows its instructions, autonomously calling tools and consulting resources to complete the workflow.
| Prompt | Module | Description |
|---|---|---|
cucm_security_audit |
CUCM | Automated CUCM security audit based on the Cisco Security Guide Release 15. Executes a structured sequence of AXL queries, SSH commands, and RIS checks. Produces a Markdown report with PDF export. |
imp_security_audit |
IMP | Equivalent security audit workflow for IMP nodes. Covers IM & Presence-specific security controls and Cisco hardening guidance. |
cuc_security_audit |
CUC | Cisco Unity Connection security audit covering VOS hardening, CUPI/REST exposure, voicemail security and TLS/certificate posture. Produces a Markdown report with PDF export. |
Prompt requirements
Security audit prompts require an admin or auditor profile. They invoke multiple tools in sequence — ensure the profile's rate limits accommodate the full audit workload.
Prompt compatibility
All prompts listed above are also accessible via the infra_list_prompts and infra_get_prompt tools for MCP clients that do not support native prompts (Cursor, Continue, Copilot, etc.).
MCP Resources Reference¶
Resources are embedded read-only reference documents that the AI agent can consult during tool-calling workflows. They are served via the MCP resource protocol.
CUCM Resources:
| URI Pattern | Content |
|---|---|
cucm://cli-guide/* |
Cisco CUCM VOS CLI command reference |
cucm://security-guide/* |
Cisco CUCM Security Guide chapters (Release 15) |
IMP Resources:
| URI Pattern | Content |
|---|---|
imp://cli-guide/* |
Cisco IMP VOS CLI command reference |
imp://security-guide/* |
Cisco IMP Security Guide chapters |
CUC Resources:
| URI Pattern | Content |
|---|---|
cuc://cli-guide-readonly/* |
Cisco CUC VOS CLI command reference (show/utils/file/run/set/unset/delete/license) |
cuc://cupi/reference |
CUPI REST endpoint catalogue — verbs, payloads, pagination, examples (CUC 14 & 15) |
cuc://security-guide/* |
Cisco CUC Security Guide chapters (Release 15) (when packaged) |
HTTP Endpoints Reference¶
| Method | Endpoint | Auth Required | Description |
|---|---|---|---|
GET |
/health |
None | Liveness probe — returns ok |
GET |
/metrics |
None | Prometheus metrics |
GET |
/status |
Bearer | Server status JSON |
GET |
/authorize |
None | OAuth 2.1 authorization endpoint — serves login page (RFC 6749 §3.1, RFC 7636 PKCE) |
POST |
/authorize |
None | OAuth 2.1 authorization endpoint — processes login form, redirects with auth code |
POST |
/token |
None | OAuth 2.1 token issuance — authorization_code (PKCE) or client_credentials grant |
POST |
/revoke |
Bearer | Token revocation (RFC 7009) |
GET |
/.well-known/oauth-authorization-server |
None | OAuth 2.0 Authorization Server Metadata (RFC 8414) |
GET |
/.well-known/oauth-protected-resource |
None | OAuth 2.0 Protected Resource Metadata (RFC 9728) |
GET |
/.well-known/oauth-protected-resource/mcp |
None | OAuth 2.0 Protected Resource Metadata — MCP path variant (RFC 9728) |
POST / GET / DELETE |
/mcp/ |
Bearer | MCP protocol endpoint (Streamable HTTP transport) |
MCP endpoint methods
The /mcp/ endpoint accepts POST (send message), GET (open SSE stream), and DELETE (close session) as defined by the MCP Streamable HTTP transport specification.
Audit Log Event Reference¶
Audit log format: one JSON object per line in logs/audit.log.
Common Fields¶
Every audit event contains these fields:
| Field | Description |
|---|---|
timestamp |
ISO 8601 UTC timestamp |
event |
Event category (AUTH, ACTIONS, CREDENTIAL, etc.) |
client |
Client name (if identified at time of event) |
ip |
Source IP address |
status |
Event outcome — see category tables below |
AUTH Events¶
status Value |
Meaning |
|---|---|
AUTH_OK |
Successful authentication |
AUTH_FAILED |
Invalid token or bad credentials |
AUTH_REVOKED |
Token has been explicitly revoked |
AUTH_EXPIRED |
Token has passed its expiry time |
IP_BLACKLISTED |
IP address added to Fail2Ban blacklist |
AUTH_BLOCKED |
Request rejected — source IP is blacklisted |
IP_RELEASED |
Blacklist entry expired; IP unblocked |
ACTIONS Events¶
Every MCP tool call is logged with:
| Field | Value |
|---|---|
client |
Client name |
tool_name |
Full tool name (e.g., cucm_axl_call) |
product |
Target product (cucm, imp, cuc, common, infra) |
host |
Target Cisco UC node hostname or IP (if applicable) |
result |
ALLOWED / DENIED / RATE_LIMITED / ERROR |
exec_time_ms |
Execution time in milliseconds |
CREDENTIAL Events¶
Logged for every store / update / delete credential operation:
| Field | Value |
|---|---|
operation |
store / update / delete |
client |
Client performing the operation |
product |
Target product |
cluster |
Cluster name |
TRUSTED Events¶
Logged for every SSH host fingerprint decision:
| Field | Value |
|---|---|
action |
trusted / rejected |
host |
Target node hostname |
fingerprint |
SHA-256 fingerprint of the host key |
client |
Client making the trust decision |
SERVER Events¶
| Condition | Logged |
|---|---|
| Startup complete | Version, loaded modules, client count |
| Shutdown initiated | Source signal (SIGTERM / SIGINT) |
| License state change | Previous state → new state, expiry date |
| Integrity check result | Pass / fail with affected file list |
TRANSPORT Events¶
| Condition | Logged |
|---|---|
| DNS rebinding attempt | Invalid Host header value, source IP |
Invalid Origin header |
Header value, source IP |
| TLS alert | Alert type, source IP |
Error Types Reference¶
| Error | HTTP Status | Meaning |
|---|---|---|
AUTH_FAILED |
401 | Invalid, unrecognized, or malformed token |
AUTH_REVOKED |
401 | Token has been explicitly revoked via /revoke |
AUTH_EXPIRED |
401 | Token has passed its expiry time |
AUTH_BLOCKED |
429 | Source IP is currently blacklisted by Fail2Ban |
RATE_LIMITED |
429 | Per-client rate limit exceeded for this product/service — retry after N seconds |
ProfilePermissionError |
403 | Operation not permitted by the client's RBAC profile |
ConfigError |
500 | .env configuration error detected at startup |
LicenseError |
503 | License invalid or expired — product modules unavailable |
CredentialError |
400 | Credential store error (not found, decryption failure) |
ConnectivityError |
400 | Cannot reach the target Cisco UC node (timeout, refused) |
AXLError |
400 | AXL SOAP operation returned a fault from Cisco UC |
SSHError |
400 | SSH command failed or connection was refused |
RISError |
400 | RIS query returned an error from Cisco UC |
CUPIError |
400 | CUPI REST call returned a non-2xx response from Cisco Unity Connection |
IntegrityError |
500 | Software integrity check failed — tampered file detected |
Rate limit retry
On a RATE_LIMITED (HTTP 429) response, the Retry-After header indicates the number of seconds to wait before retrying.
Standards & RFC Compliance¶
| Standard | Coverage |
|---|---|
| RFC 6749 | OAuth 2.0 Authorization Framework (client_credentials and authorization_code grants) |
| RFC 7636 | Proof Key for Code Exchange (PKCE) — S256 code challenge method |
| RFC 6750 | Bearer Token Usage in HTTP requests |
| RFC 7009 | OAuth 2.0 Token Revocation |
| RFC 7519 | JSON Web Tokens (JWT) |
| RFC 7518 | JSON Web Algorithms (JWA) — RS256 signing algorithm |
| RFC 7617 | HTTP Basic Authentication |
| RFC 8017 | RSA-PSS signing & RSA-OAEP encryption (PKCS#1 v2.2) |
| RFC 8414 | OAuth 2.0 Authorization Server Metadata |
| RFC 9728 | OAuth 2.0 Protected Resource Metadata |
| RFC 9068 | JWT Profile for OAuth 2.0 Access Tokens |
| RFC 8018 | PBKDF2 — Password-Based Key Derivation Function 2 |
| RFC 8446 / 5246 | TLS 1.3 / TLS 1.2 |
| RFC 5280 | X.509 Certificate and CRL Profile |
| RFC 9110 | HTTP Semantics |
| RFC 6585 | HTTP 429 Too Many Requests |
| RFC 4251–4254 | SSH Protocol Architecture, Transport, Authentication, Connection |
| RFC 8259 | JSON |
| NIST SP 800-132 | PBKDF2 — 600,000 iterations, SHA-512 |
| NIST SP 800-38D | AES-256-GCM authenticated encryption |
| NIST FIPS 180-4 | SHA-256 / SHA-512 hash algorithms |
| OWASP Top 10 | Input validation, transport security, injection prevention |
| CWE-117 | Log injection prevention in structured log output |
Scripts Reference¶
Standalone scripts in scripts/. Run from the project root with python scripts/<name>.py.
| Script | Description |
|---|---|
backup_restore.py |
Interactive restore from encrypted local or SFTP backup archives |
certificate_generate_csr.py |
Generate a TLS CSR with proper SAN extension; reuses existing private key if present |
encrypt_sftp_password.py |
Encrypt the SFTP backup password for secure storage in .env as BACKUP_SFTP_PASSWORD_ENC |
export_mcp_definitions.py |
Export all MCP tools, prompts, and resources to JSON for static analysis |
license_checker.py |
Decode and display secrets/license.jwt — works without starting the server |
rotate_rsa_keys.py |
Interactive RSA key pair rotation: archives the old key, forces token regeneration at next startup |
show_tech.py |
Collect a diagnostic bundle (logs, config snapshot, status) for support |
update_manifest.py |
Pre-commit hook: regenerate the SHA-512 integrity manifest before each commit |
Test Scripts¶
| Script | Description |
|---|---|
tests_check_mcp_scan.py |
Validate mcp-scanner JSON output against a known false-positive allowlist |
tests_cucm_helper.py |
Internal helper for tests_run.py — isolated subprocess for CUCM operations |
tests_run.py |
Interactive test runner — unit tests, then optionally integration tests |
tests_setup_credentials.py |
Encrypt and store Cisco UC credentials for the pytest integration-test client |
Library Modules Reference¶
Internal modules in lib/. Not meant to be executed directly.
| Module | Description |
|---|---|
audit_middleware.py |
FastMCP middleware that writes a structured audit entry for every MCP tool call |
auth.py |
JWT verifier with audit logging, token expiry check, and fail2ban integration |
auth_clients.py |
Parser and validator for the AUTH_CLIENTS environment variable |
auth_rate_limiter.py |
Sliding-window fail2ban: temporary IP blacklist after repeated authentication failures |
backup.py |
Periodic encrypted backup watchdog — AES-256-GCM archive + RSA-4096 OAEP key wrapping |
credentials.py |
Fernet-based per-client credential encryption/decryption with PBKDF2-derived keys |
crypto.py |
Server salt management and per-client PBKDF2 key derivation for Fernet encryption |
env_variables.py |
.env loader and typed configuration accessors used across all modules |
exceptions.py |
Custom exception classes (ConfigError, LicenseError, IntegrityError, …) |
integrity.py |
SHA-512 manifest verification against the RSA-PSS signed manifest.json |
license.py |
JWT-based license verification: hostname binding, expiry, grace period, product scope |
log_setup.py |
Rotating file logger + optional colored console handler (configurable via .env) |
metrics.py |
Prometheus metrics definitions — counters, gauges, and histograms for all subsystems |
oauth.py |
OAuth 2.1 server helpers: PKCE auth codes, token issuance, client secret management |
profiles.py |
RBAC profile loading, hot-reload on file change, and per-operation permission evaluation |
rate_limiter.py |
Per-client sliding window rate limiter for AXL, SSH, RIS, and report operations |
retry.py |
Exponential backoff retry decorator for transient network/connection errors |
sanitize.py |
Input sanitization utilities shared across MCP tool handlers |
status_tracker.py |
Thread-safe in-memory stats tracker powering the /status endpoint |
sync_clients.py |
Client lifecycle management at startup: create directories, renew credentials, purge removed clients |
tls.py |
TLS certificate management: self-signed auto-generation, CA-signed loading, mid-life renewal |
token_blacklist.py |
Persisted JWT revocation list — stores revoked jti claims in secrets/token_blacklist.json |
transport_security.py |
ASGI middleware for DNS rebinding protection via Host and Origin header validation |
upgrade.py |
Core upgrade logic: .env merging, file action planning, version comparison |
validators.py |
Pydantic input validation models for all MCP tool parameters |
Glossary¶
| Term | Definition |
|---|---|
| AES-GCM | AES Galois/Counter Mode — authenticated encryption mode providing both confidentiality and integrity |
| ASGI | Asynchronous Server Gateway Interface — Python standard for async web servers and frameworks |
| AXL | Administrative XML Layer — Cisco's SOAP/XML API for UC platform configuration |
| bcrypt | Adaptive password hashing function used for OAuth client secret storage |
| CUC | Cisco Unity Connection — voicemail and unified messaging platform |
| CUCM | Cisco Unified Communications Manager — the primary UC call control and configuration platform |
| CUPI | Cisco Unity Provisioning Interface — REST API exposed by CUC for provisioning and read operations (/vmrest/) |
| Fernet | Symmetric authenticated encryption scheme: AES-128-CBC + HMAC-SHA256 (Python cryptography library) |
| IMP | Cisco IM & Presence Service — XMPP-based instant messaging component of the CUCM suite |
| JWT | JSON Web Token — compact, URL-safe, self-contained token format (RFC 7519) |
| MCP | Model Context Protocol — open standard for AI agent ↔ tool server communication, maintained by Anthropic |
| PBKDF2 | Password-Based Key Derivation Function 2 — NIST-recommended key stretching algorithm (RFC 8018) |
| RBAC | Role-Based Access Control — permission model where access is governed by predefined roles |
| RIS | Real-time Information Service — Cisco API for querying live device registration status |
| RS256 | RSA Signature with SHA-256 — JWT signing algorithm (RFC 7518) |
| RSA-OAEP | RSA Optimal Asymmetric Encryption Padding — modern RSA encryption scheme (PKCS#1 v2.2, RFC 8017) |
| RSA-PSS | RSA Probabilistic Signature Scheme — modern RSA signature padding (PKCS#1 v2.2, RFC 8017) |
| SAN | Subject Alternative Name — X.509 certificate extension for binding multiple hostnames/IPs to a single certificate |
| SFTP | SSH File Transfer Protocol — secure file transfer protocol operating over an SSH connection |
| TOFU | Trust On First Use — SSH host key trust model: fingerprint is trusted on first connection and pinned for subsequent ones |
| VOS | Voice Operating System — Cisco's hardened Linux-based platform OS underlying CUCM, IMP, CUC, and other UC products |
| WSDL | Web Services Description Language — XML format describing the operations and data types of a SOAP web service |