Reference

Last update: October 8, 2026

---

This page is the comprehensive technical reference for Tolk for Cisco UC — MCP tools, prompts, resources, HTTP endpoints, audit log events, error types, standards compliance, scripts, internal modules and glossary.

---

MCP Tools Reference

All tools use the namespace prefix of their module. RBAC is enforced at the operation level (not per tool): AXL, RIS, SSH, CUPI, phone, RoomOS xAPI, Serviceability and report operations are checked against the client's profile allowlists and rate limits, and a denied operation returns a ProfilePermissionError. Credential-management tools (store/update/delete/list) are available to any authenticated client, since each client manages its own set of Cisco UC credentials. A client's product_scope still governs which product modules (CUCM, IMP, CUC) it can see at all.

---

CUCM Module

Tool	Description
cucm_axl_call	Execute an AXL SOAP operation (get, list, add, update, remove, do, SQL, …)
cucm_check_connectivity	Check AXL, RIS and SSH connectivity to a CUCM host — returns per-service latency
cucm_cop_install_list	List the COP file install jobs of the calling client (to resume one)
cucm_cop_install_start	Install COP files one at a time (cluster wide or node by node); cmterm-*: Device Defaults kept or restored
cucm_cop_install_status	Follow a COP install job (resumes after SSH loss / restart) — final ✅/❌ report per node
cucm_cop_precheck	Read-only prechecks: replication, upgrade, disk, version, NTP, DRF, certs, Device Defaults
cucm_delete_credentials	Delete CUCM AXL credentials for a host
cucm_download_axl_toolkit	Download AXL WSDL/XSD schemas from a CUCM node into the local schemas cache
cucm_download_ris_toolkit	Download RIS WSDL schemas from a CUCM node into the local schemas cache
cucm_get_version	Get the CUCM version of a node (via AXL)
cucm_list_axl_operations	Introspect the AXL WSDL — list available SOAP operations, optionally filtered
cucm_list_credentials	List configured CUCM hosts (AXL + OS, + phone / RoomOS when the sub-module is loaded)
cucm_os_delete_credentials	Delete OS Admin CLI credentials for a CUCM host
cucm_os_run_command	Execute a VOS CLI command via SSH on a CUCM node
cucm_os_store_credentials	Store OS Admin CLI (SSH) credentials for a CUCM host
cucm_os_trust_fingerprint	Trust or reject the SSH host fingerprint for a CUCM node
cucm_os_update_credentials	Update OS Admin CLI credentials for a CUCM host
cucm_restart_feature_service	Restart a feature service (e.g. Cisco Tftp) on one node via Serviceability (ControlCenterServices) — platform services: CLI utils service restart
cucm_risport_query	Query real-time registration status (IP, node) of one or several devices via RIS (RisPort70)
cucm_store_credentials	Store CUCM AXL (HTTPS/REST) credentials for a host
cucm_update_credentials	Update CUCM AXL credentials for a host

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.

CUCM sub-module — IP phones (SERVER_CUCM_PHONES_ENABLED)

Loaded when SERVER_CUCM_PHONES_ENABLED='1' (default). Screenshot, web information pages and text message: Cisco IP Phones 88xx / 98xx only, through the phone web server (HTTPS, HTTP Basic); credentials are stored as cucm-phone entries. Firmware upgrade campaigns (78xx / 88xx / 98xx, ATA 19x, wireless 8821 / 840 / 860) go through AXL and RisPort only (CUCM credentials).

Tool	Description
cucm_phone_delete_credentials	Delete phone web access credentials
cucm_phone_screenshot	Capture a screenshot from a Cisco IP Phone display (returns PNG)
cucm_phone_send_message	Push a text message to one or several Cisco IP Phones (88xx/98xx)
cucm_phone_store_credentials	Store phone web access credentials (HTTP Basic)
cucm_phone_update_credentials	Update phone web access credentials
cucm_phone_web_info	Read the phone web information pages, parsed (device, network, ports + CDP/LLDP neighbour, RTP streams, status messages, logs...): one page, a list or all, compact / summary output, UTC time stamps, ITL/CTL trust list audit (optional comparison with CUCM), several phones at once (ip_phones, fleet trust_summary)
cucm_phone_upgrade_campaign_create	Firmware upgrade campaign: read-only inventory (listPhone, RisPort, ITL status per phone, Device Defaults), exclusions, source versions per model, pilot + waves plan, duration estimate (draft)
cucm_phone_upgrade_campaign_start	Start a draft campaign after the user's single confirmation: server-side waves (Phone Load Name + restartPhone) and RisPort monitoring
cucm_phone_upgrade_campaign_status	Campaign progress (waves, counters, attention list) and final report; restarts a lost driver
cucm_phone_upgrade_campaign_control	Suspend / resume / abort a campaign, align Device Defaults, re-check postponed phones
cucm_phone_upgrade_campaign_list	List the phone upgrade campaigns of the current client

