mcaxl/README.md

mcp-cucm-axl

Read-only MCP server for Cisco Unified CM 15 AXL — built for LLM-driven cluster auditing, with a particular focus on the Route Plan Report: partitions, calling search spaces, route patterns, translation patterns, called/calling party transformations, and digit-discard instructions.

Why this exists

CUCM's admin UI is great for one-config-at-a-time work but painful for audit/discovery questions like:

• "Which translation patterns rewrite the calling party number, and why?"
• "Which CSSs include the Internal_PT partition, in what order?"
• "Show me every route pattern targeting the SIP trunk to the carrier."
• "Are there partitions defined but unreachable from any CSS?"

This server gives an LLM SQL access to CUCM's Informix data dictionary, plus focused tools that bake in the right joins for routing-audit work. Pair it with the sibling mcp-cisco-docs server and the LLM gets vendor documentation alongside live cluster state — answering "is our config consistent with Cisco's recommended baseline?" in a single conversation.

Read-only by structural guarantee

The server never registers AXL write methods. There is no executeSQLUpdate, no add*/update*/remove*/apply*/reset*/ restart* tool. Read-only is enforced by absence of write operations, not by runtime sanitization. Defense-in-depth: SQL queries are also client-side validated to begin with SELECT or WITH.

Setup

1. Configure environment

Edit .env (already gitignored):

AXL_URL=https://cucm-pub:8443/axl
AXL_USER=AxlUser
AXL_PASS=...
AXL_VERIFY_TLS=false        # CUCM ships self-signed certs; default off
AXL_CACHE_TTL=3600          # 1 hour; 0 disables caching
AXL_WSDL_PATH=              # optional explicit WSDL location
CISCO_DOCS_INDEX_PATH=      # optional override for prompt enrichment

2. Bootstrap the AXL WSDL

Download the Cisco AXL Toolkit from your CUCM admin UI:

Application → Plugins → Find → "Cisco AXL Toolkit" → Download

Drop the resulting axlsqltoolkit.zip into the project directory. On first launch, the server auto-extracts schema/15.0/ into ~/.cache/mcp-cucm-axl/wsdl/15.0/. The zip is gitignored (Cisco-licensed; not redistributable).

Alternatives (in resolution order):

# A: explicit zip elsewhere
export AXL_WSDL_ZIP=/path/to/axlsqltoolkit.zip

# B: explicit WSDL file
export AXL_WSDL_PATH=/path/to/schema/15.0/AXLAPI.wsdl

# C: pre-populated cache directory
mkdir -p ~/.cache/mcp-cucm-axl/wsdl/15.0/
cp /path/to/schema/15.0/* ~/.cache/mcp-cucm-axl/wsdl/15.0/

3. Install + run

uv sync
uv run mcp-cucm-axl

Or via the bundled .mcp.json, automatically registered when Claude Code opens this directory.

Tool surface

Foundational

Tool	Purpose
axl_version()	Cluster version sanity check
axl_sql(query)	Execute a SELECT against Informix data dictionary
axl_list_tables(pattern=None)	Discover Informix tables
axl_describe_table(name)	Column metadata for one table
cache_stats(), cache_clear(pattern=None)	Cache plumbing
health()	Subsystem self-check (cache / AXL / docs / RisPort init state)

Real-time device registration (RisPort70)

Complementary to AXL — AXL tells you what's configured, RisPort tells you what's currently registered. The audit-relevant cross-reference is "configured but unregistered" (orphan signal).

Tool	Purpose
device_registration_status(device_class, status, name_filter, page_size)	Page through CUCM's RisPort selectCmDevice for live registration state
device_registration_summary()	Cluster-wide breakdown: registered / unregistered / rejected counts across Phone, Gateway, SIPTrunk, HuntList, etc.

Route plan

Tool	Purpose
route_partitions()	All partitions with pattern + CSS-member counts
route_calling_search_spaces(name=None)	CSS list with ordered partitions
route_patterns(kind=None, partition=None, filter=None)	Route Plan Report — patterns + transformations
route_inspect_pattern(pattern, partition=None)	Deep dive: transforms, route filter, reachable-from CSS, full destination chain (route list → groups → gateways)
route_lists_and_groups(name=None)	Route list → route group → gateway chain (annotates Local Route Group placeholders)
route_translation_chain(number, css_name=None)	Wildcard-aware pattern matcher: evaluates X / ! / [0-9] / @ / \+ against the number and returns matches sorted by specificity
route_digit_discard_instructions()	DDI catalog
route_device_pool_route_groups(device_pool_name=None)	How each device pool resolves Local Route Group placeholders to actual gateway-bearing groups
route_devices_using_css(css_name)	Impact analysis: every reference to a CSS across line CFA/CFB/CFNA/CFUR/translation/MWI/shared, device-level CSSs, voicemail pilots, route lists
route_filters(name=None)	Route filter clauses + member rules (composed with @-pattern routes)

Prompts

Schema-grounded conversation seeds. They pull relevant chunks from the sibling cisco-docs index and embed them inline:

• route_plan_overview — fresh audit conversation seed
• investigate_pattern(pattern, partition=None) — deep-dive a specific pattern
• audit_routing(focus="full") — comprehensive audit walkthrough
• cucm_sql_help(question) — catch-all for arbitrary SQL questions
• sip_trunk_report(name_filter=None) — SIP trunk inventory + findings
• phone_inventory_report(filter=None) — phone fleet aggregates with anomaly findings; cross-references RisPort registration state
• user_audit(focus="full") — end users + application users + role assignments
• inbound_did_audit() — XFORM-Inbound-DNIS inventory + screening pipeline
• hunt_pilot_audit() — hunt pilots, queue settings, line group membership
• whoami(userid=None) — single-user role chain (defaults to AXL service account)

Scope and complement

This server is audit-focused: read-only queries against AXL plus RisPort cross-reference for registration state. It does not cover operational debugging (logs, packet capture, perfmon counters, service control, certificates, backups).

For those, install @calltelemetry/cisco-cucm-mcp alongside this server:

claude mcp add cucm-ops -- npx -y @calltelemetry/cisco-cucm-mcp@latest

The two servers are complementary, not competing — they answer different questions and use different CUCM APIs (AXL + RisPort here; DIME + RisPort + PerfMon + ControlCenter + SSH there). An LLM with both servers can compose audit findings (this server) with operational state (theirs) — e.g., "audit found CSS X has 0 references AND RisPort shows zero phones currently registered against any device pool that inherits it → confirmed safe to delete."

Cache

Responses are cached in SQLite at ~/.cache/mcp-cucm-axl/responses/axl_responses.sqlite. Cache survives restarts. Clear with cache_clear() after a known config change.

Notes

• route_translation_chain does literal/prefix matching only. CUCM's actual matcher evaluates wildcards (X, !, [0-9], etc.) and selects the longest match. Treat results as "patterns to investigate" rather than "definitive route."
• Pattern type codes (tkpatternusage) used by route_patterns(kind=...) are stable across CUCM versions but enumerated against the typepatternusage table at query time, so any cluster-specific custom types still work.