CUCM sub-module — RoomOS codecs (SERVER_CUCM_ROOMOS_ENABLED)

Loaded when SERVER_CUCM_ROOMOS_ENABLED='1' (default). Cisco RoomOS devices (Room / Desk / Board / Codec) driven through their xAPI over HTTPS (/getxml for reads, /putxml for writes and commands). Credentials are stored as cucm-roomos entries: one entry on the CUCM host is the cluster default, an entry on a codec IP overrides it for that codec.

Tool	Description
cucm_roomos_store_credentials	Store RoomOS xAPI credentials (host = CUCM node for the cluster default, or codec IP for a per-codec override)
cucm_roomos_update_credentials	Update RoomOS xAPI credentials
cucm_roomos_delete_credentials	Delete RoomOS xAPI credentials
cucm_roomos_xapi_lookup	Search the bundled xAPI reference (RoomOS 26.9.1): paths, parameters, value spaces, roles — no codec access. Mandatory before any write unless a prompt gives the exact command
cucm_roomos_get_info	Codec identity: product, software version, serial number, uptime
cucm_roomos_xstatus	Read an xStatus path (/getxml)
cucm_roomos_xconfiguration_get	Read an xConfiguration path (/getxml)
cucm_roomos_xconfiguration_set	Set one xConfiguration leaf (/putxml)
cucm_roomos_xcommand	Run one xCommand with its parameters (/putxml) — e.g. local phonebook, standby, dial
cucm_roomos_send_message	Display an on-screen message on one or several codecs (UserInterface Message Alert Display)
cucm_roomos_trust_check	ITL / CTL conformity of codecs against their CUCM TFTP node (SHA-1 fingerprints compared, not mere presence) — mandatory before a software upgrade
cucm_roomos_campaign_create	Create a RoomOS software upgrade campaign: persistent per-client journal + server-side monitoring settings (status draft until the single confirmation)
cucm_roomos_campaign_snapshot	Read the campaign codecs (RisPort + /Status + Navigator profile): eligibility, registration, identity, Room Navigator, availability
cucm_roomos_campaign_record	Journal a decision or fact: single confirmation, suspension / resume / closure, device exclusion, previous load, AXL trigger failure, Device Defaults review
cucm_roomos_campaign_start_upgrade	Gate called immediately before updatePhone + applyPhone / restartPhone: re-checks the codec, opens the attempt and starts the server-side monitor
cucm_roomos_campaign_align_load	Align the Phone Load Name of a codec already on target without software deployment (automatic, verified target load, non-blocking; updatePhone + read-back only, no apply / restart, no-restart check)
cucm_roomos_campaign_status	Campaign state, server-side wait for the next monitoring cycle (≤ 50 s), final report rows, device outcome apart from campaign state, next action
cucm_roomos_campaign_list	List the upgrade campaigns of the current client (resume from a new session)

RoomOS xAPI permissions

RoomOS calls are checked against the cucm.roomos section of the client profile: allowed_prefixes (e.g. get Status, get Configuration, set Configuration, Command Phonebook). Sensitive operations (Command SystemUnit FactoryReset, Command SystemUnit SoftwareUpgrade, Command Macros, Command UserManagement, Command Security, Command Provisioning, set Configuration Network, set Configuration Security, …) are shown in the same list but are blocked by default (red tiles): they are never granted by a broader prefix such as Command, only by an explicit entry. Multiline commands (macros, UI extensions, certificates) are not supported.

---

IMP Module

Tool	Description
imp_axl_call	Execute an AXL SOAP operation
imp_check_connectivity	Check AXL and SSH connectivity to an IMP host — returns per-service latency
imp_delete_credentials	Delete IMP AXL credentials for a host
imp_download_axl_toolkit	Download AXL WSDL/XSD schemas from an IMP node into the local schemas cache
imp_get_version	Get the IMP version of a node (via AXL)
imp_list_axl_operations	Introspect the AXL WSDL — list available SOAP operations, optionally filtered
imp_list_credentials	List configured IMP hosts (AXL + OS) for the current client
imp_os_delete_credentials	Delete OS Admin CLI credentials for an IMP host
imp_os_run_command	Execute a VOS CLI command via SSH on an IMP node
imp_os_store_credentials	Store OS Admin CLI (SSH) credentials for an IMP host
imp_os_trust_fingerprint	Trust or reject the SSH host fingerprint for an IMP node
imp_os_update_credentials	Update OS Admin CLI credentials for an IMP host
imp_store_credentials	Store IMP AXL (HTTPS/REST) credentials for a host
imp_update_credentials	Update IMP AXL credentials for a host

---

CUC Module

Tool	Description
cuc_check_connectivity	Check CUPI and SSH connectivity to a CUC host — returns per-service latency
cuc_cupi_call	Arbitrary CUPI REST call (GET / POST / PUT / DELETE under /vmrest/)
cuc_cupi_list	Paginated CUPI listing — GET /vmrest/<resource> with optional query/sort/page
cuc_delete_credentials	Delete CUPI credentials for a CUC host
cuc_get_version	Get CUC product version via GET /vmrest/version/product
cuc_list_credentials	List configured CUC hosts (CUPI + OS) for the current client
cuc_os_delete_credentials	Delete OS Admin CLI credentials for a CUC host
cuc_os_run_command	Execute a VOS CLI command via SSH on a CUC node
cuc_os_store_credentials	Store OS Admin CLI (SSH) credentials for a CUC host
cuc_os_trust_fingerprint	Trust or reject the SSH host fingerprint for a CUC node
cuc_os_update_credentials	Update OS Admin CLI credentials for a CUC host
cuc_store_credentials	Store CUPI (REST) credentials for a CUC host
cuc_update_credentials	Update CUPI credentials for a CUC host

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_download_report	Download a single report file inline via MCP (PDF as binary blob, Markdown as text)
common_export_report_pdf	Export a Markdown report to PDF via WeasyPrint
common_list_reports	List all reports (PDF and Markdown) available for the authenticated client
common_read_report	Read report content (chunked for large files)
common_write_report	Write content to a Markdown report. Modes: create, append, overwrite, resume, insert_after

Report modes

• create — fails if file exists; prevents accidental overwrite
• append — adds content at the end of an existing file
• overwrite — replaces file content entirely
• resume — resumes an in-progress report from the last written section
• insert_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_get_doc	Retrieve the full content of a doc/resource by name
infra_get_my_permissions	Authoritative RBAC matrix for the calling client (per product / per service allowlists & rate limits)
infra_get_prompt	Retrieve the full content of a prompt by name
infra_health	Liveness/readiness probe — status, ready, license state, server name, uptime
infra_init_session	MANDATORY first call — returns the full tool/prompt catalogue and the client's effective RBAC matrix
infra_list_available_products	Licensed products vs. the calling client's product scope (and the out-of-scope diff)
infra_list_docs	List all available MCP resources/docs (filtered by RBAC product scope)
infra_list_prompts	List all available prompts (filtered by RBAC product scope)
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)

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
cuc_procedure	CUC	⚠️ Mandatory pre-flight — required CUPI (REST) and SSH workflows to read before any CUC operation.
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.
cucm_procedure	CUCM	⚠️ Mandatory pre-flight — required AXL, RIS and SSH workflows, terminal model / IP resolution and sub-module routing, to read before any CUCM operation.
cucm_phone_procedure	CUCM (phones)	⚠️ Mandatory pre-flight for IP phone operations (credentials, screenshot, web information pages, text message). Loaded with the IP phones sub-module.
cucm_roomos_procedure	CUCM (RoomOS)	⚠️ Mandatory pre-flight for RoomOS codec operations: credentials (cluster default / per-codec override), mandatory xAPI lookup, read/write rules, phonebook, messages. Loaded with the RoomOS sub-module.
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_procedure	IMP	⚠️ Mandatory pre-flight — required AXL and SSH workflows to read before any IMP operation.
imp_security_audit	IMP	Equivalent security audit workflow for IMP nodes. Covers IM & Presence-specific security controls and Cisco hardening guidance.

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.).

Security-audit orchestration sub-prompts

The CUCM audit is internally split into chapter sub-prompts (cucm_security_audit_ch01_02 … cucm_security_audit_ch17b) plus cucm_security_audit_report. These are invoked by cucm_security_audit and are not meant to be called directly.

Guided Workflows by Product

MCP prompts the AI agent follows step by step:

Product	Workflow (MCP prompt)	Description
CUCM	cucm_security_audit	Configuration security audit based on the Cisco Security Guide (AXL, SSH and RIS checks), Markdown report with PDF export.
CUCM	cucm_cop_file_install_workflow	COP files installation (patches, device packs, phone / RoomOS firmware) on a CUCM cluster: precheck, installation, progress monitoring.
CUCM – Phones	cucm_phone_software_upgrade_workflow	IP phone firmware upgrade campaign: prerequisites (COP, loads per model, TFTP restart), waves, Device Defaults, automatic monitoring, persistent journal, final report.
CUCM – Phones	cucm_phone_blf_edit_workflow	Add, modify or remove a BLF speed dial on a Cisco IP phone.
CUCM – RoomOS	cucm_roomos_software_upgrade_workflow	RoomOS software upgrade campaign through CUCM: ITL/CTL and Room Navigator checks, automatic monitoring, persistent journal, final report.
CUCM – RoomOS	cucm_roomos_local_phonebook_edit_workflow	List, add, modify or remove folders and contacts in the local phonebook of a RoomOS device.
IMP	imp_security_audit	IM & Presence configuration security audit, Markdown report with PDF export.
CUC	cuc_security_audit	Unity Connection security audit (VOS hardening, CUPI exposure, voicemail security, TLS/certificates), Markdown report with PDF export.

Each product also exposes a mandatory instruction prompt (cucm_procedure, cucm_phone_procedure, cucm_roomos_procedure, imp_procedure, cuc_procedure). Additional workflows can be created as custom prompts from the Admin Web UI.

---

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. All resources share the docs:// scheme, with the module name as the first path segment (docs://<module>/…).

CUCM Resources:

URI Pattern	Content
docs://cucm/cli-guide/*	Cisco CUCM VOS CLI command reference
docs://cucm/security-guide/*	Cisco CUCM Security Guide chapters (Release 15)
docs://cucm/roomos-xapi-guide/*	Cisco RoomOS xAPI reference (RoomOS 26.9.1), one chapter per xAPI domain (Audio, Conference, Phonebook, UserInterface, …) plus an overview of the HTTPS xAPI transport — loaded with the RoomOS sub-module

IMP Resources:

URI Pattern	Content
docs://imp/cli-guide-readonly/*	Cisco IMP VOS CLI command reference (show/utils/file/run/set/unset/delete/license)
docs://imp/security-guide/*	Cisco IMP Security Guide chapters

CUC Resources:

URI Pattern	Content
docs://cuc/cli-guide-readonly/*	Cisco CUC VOS CLI command reference (show/utils/file/run/set/unset/delete/license)
docs://cuc/cupi/reference	CUPI REST endpoint catalogue — verbs, payloads, pagination, examples (CUC 14 & 15)
docs://cuc/security-guide/*	Cisco CUC Security Guide chapters (Release 15) (when packaged)

---

HTTP Endpoints Reference

Endpoints of the MCP listener (https://<host>:<MCP_SERVER_PORT>, 8443 by default).

Method	Endpoint	Auth Required	Description
GET	/.well-known/oauth-authorization-server	None	OAuth 2.0 Authorization Server Metadata (RFC 8414) — OAuth modes only
GET	/.well-known/oauth-protected-resource	None	OAuth 2.0 Protected Resource Metadata (RFC 9728) — OAuth modes only
GET	/.well-known/oauth-protected-resource/mcp	None	OAuth 2.0 Protected Resource Metadata — MCP path variant (RFC 9728) — OAuth modes only
GET	/authorize	None	OAuth 2.1 authorization endpoint — serves the login page (RFC 6749 §3.1, RFC 7636 PKCE) — OAuth modes only
POST	/authorize	Client ID + client secret (login form)	Processes the login form, checks the redirect_uri allow-list, redirects with an authorization code — OAuth modes only
GET	/health	None	Liveness / readiness probe — always HTTP 200; JSON with status, ready, license, maintenance, server, uptime_s
POST / GET / DELETE	/mcp/	Bearer token	MCP protocol endpoint (Streamable HTTP transport)
GET	/metrics	Bearer token	Prometheus metrics (text exposition format)
POST	/revoke	Bearer token	Token revocation (RFC 7009) — a client can only revoke its own tokens — OAuth modes only
GET	/status	Bearer token	Full server status JSON (server, license, backup, requests, security)
POST	/token	Client secret (Basic or form) or PKCE verifier	OAuth 2.1 token issuance — client_credentials or authorization_code (PKCE) grant — OAuth modes only

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.

OAuth endpoints

OAuth modes only endpoints are exposed only when the global authentication mode is oauth2 or jwt+oauth2 (see Authentication Modes). In jwt mode they are not registered.

Admin Web UI listener

The Admin Web UI is served by a separate HTTPS listener (https://<host>:<ADMIN_UI_PORT>/admin/, 9443 by default), protected by its own source-IP allow-list and session authentication (see Security — Admin Web UI). It exposes no API intended for MCP clients.

---

Audit Log Event Reference

The audit log is a dedicated file, logs/audit.log, with its own rotation settings (Logging → Audit logs rotation). It contains one JSON object per line and can be browsed and filtered from the Audit page of the Admin Web UI.

{"timestamp": "2026-10-05 19:25:45,532", "type": "AUDIT", "client": "alice", "profile": "admin", "status": "ALLOWED", "host": "cucm-pub.example.com", "action": "cucm/axl/getPhone"}

Common Fields

Field	Description
timestamp	Server-local timestamp (YYYY-MM-DD HH:MM:SS,mmm)
type	Always AUDIT
status	Event outcome — see the tables below
action	Event category and operation, as <category>/<operation> (e.g. auth/verify, cucm/axl/getPhone, adminui/settings-edit)
client	MCP client name; server for internal events, adminui for Admin Web UI events, unknown when the caller is not identified
profile	RBAC profile of the client (admin profile for Web UI events); system for internal events, none when unknown
source_ip	Source IP address of the request (src on Admin Web UI events)
host	Target Cisco UC node (or terminal), server for server-side checks
reason	Failure or rejection reason, when applicable (e.g. token_expired, invalid_client_secret, redirect_uri_not_whitelisted)

Other fields depend on the event: tool, prompt, uri, error_type, user (admin login), key (setting), fingerprint, scope, grant, jti…

---

Authentication Events

action	status values	Logged when
auth/verify, token/verify	AUTH_SUCCESS, AUTH_FAILED, AUTH_REVOKED, AUTH_BLOCKED	Every MCP bearer-token verification (reason: invalid_token, token_expired, token_malformed, subject_not_in_auth_clients…)
oauth/authorize	AUTH_CODE_ISSUED, AUTH_FAILED, AUTH_BLOCKED	OAuth login form submitted (authorization code + PKCE flow)
oauth/token	TOKEN_ISSUED, AUTH_FAILED, AUTH_BLOCKED	OAuth token request (grant: client_credentials / authorization_code)
oauth/revoke	TOKEN_REVOKED, TOKEN_REVOKE_NOOP, TOKEN_REVOKE_DENIED, TOKEN_REVOKE_FAILED	Token revocation request (RFC 7009)
(none)	IP_BLACKLISTED, IP_RELEASED	Fail2Ban: source IP blacklisted after too many failures (or by an administrator) / released
client/sync	TOKEN_CREATED, TOKEN_RENEWED, TOKEN_REMOVED, SECRET_CREATED, SECRET_REMOVED, TOKEN_VERIFY_ERROR	Client credentials provisioned, renewed or purged at startup

---

MCP Call Events

Every MCP request is logged twice: once by the RBAC / rate-limit gate of the operation, once for the call itself.

action	status values	Logged when
<product>/<protocol>/<operation>	ALLOWED, DENIED, RATE_LIMITED, RATE_LIMITED_GLOBAL	RBAC and rate-limit check of an operation (e.g. cucm/axl/updateLine, imp/ssh/show version active, common/report/write)
(none — field tool)	TOOL_CALLED, TOOL_FAILED	MCP tool invocation (TOOL_FAILED carries error_type and reason)
(none — field prompt)	PROMPT_READ, PROMPT_FAILED	MCP prompt read
(none — field uri)	RESOURCE_READ, RESOURCE_FAILED	MCP resource read
input_validation	REJECTED	Tool parameters rejected by input validation
mcp/<method>	MAINTENANCE_REJECTED	Request refused while maintenance mode is on
cucm/phone/…, cucm/roomos/…, cucm/serviceability/restart <service>	SENT, PARTIAL, EXECUTED, APPLIED, FAILED, SERVICE_<STATUS>	Terminal actions (text message, xAPI command / configuration) and feature-service restarts

Status values

RATE_LIMITED is the per-client limit (RBAC profile); RATE_LIMITED_GLOBAL is the optional global limit per destination host, all clients combined.

---

Credential & Host Trust Events

action	status values	Logged when
credentials/<service>	STORED, UPDATED, DELETED	A client stores, updates or deletes Cisco UC credentials
ssh/fingerprint	TRUSTED	An SSH host fingerprint is trusted (field fingerprint, SHA-256)

---

Report Events

action	status values	Logged when
report/<type>	WRITTEN	Report written (field mode, file)
report/<type>	EXPORTED	Report exported to PDF

---

Server, License & Integrity Events

action	status values	Logged when
server/start, server/stop	STARTED, STOPPED, FAILED, MCP_DISABLED	Server start / stop; MCP disabled by the license state
startup	SSL_DISABLED	Certificate verification towards a Cisco UC product is off
license/verify, license/watchdog, license/import, license/delete	LICENSE_OK, LICENSE_GRACE, LICENSE_EXPIRED, LICENSE_INVALID, LICENSE_MISSING, LICENSE_EXCEEDED, LICENSE_LOST, LICENSE_IMPORTED, LICENSE_DELETED	License check at startup, periodic watchdog, import / delete from the Web UI
integrity/watchdog	INTEGRITY_OK, INTEGRITY_VIOLATION, INTEGRITY_ERROR	Software integrity check (startup and periodic)
transport/<method>	TRANSPORT_BLOCKED	Invalid Host or Origin header (DNS rebinding protection)

---

Admin Web UI Events

Every Admin Web UI action is logged with client = adminui, the administrator login in user, its admin profile in profile and the source IP in src.

action	Logged when
adminui/start	Admin UI listener started
adminui/login, adminui/password-change, adminui/access	Sign-in (SUCCESS, FAILED, LOCKED), password change, request refused (source IP not allowed or blacklisted)
adminui/settings-edit, -revert, -revert-all, -apply, -new-ack	Setting staged, reverted, applied with restart, new setting acknowledged
adminui/file-edit, file-delete, file-delete-pair, file-hostkey-scan, ca-bundle-add, ca-bundle-remove, key-generate, csr-generate, secret-generate, sftp-password, rsa-regenerate	Key, certificate, CA bundle and secret management
adminui/client-create, -edit, -delete, -reveal, -reset-tokens, client-profile-add, -edit, -delete, reveal-template	MCP clients and client profiles
adminui/admin-create, -edit, -delete, -reset-password, admin-profile-create, -delete, admin-rights-save	Administrators and admin profiles
adminui/prompts-save, -import, -delete, -toggle	Custom prompts
adminui/backup-now, -restore, -download, -delete, sftp-export-now, reports-delete	Backups and reports
adminui/license-import, license-delete	License management
adminui/system-maintenance-*, system-blacklist, system-unblacklist, system-reset-stats	System & reload page
adminui/show-tech-run, show-tech-delete, tools-connectivity, tools-add-to-client	Diagnostics and tools

Admin UI events use the statuses SUCCESS, OK, FAILED, DENIED, LOCKED, STARTED and CANCELLED.

Log injection

Every logged value is sanitized (control characters escaped) before being written (CWE-117).

---

Error Types Reference

Error / Status	HTTP Status	Meaning
AXLOperationError	400	AXL SOAP operation failed or returned a fault from Cisco UC
AXLValidationError	400	AXL input validation failed (bad SQL, path traversal, etc.)
CredentialError	400	Credential store error (not found, decryption failure)
OAuthError	400	OAuth 2.1 token request failed (invalid client, bad grant type, etc.)
RISQueryError	400	RIS/Performance query returned an error from Cisco UC
RoomOSError	400	RoomOS codec xAPI call (getxml / putxml) failed
ServiceabilityError	400	CUCM Serviceability (Control Center services) call failed
SSHCommandError	400	SSH command failed or connection was refused
UCPlatformError	400	Base error for Cisco UC platform failures (subclasses below)
WSDLError	400	WSDL/schema download or parsing failed
AUTH_FAILED (malformed)	400	Token cannot be decoded (TokenMalformedError, reason token_malformed)
AUTH_FAILED (expired)	401	Token has passed its expiry time (TokenExpiredError, reason token_expired)
AUTH_FAILED	401	Missing token, invalid signature or claims (TokenInvalidError)
AUTH_REVOKED	401	Token has been explicitly revoked via /revoke
ProfilePermissionError	403	Operation not permitted by the client's RBAC profile
TokenForbiddenError	403	Token is valid but its subject is not a declared client (deleted client)
AUTH_BLOCKED	429	Source IP is currently blacklisted by Fail2Ban
RateLimitError	429	Per-client rate limit exceeded for this product/service — retry after N seconds
RateLimitError (global)	429	Global per-host limit exceeded (all clients) for this product/service on a Cisco node
BackupError	500	Backup or restore operation failed
ConfigError	500	Missing or invalid configuration setting detected at startup
IntegrityError	500	Software integrity check failed — tampered file detected
ReportError	500	Report generation, reading, or PDF export failed
UpgradeError	500	Upgrade tool cannot proceed (e.g. unrecognised release version)
LicenseError	503	License invalid or expired — product modules unavailable

Rate limit retry

On a RATE_LIMITED or RATE_LIMITED_GLOBAL (HTTP 429) response, the Retry-After header indicates the number of seconds to wait before retrying. The per-client limit is defined in the RBAC profile; the optional global limit (all clients, per destination host) is configured in the Admin Web UI (Global settings → Rate limiting and the Rate limiting tab of each product) and is checked after the per-client gate.

---

Standards & RFC Compliance

Standard	Coverage
CWE-117	Log injection prevention in structured log output
NIST FIPS 180-4	SHA-256 / SHA-512 hash algorithms
NIST SP 800-132	PBKDF2 — 600,000 iterations, SHA-512
NIST SP 800-38D	AES-256-GCM authenticated encryption
OWASP Top 10	Input validation, transport security, injection prevention
RFC 4251–4254	SSH Protocol Architecture, Transport, Authentication, Connection
RFC 5280	X.509 Certificate and CRL Profile
RFC 6585	HTTP 429 Too Many Requests
RFC 6749	OAuth 2.0 Authorization Framework (client_credentials and authorization_code grants)
RFC 6750	Bearer Token Usage in HTTP requests
RFC 7009	OAuth 2.0 Token Revocation
RFC 7518	JSON Web Algorithms (JWA) — RS256 signing algorithm
RFC 7519	JSON Web Tokens (JWT)
RFC 7617	HTTP Basic Authentication
RFC 7636	Proof Key for Code Exchange (PKCE) — S256 code challenge method
RFC 8017	RSA-PSS signing & RSA-OAEP encryption (PKCS#1 v2.2)
RFC 8018	PBKDF2 — Password-Based Key Derivation Function 2
RFC 8259	JSON
RFC 8414	OAuth 2.0 Authorization Server Metadata
RFC 8446 / 5246	TLS 1.3 / TLS 1.2
RFC 9068	JWT Profile for OAuth 2.0 Access Tokens
RFC 9110	HTTP Semantics
RFC 9728	OAuth 2.0 Protected Resource Metadata

---

Scripts Reference

Standalone scripts in scripts/. Run from the project root with python scripts/<name>.py.

Script	Description
admin_set_password.py	Set or reset an Admin Web UI account password (bcrypt, password policy enforced); prompts for the password when --password is omitted
backup_restore.py	Interactive restore from encrypted local or SFTP backup archives
certificate_generate_csr.py	Generate a TLS CSR with proper SAN extension (--target mcp\|adminui); reuses existing private key if present
encrypt_sftp_password.py	Encrypt the SFTP backup password (BACKUP_SFTP_PASSWORD_ENC) — CLI alternative to the Set password link of the Web UI
export_mcp_definitions.py	Export all MCP tools, prompts, and resources to JSON for static analysis
healthcheck.py	Container HEALTHCHECK probe (loopback only): MCP /health, or the Admin UI when the MCP listener is disabled by the license
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
upgrade.py	Upgrade tool — reconciles the configuration with the new release (run by tolk-setup.sh)

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 (CUCM, IP phones, IMP, RoomOS lab codec) 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 of the declared MCP clients (name:subject:profile[:auth_mode]) and their authentication modes
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
ca_trust_store.py	Read-only inspection of a per-product CA trust store (directory or bundle file)
client_activity.py	Per-client last-connection tracker (secrets/client_activity.json)
client_credentials.py	One-time reveal of a client's credentials in the Web UI (View credentials)
client_editor.py	Staged create / edit / delete of MCP clients from the Web UI
client_reset.py	Live revocation of a client's active credentials (Reset tokens)
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
csr.py	Shared TLS Certificate Signing Request construction (CN, SANs) for the MCP and Admin UI listeners
cucm_cli_reference.py	CUCM 15 reference sets displayed by the client profile editor (granted / not granted prefixes)
custom_prompts_loader.py	Declarative loader for per-client custom prompts (JSON store) from servers-data/<product>/custom-prompts/
env_editor.py	Write side of the Web UI settings: staged edits, enum / range validation, snapshots, revert, pending-restart diff, AUTH_MODE ↔ clients consistency check
env_variables.py	Configuration loader and typed configuration accessors used across all modules
exceptions.py	Custom exception classes (ConfigError, LicenseError, IntegrityError, …)
garbage_collector.py	Nightly housekeeping daemon (03:15 server time + one pass at startup): purges expired data and re-verifies the license
http_metrics_middleware.py	ASGI middleware incrementing http_requests_total for every HTTP response
integrity.py	SHA-512 manifest verification against the RSA-PSS signed manifest.json
ip_targets.py	Normalization and matching of blacklist targets (single IP or CIDR subnet), shared by Fail2Ban and the admin login throttle
license.py	JWT-based license verification: hostname binding, expiry, grace period, product scope
log_setup.py	JSON rotating loggers for app.log and audit.log + optional colored console handler
lru_cache.py	Tiny thread-safe bounded LRU cache used by the Zeep/WSDL client caches
maintenance.py	Maintenance mode state (persisted on/off switch) and per-client MCP activity tracking
maintenance_middleware.py	Maintenance enforcement: ASGI 503 on new MCP sessions + FastMCP refusal of idle clients
metrics.py	Prometheus metrics definitions — counters, gauges, and histograms for all subsystems
metrics_history.py	Persistent long-term history of request volumes per pipeline stage (Statistics page)
new_settings.py	Settings added by the upgrade tool, flagged as new (blue) in the admin UI until acknowledged, edited or 7 days old
oauth.py	OAuth 2.1 server helpers: PKCE auth codes, token issuance, client secret management
oauth_cors.py	ASGI middleware adding CORS headers to the public OAuth 2.1 endpoints for browser-based clients
profiles.py	RBAC profile loading, hot-reload on file change, and per-operation permission evaluation
public_url.py	MCP_SERVER_PUBLIC_URL: public base URL (reverse proxy / VIP) advertised in OAuth metadata and client URLs; implicitly allowed host / origin
rate_limiter.py	Sliding-window rate limiter: per-client and optional global (all-clients, per destination host)
retry.py	Exponential backoff retry decorator for transient network/connection errors
reveal_template.py	Optional site-customizable template of the client credentials reveal block
rsa_key_cache.py	Process-wide cache for RSA public/private keys to avoid repeated disk reads and parsing
sanitize.py	Input sanitization utilities shared across MCP tool handlers
secure_files.py	Safe view / edit of the key and certificate files referenced by the configuration (Web UI View / Edit)
show_tech_store.py	Storage and orchestration of on-demand show-tech bundles (Logs → Diagnostics)
ssh_pool.py	SSH connection pool with adaptive scaling and idle TTL — multiplexes sessions to CUCM/IMP nodes
stats_snapshot.py	Machine-readable statistics export, outside the Admin Web UI
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: single cert/key pair per listener (self-signed or CA-signed, auto-detected), CN/SAN computation, mid-life renewal, 50% alert state
token_blacklist.py	Persisted JWT revocation list — stores revoked jti claims in secrets/token_blacklist.json
tool_catalog.py	Persisted snapshot of the full MCP tool catalog (coverage views of the Web UI)
transport_security.py	ASGI middleware for DNS rebinding protection via Host and Origin header validation
trusted_proxies.py	TRUSTED_PROXY_IPS: reverse proxies whose X-Forwarded-For identifies the real client; never blacklisted
typeddicts.py	Typed return shapes (TypedDict) for MCP tools and infra helpers
upgrade.py	Upgrade tool engine: version comparison, configuration reconciliation with the new release (new keys inserted, PROJECT_* refreshed), backup, report
validators.py	Pydantic input validation models for all MCP tool parameters

Admin Web UI Modules

Internal modules in servers/admin/ (Admin Web UI).

Module	Description
accounts.py	Admin account store (secrets/admins/accounts.json), bcrypt verification and password policy enforcement
active_sessions.py	In-memory registry of the active admin sessions (shown before a restart)
app.py	Starlette application: routing, session authentication, CSRF protection, per-page RBAC, language switch
backups.py	Backup page orchestration (system, configuration snapshots, certificates / RSA keys)
bruteforce.py	Admin login throttling per login and source IP, with temporary lockout
config.py	Loader and validator of the ADMIN_UI_* settings
context.py	Runtime context shared by the request handlers (configuration, TLS, session secret, license)
env_help.py	Per-parameter help texts (EN / FR) of the settings pages
i18n.py	Minimal EN / FR translation loader
nav_icons.py	Inline SVG navigation icons (no external asset)
pages.py	Page bodies (dashboard, settings, clients, administrators, statistics, system…)
prompts_editor.py	Custom prompts editor backend (servers-data/<product>/custom-prompts/)
rbac.py	Admin RBAC: per-page access matrix (none / ro / rw) and admin profile storage
render.py	Dependency-free HTML rendering with systematic escaping
restart.py	In-place service restart to apply staged settings
security.py	Source-IP allow-list / blacklist middleware and strict security headers (CSP, HSTS…)
server.py	Admin UI HTTPS listener bootstrap (dedicated port)
sessions.py	HMAC-SHA256 signed session cookies
stats_extra.py	Statistics tabs: summary, errors, security, backends, trends, adoption
stats_tops.py	Statistics Tops tab (leaderboards derived from the audit log)
system_info.py	Live system metrics of the System & reload page
tls.py	TLS certificate resolution for the Admin UI listener (MCP certificate reuse or dedicated certificate)
tls_preflight.py	TLS certificate pre-checks displayed before applying changes and restarting
tools_connectivity.py	Tools page connectivity test (DNS, TCP, TLS, …) towards a CUCM, IMP, CUC node or terminal

---

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 secrets and Admin Web UI passwords
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