Cisco Catalyst SD-WAN MCP Server
This MCP server lets an AI assistant read and explore a Cisco Catalyst SD-WAN Manager (vManage) fabric through natural-language tool calls.
API explorer: list, search, describe, and call any vManage OpenAPI operation; writes require server-side enablement and explicit confirmation.
Inventory: list devices, reachable devices, controllers, WAN edge inventory, and device details.
Control plane and OMP: inspect control connections, histories, local properties, WAN TLOCs, affinity, OMP peers/routes/TLOCs/services/multicast/Cloud OnRamp, links, status, and summaries.
Validator: query vBond connections/history, summary, statistics, local properties, authorized devices, and proxy/NAT mappings.
Data plane and system: check BFD sessions/summaries/TLOCs, interfaces, system CPU/memory/uptime, ARP, VPNs, TLOCs, and bridge tables.
Routing and traffic stats: view BGP neighbors/routes/summary, application-aware routing stats/SLA, cflowd flows/stats, app-log flows/count, and SD-WAN stats.
UX 2.0 configuration: inspect config/policy/topology groups, feature profiles, network hierarchy, group variables, and read-only previews of device configuration changes.
UX 1.0 templates and policies: list device/feature templates, attached devices, template definitions, policy lists/definitions, and policies.
Operations and Cloud OnRamp: check CloudExpress status/lists/apps, active alarms, certificate summary, cluster health, and custom apps.
Limit: this schema exposes read-only tooling by default; dedicated write tools are absent, and only the generic API caller can perform writes when enabled and confirmed.
Provides tools for querying and managing Cisco Catalyst SD-WAN Manager (vManage) through its REST API, covering fabric inventory, devices, control connections, OMP routing, BFD sessions, templates, policies, alarms, certificates, and other vManage operations, with optional controlled write operations.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Cisco Catalyst SD-WAN MCP Server How many devices are in the fabric, and are they all reachable?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Cisco Catalyst SD-WAN MCP Server
A Model Context Protocol (MCP) server for Cisco Catalyst SD-WAN Manager (vManage). It lets AI assistants such as OpenChamber/OpenCode, GitHub Copilot in VS Code and Visual Studio, Cursor and Claude query the SD-WAN fabric in natural language: devices, control plane, OMP, BFD, routing, templates, policies, alarms and the rest of the vManage REST API.
All requests go through vManage. The server never connects to routers directly.
163 MCP tools (121 listed on a read-only server, 163 with writes enabled): 159 purpose-built tools, including fabric-wide health, BFD and TLOC checks in a single call, BGP, OSPF, OSPFv3, EIGRP, multicast (IGMP, PIM, MFIB) and IPv6 monitoring and configuration (UX 2.0 features and UX 1.0 templates/policy objects), CLI add-on configuration (for example RIP/RIPng), UX 2.0 configuration, policy and topology groups (read, preview, create, change, associate devices, set variables, deploy), feature profiles and the network hierarchy (regions, areas, sites and their Cyber Vision network settings), plus 4 general tools that reach every operation in the vManage OpenAPI spec (4,128 operations on 26.2).
Lean tool list. Write tools are listed only when
VMANAGE_ALLOW_WRITE=true, so a read-only server offers 121 tools (under VS Code's 128-tool limit) in a tool list under 110 KB, about a third smaller than before. Assistants answer faster and spend fewer tokens on every request.Read-only by default. Operations that change configuration or state are disabled unless you enable them, and each call then needs explicit confirmation.
BGP, OSPF, OSPFv3 and EIGRP end to end. Real-time neighbors, routes, interfaces, topology and LSDB; UX 2.0 feature reads and writes for SD-WAN and SD-Routing profiles; UX 1.0 feature templates (list, read, schema, create, update, delete, clone). Every BGP, OSPF and EIGRP operation in the 26.2 spec has a dedicated tool.
Multicast end to end. IGMP, PIM, overlay multicast (topology, RPF, replicators, tunnels) and MFIB monitoring; UX 2.0 multicast features (read, schema, write); UX 1.0 IGMP, PIM and multicast templates. Every multicast operation in the 26.2 spec has a dedicated tool.
IPv6 end to end. ND, neighbors, IPv6 routes, FIB, interface statistics, DHCPv6, NAT64, OMP IPv6 routes, IPv6 ACL and SGACL counters; UX 1.0 IPv6 prefix lists, IPv6 ACLs and device-access policies (read, preview, write); UX 2.0 IPv6 trackers and tracker groups (read, schema, write). Every IPv6 operation in the 26.2 spec has a dedicated tool.
CLI add-ons for everything else. RIP and RIPng have no vManage API, so they are configured as raw IOS XE CLI. Dedicated tools find, read, create, change and delete CLI add-on features (UX 2.0) and CLI add-on templates (UX 1.0);
contains: "router rip"finds where a protocol is configured.Validated against the spec. Calls through the general tools are checked against the OpenAPI spec published by your vManage before they are sent.
Secrets are protected. Endpoints that issue tokens, passwords, OTPs or credentials are blocked. Session IDs and CSRF tokens are redacted from responses. Passwords, secret hashes, keys and SNMP communities are masked in configuration, policy and topology group previews.
Fast and resilient.
Logs in, loads the device list and the API spec in the background at startup, so the first question doesn't wait.
Uses Node's
undiciHTTP client with a pooled keep-alive connection set and one login shared across concurrent calls; the JWT is renewed in the background before it expires.Combines identical concurrent requests and caps how many run against vManage at once.
Retries dropped connections and 429/502/503/504 with jittered backoff, honouring
Retry-After.Fails fast for 10 s after vManage proves unreachable, instead of every call waiting for a timeout.
Separate timeouts: real-time device queries get longer than inventory, configuration and statistics queries.
Caches the API spec on disk and short-lived lookups in a bounded memory cache; hostname lookups answer from the last device list while it refreshes in the background.
Returns compact JSON, and every list tool accepts
fieldsandfilterto return only what is needed.Logs out session-cookie logins when the client disconnects, so they don't pile up against vManage's session limit.
Device names work everywhere. Pass a hostname (
Branch-1), system IP, UUID or serial number.JWT authentication (vManage 20.18.1+) with session-cookie fallback for older releases.
flowchart LR
U(["User<br/>asks in plain language"])
subgraph CLIENT["AI client"]
A["GitHub Copilot · Claude · Cursor · OpenCode"]
end
subgraph MCP["catalyst-sdwan MCP server · Node.js"]
direction TB
T["Tool router<br/>156 dedicated + 4 general tools"]
R["Name resolution<br/>hostname · system IP · UUID<br/>group · profile · hierarchy node"]
G{"Write gate<br/>VMANAGE_ALLOW_WRITE<br/>+ confirm: true"}
C["API catalog<br/>checks each call against the OpenAPI spec"]
V["vManage client<br/>JWT login · cache · request dedupe<br/>retries · concurrency cap"]
S["Response shaping<br/>fields · filter · count_by · paging"]
end
subgraph SDWAN["Cisco Catalyst SD-WAN"]
M[("SD-WAN Manager<br/>vManage REST API")]
D["Controllers · Validators · WAN edges"]
end
U --> A
A -- "MCP over stdio" --> T
T --> R --> G
G -- "read or approved write" --> C --> V
G -. "write refused" .-> A
V == "HTTPS REST + JWT" ==> M
M <--> D
M -- "JSON" --> V --> S --> A
A -- "answer" --> U
M -. "OpenAPI spec, cached on disk" .-> C
classDef user fill:#f472b6,stroke:#be185d,stroke-width:3px,color:#fff
classDef client fill:#8b5cf6,stroke:#5b21b6,stroke-width:3px,color:#fff
classDef core fill:#06b6d4,stroke:#0e7490,stroke-width:2px,color:#fff
classDef gate fill:#facc15,stroke:#a16207,stroke-width:3px,color:#1f2937
classDef net fill:#22c55e,stroke:#15803d,stroke-width:2px,color:#fff
classDef mgr fill:#f97316,stroke:#c2410c,stroke-width:3px,color:#fff
classDef dev fill:#3b82f6,stroke:#1d4ed8,stroke-width:2px,color:#fff
class U user
class A client
class T,R,C,S core
class G gate
class V net
class M mgr
class D dev
style CLIENT fill:#f5f3ff,stroke:#8b5cf6,stroke-width:2px,stroke-dasharray:6 4
style MCP fill:#ecfeff,stroke:#06b6d4,stroke-width:2px
style SDWAN fill:#fff7ed,stroke:#f97316,stroke-width:2px,stroke-dasharray:6 4
linkStyle default stroke:#64748b,stroke-width:2px
linkStyle 1 stroke:#8b5cf6,stroke-width:3px
linkStyle 6 stroke:#ef4444,stroke-width:2px
linkStyle 7 stroke:#f97316,stroke-width:4px
linkStyle 9,10,11,12 stroke:#22c55e,stroke-width:3px
linkStyle 13 stroke:#06b6d4,stroke-width:2pxA question goes from the AI client to the matching tool. The server resolves names to IDs, stops writes at the write gate unless they are enabled and confirmed, checks the call against the vManage API spec and sends it to SD-WAN Manager. The JSON reply is trimmed to the fields needed and returned to the assistant.
Contents
Related MCP server: Cisco Meraki MCP Server
What you can achieve
Ask questions about your SD-WAN fabric in plain language and get answers built from live Manager data, without clicking through the GUI or writing API scripts.
Use case | Example questions | Main tools |
Inventory and health | "Is my fabric healthy?" "Which edges have high CPU?" "Is the Manager a cluster or single node?" |
|
Control-plane troubleshooting | "Why is this edge missing control connections? Show the history." |
|
Overlay routing (OMP) | "Which TLOCs and routes does this site advertise in VPN 10?" |
|
OSPF and OSPFv3 | "Is OSPF running on Branch-2? Show its OSPFv3 neighbors. Which service profiles configure OSPF?" |
|
BGP | "Which BGP neighbors does Hub-1 have in VPN 10? Which profiles configure BGP?" |
|
EIGRP | "Is EIGRP running on Branch-3? Show its topology table. Which service profiles configure EIGRP?" |
|
Multicast | "Which IGMP groups has Branch-1 joined? Who are its PIM neighbors and RPs? Which service profiles configure multicast?" |
|
IPv6 | "Which IPv6 routes does Branch-1 have in VPN 10? Show its IPv6 neighbors. Which IPv6 prefix lists and ACLs exist?" |
|
RIP, RIPng and other CLI | "Which CLI add-ons configure RIP? Add an |
|
Routing changes (opt-in) | "Create a BGP feature for AS 65001 and attach it to VPN 10." "Clone the OSPF-Branch template." |
|
Data plane and transport | "Are all BFD sessions in the fabric up? How many TLOCs does site 100 have?" |
|
Application-aware routing | "Show tunnel loss/latency/jitter and SLA classes." |
|
Configuration audit (UX 2.0) | "Which configuration group configures the branch sites? What would a deploy change?" |
|
Configuration, policy and topology group changes (UX 2.0, opt-in) | "Add Branch-3 to Branch-CG, set its variables, preview and deploy." |
|
Network hierarchy (UX 2.0) | "Show the regions, areas and sites. Which devices are in site 105? Which Cyber Vision centers are configured?" |
|
Templates and policies (UX 1.0) | "Which device templates and centralized policies are in use? Which BGP, OSPF, EIGRP or PIM templates exist?" |
|
Operations | "Any critical alarms? Certificates expiring? Is the Manager cluster healthy?" |
|
Anything else in the API | "Show IPsec/IKE sessions", "audit log for today" |
|
Controlled changes (opt-in) | Any POST/PUT/DELETE operation, only after you approve it | The routing write tools, or |
Quick start
# 1. Get the code and build it
git clone https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp.git
cd cisco-catalyst-sdwan-mcp
npm ci && npm run build
# 2. Point it at your Manager
cp .env.example .env && chmod 600 .env
# edit .env: VMANAGE_HOST, VMANAGE_USERNAME, VMANAGE_PASSWORD
# 3. (Optional) Smoke test with the MCP Inspector
npx @modelcontextprotocol/inspector node build/index.jsRegister the server in your AI client, for example VS Code
.vscode/mcp.json:{ "servers": { "catalyst-sdwan": { "type": "stdio", "command": "node", "args": ["${workspaceFolder}/build/index.js"] } } }Open the chat in Agent mode and ask: "How many devices are in my SD-WAN fabric?"
See Installation, Configuration and Integrating with MCP clients for details and other clients.
Versions and compatibility
Component | Version | Notes |
MCP server | 1.1.0 |
|
Catalyst SD-WAN Manager | Tested on 26.2.1 | Controllers 26.2.1, WAN edges Catalyst 8000V IOS XE 26.02.01 |
Catalyst SD-WAN Manager (auth) | 20.18.1+ for JWT | Older releases: set |
Node.js | 20.12+ | CI runs the offline tests on Node.js 20, 22 and 24; tested live on Node.js 26 |
MCP TypeScript SDK |
| Tested with 1.27.1 |
Transport | stdio | The client starts the server as a child process |
MCP clients tested | OpenChamber 2.5 (bundled OpenCode 2.0.32), OpenCode 1.19 | Other clients use their documented standard MCP config |
The four general API tools (list_api_categories, search_api_operations, describe_api_operation, call_api_operation) download the OpenAPI spec that your vManage publishes at https://<vmanage>/apidocs/vmanageapi.json. They therefore follow the API of whatever release you connect to, and new endpoints in later releases are available without code changes.
Supported functionality
General API tools (full vManage API)
Tool | Purpose | Key parameters | Example prompt |
| Lists the API categories (390 on 26.2) with counts of read, write and blocked operations |
| "Which API categories exist for monitoring?" |
| Finds operations by keywords matched against path, operationId, category and summary |
| "Find the API for OSPF neighbors." |
| Shows an operation's documented parameters, request-body schema/example and access level |
| "What parameters does |
| Calls any operation; parameters and body are validated against the spec |
| "Show OSPF neighbors on Branch-1." |
Each of the 4,128 operations in the 26.2 spec falls into one of three access levels:
Access | Count on 26.2 | Behaviour |
read | 2,392 | Runs immediately |
write | 1,672 | Disabled unless |
blocked | 64 | Never callable: issues or exposes tokens, passwords, OTPs, credentials or bootstrap configs; file uploads; event streams |
Operations count as write when their method is POST, PUT or DELETE, or when their operationId or spec description describes an action. Examples: setvSmartMtHubList (pushes the serial list to controllers), reTriggerNetworkMigration, telemetry opt-in. vManage has several GET endpoints like these that change state.
Dedicated tools
Parameters marked * are required; all others are optional. Every device_id / device parameter accepts a hostname (e.g. Branch-1), system IP, UUID or serial number. Real-time device tools query the device through the Manager; tools with synced can return the Manager's cached copy instead, which is faster.
Response shaping (all tools except the API catalog and fabric-wide tools). Optional arguments trim list results before they reach the assistant, which means fewer tokens and faster answers:
Argument | Example | Effect |
|
| Keep only these fields in each row |
|
| Keep only matching rows (case-insensitive; an array matches any value). The response includes |
|
| Return counts per value instead of rows (after |
|
| Page through rows (after |
Responses stay under 200,000 characters. A larger list is cut at a row boundary and returns truncated: { returned, total, nextOffset }; calling again with offset set to nextOffset continues the list. list_devices reads a cached inventory (60 s), which is also preloaded at startup, and returns summary fields unless fields or all_fields: true is given.
{ "name": "list_devices", "arguments": { "fields": ["host-name", "system-ip"], "filter": { "device-type": "vedge" } } }Fabric-wide (3)
One call answers a fabric-wide question. The server queries every selected WAN edge in parallel and returns a summary plus per-device detail, instead of the assistant calling a per-device tool once per edge. Unreachable edges are listed under skippedUnreachable rather than queried, and a device that fails is reported with an error without failing the whole call.
Built for large overlays:
Bounded fan-out. A fixed pool of workers (
VMANAGE_FABRIC_CONCURRENCY, default 6) leaves request slots free for other tools. Real-time sweeps use a smaller pool (VMANAGE_FABRIC_REALTIME_CONCURRENCY, default 4) and are capped at 200 edges.Time budget. A sweep returns within
VMANAGE_FABRIC_DEADLINE_MS(default 25 s), ormax_wait_secondsper call. Edges not reached in time are listed underincomplete.Resumable. Per-device results are cached (60 s synced, 15 s real-time), so calling again continues with only the remaining edges.
Overload breaker. After 5 consecutive overload errors (429/5xx/timeouts), the sweep stops instead of adding load to the Manager.
Compact output. Above 50 edges only devices with problems or errors are listed (
detail: "all"lists every device); summary totals always cover all queried edges.
Tool | Description | Key parameters | Example prompt |
| Overall |
| "Is my SD-WAN fabric healthy?" |
| BFD sessions of every WAN edge: per-device counts, the sessions that are not up, and fabric totals |
| "Are all BFD sessions in the fabric up?" |
| TLOCs of every WAN edge: color, interface, state and IPs per device, totals per color and TLOCs that are not up |
| "How many TLOCs does each branch have, and are any down?" |
get_fabric_health takes per-device counters and health from /health/devices (falling back to the device inventory), not from the dashboard status widgets, which can report 0 up / 0 down. Unhealthy devices show the cause, e.g. health red (CPU 96.4%, memory 45.5%). The Manager deployment comes from /clusterManagement/tenancy/mode and /clusterManagement/list; on a multi-tenant Manager in provider view the tenants are listed. Up to 50 devices are all listed; above that only devices with problems (detail: "all" lists every device).
The fabric BFD and TLOC tools query devices in real time when 25 or fewer edges are selected, and use vManage's cached (synced) data otherwise; synced: true or false overrides this. With synced data, results include the time the data was last synced (syncedDataAsOf), and edges whose cached BFD sessions are not up are re-checked in real time (verifiedLive) before they are reported. vManage processes many real-time device queries slowly, so combine synced: false with site_id or devices on large fabrics.
Devices and inventory (5)
Tool | Description | Key parameters | Example prompt |
| All fabric devices (Manager, Controllers, Validators, WAN edges) with hostname, type, system IP, site ID, reachability and version |
| "How many devices are in the SD-WAN fabric?" |
| Full inventory record of one device |
| "Show details of Branch-1." |
| Devices that are currently reachable | – | "Which devices are reachable right now?" |
| Manager, Controller and Validator inventory | – | "List the controllers and their versions." |
| WAN edge authorized list with certificate and validity status | – | "Which WAN edges are in the inventory but not valid?" |
Control plane (13)
Tool | Description | Key parameters | Example prompt |
| Control connections of a device to Controllers, Validator and Manager |
| "Show Branch-1's control connections to the vSmarts." |
| Past connection attempts, errors and down reasons |
| "Why did Branch-2 lose its control connections?" |
| System IP, site ID, organization, certificate state, Validator address, max controllers |
| "What org name and certificate state does Hub-1 have?" |
| Per-TLOC control state: color, interface, public/private IP and port, controller counts |
| "How many TLOCs does Branch-1 have?" |
| Authorized device lists held by a Controller (vSmart) |
| "Which edges are authorized on the first Controller?" |
| Controller-group affinity configuration or status |
| "Show controller affinity status of Hub-1." |
| Fabric-wide control links in a given state |
| "List all control links that are down." |
| Fabric-wide control up/down counts | – | "How many control connections are up vs. down?" |
| Control connection counts, fabric-wide or per site |
| "Control connection count for site 103." |
| Per device: control connections, OMP peers, vSmart peers, reachability |
| "Give me a fabric-wide control-plane summary." |
| Reachable/unreachable counts per device class | – | "How many WAN edges are unreachable?" |
| Control-plane summary of a device |
| "Control summary of Branch-3." |
| DTLS control connection statistics |
| "Show DTLS statistics of Branch-1." |
OMP – Overlay Management Protocol (9)
Tool | Description | Key parameters | Example prompt |
| OMP peers of a device |
| "Show the OMP peers of the first Controller." |
| OMP routes received or advertised |
| "Show OMP routes Branch-1 receives in VPN 10." |
| OMP TLOC routes received or advertised |
| "Which TLOCs does Branch-1 advertise?" |
| OMP service routes (VPN, firewall, IDS, ...) |
| "Which OMP services does Hub-1 know?" |
| Multicast routes or auto-discovery entries |
| "Show multicast auto-discovery on Branch-2." |
| Cloud OnRamp (CloudExpress) OMP routes |
| "Any Cloud OnRamp routes on Hub-1?" |
| Fabric-wide OMP peering links in a given state |
| "List OMP peerings that are down." |
| Fabric-wide OMP up/down counts | – | "Are all OMP peerings up?" |
| OMP summary of a device |
| "OMP summary of Branch-3." |
Validator – vBond / orchestrator (6)
Use the Validator's system IP or hostname as device_id.
Tool | Description | Key parameters | Example prompt |
| Current connections on the Validator, or history |
| "Show the Validator's connection history." |
| Validator connection summary |
| "Validator connection summary." |
| DTLS/control packet statistics |
| "Show Validator packet statistics." |
| Organization, certificate state, system IP |
| "Which organization name is the Validator using?" |
| Authorized device lists on the Validator |
| "How many WAN edges are authorized on the Validator?" |
| NAT/proxy mapping table |
| "Show the Validator NAT mapping table." |
Data plane, interfaces, routing and system (9)
Tool | Description | Key parameters | Example prompt |
| BFD sessions (tunnels) of a device |
| "Are all BFD sessions on Branch-1 up?" |
| BFD session summary |
| "BFD summary of Branch-2." |
| BFD session summary per TLOC |
| "BFD sessions per TLOC color on Branch-3." |
| TLOC information of a device |
| "Show TLOCs of Branch-1." |
| VPN configuration of a device |
| "Which VPNs are configured on Hub-2?" |
| Bridge forwarding table |
| "Show the bridge table of Branch-2." |
| Interface status and configuration |
| "Which interfaces are down on Branch-3?" |
| ARP table (IPv4 to MAC) |
| "Show the ARP table of Hub-1." |
| CPU, memory, uptime |
| "What's the CPU and memory usage on Hub-1?" |
Routing protocols at a glance
Every BGP, OSPF, OSPFv3 and EIGRP operation in the 26.2 spec has a dedicated tool. npm test checks this against the spec on every run.
Area | BGP | OSPF (v2) | OSPFv3 (IPv4 and IPv6) | EIGRP |
Real-time monitoring |
|
|
|
|
UX 2.0 features: read |
|
|
|
|
UX 2.0 features: write |
|
| Same OSPF tools with |
|
UX 1.0 templates |
|
|
|
|
Spec operations covered | 55 (25 read, 30 write) | 144 including OSPFv3 (63 read, 81 write) | 92 of the 144 (38 read, 54 write) | 23 (11 read, 12 write) |
The UX 1.0 rows use the routing and multicast template tools, which work on all routing and multicast template types.
RIP and RIPng have no API in vManage 26.2: no /device/rip monitoring, no UX 2.0 routing feature and no UX 1.0 template type. They are configured as IOS XE CLI through CLI add-ons.
UX 2.0 configuration tools address a feature by profile, never by raw URL:
profile_type(serviceortransport) andprofile(ID or exact name) pick the feature profile;solutionpickssdwan(default) orsd-routing.vpn_feature_idnarrows to the features associated with one VPN feature (SD-WAN: LAN VPN for service, WAN VPN for transport) or VRF feature (SD-Routing).global_vrf: trueselects the global VRF of an SD-Routing transport profile.feature_idaddresses one feature. All IDs must be UUIDs.
Typical write workflow (needs VMANAGE_ALLOW_WRITE=true; every write needs confirm: true after you approve it):
Read the current state:
get_bgp_config/get_ospf_config, andget_bgp_feature_schemafor the body format.Create the feature in the profile:
create_bgp_feature/create_ospf_featurereturns its ID.Attach it to a VPN or VRF:
associate_bgp_feature/associate_ospf_feature.Deploy the configuration group (
preview_config_group_device_configshows what would change first). Editing a profile never pushes configuration to devices by itself.
To remove a feature, first detach it (delete_*_feature with vpn_feature_id), then delete it (delete_*_feature without vpn_feature_id).
BGP (9)
The nine tools cover all 55 BGP operations in the 26.2 spec: the 3 real-time monitoring endpoints (with their filters), the 2 feature-schema reads, and the 20 read and 30 write operations for BGP features of SD-WAN and SD-Routing feature profiles. The write tools follow the same rules as the OSPF write tools below.
Tool | Description | Key parameters | Example prompt |
| BGP neighbors |
| "Show BGP neighbors on Hub-1 in VPN 10." |
| BGP routes |
| "Which BGP routes does Hub-2 have for 10.1.0.0/16?" |
| BGP summary |
| "BGP summary of Hub-1." |
| BGP features of a UX 2.0 service or transport profile, optionally per VPN/VRF feature or one feature |
| "Which BGP features does the Hub-Transport profile have?" |
| JSON schema vManage expects for an SD-WAN BGP feature body |
| "What fields does a BGP service feature need?" |
| Write. Create a BGP feature in a profile; returns its ID |
| "Create a BGP AS 65001 feature in Branch-Service." |
| Write. Replace a feature (full definition); with |
| "Add a neighbor to the BGP feature in Branch-Service." |
| Write. Delete a feature; with |
| "Detach the BGP feature from VPN 10." |
| Write. Attach an existing feature to a VPN feature (sdwan) or VRF feature (sd-routing) |
| "Attach the BGP feature to the VPN 10 feature." |
OSPF and OSPFv3 (10)
The ten tools cover all 144 OSPF operations in the 26.2 spec, 92 of them OSPFv3: the 9 real-time monitoring endpoints, and the 54 read and 81 write operations for OSPF / OSPFv3 features of SD-WAN and SD-Routing feature profiles. OSPFv3 is selected with version: ospfv3 for the monitoring tools, ospfv3-ipv4 or ospfv3-ipv6 for the feature tools.
The four write tools change configuration. Like call_api_operation, they are disabled unless VMANAGE_ALLOW_WRITE=true, each call needs confirm: true after you approve it, and the target operation is checked against the Manager's spec before it is sent. Changing a feature in a profile does not deploy it; devices get the change when their configuration group is deployed.
Tool | Description | Key parameters | Example prompt |
| OSPF process details. Can be empty even when OSPF runs in a service VPN; use |
| "Show the OSPF process on Hub-1." |
| OSPF or OSPFv3 neighbors |
| "Show OSPF neighbors on Hub-1." |
| OSPF or OSPFv3 enabled interfaces (with area, VPN, state) |
| "Is OSPF configured on Branch-2?" |
| OSPF routes |
| "Show OSPF routes on Hub-2." |
| Link-state database |
| "Show external LSAs on Hub-1." |
| OSPF / OSPFv3 features of a UX 2.0 service or transport profile, optionally per VPN/VRF feature or one feature |
| "Which OSPF features does the Branch-Service profile have?" |
| Write. Create an OSPF / OSPFv3 feature in a profile; returns its ID |
| "Create an OSPF area 0 feature in Branch-Service." |
| Write. Replace a feature (full definition); with |
| "Change the OSPF hello interval in Branch-Service to 5 s." |
| Write. Delete a feature; with |
| "Detach the OSPF feature from VPN 10 in Branch-Service." |
| Write. Attach an existing feature to a VPN feature (sdwan) or VRF feature (sd-routing) |
| "Attach the OSPF feature to the VPN 10 feature." |
EIGRP (8)
The eight tools cover all 23 EIGRP operations in the 26.2 spec: the 3 real-time monitoring endpoints and the 8 read and 12 write operations for EIGRP features. vManage has EIGRP features only in service profiles (SD-WAN: profile level and per LAN VPN; SD-Routing: profile level and per VRF), so profile_type accepts only service. The write tools follow the same rules as the OSPF write tools above.
Tool | Description | Key parameters | Example prompt |
| EIGRP-enabled interfaces; an empty list means EIGRP is not running |
| "Is EIGRP running on Branch-3?" |
| EIGRP routes |
| "Show EIGRP routes on Branch-3." |
| EIGRP topology table (successors and feasible successors) |
| "Does Branch-3 have a feasible successor for 10.20.0.0/16?" |
| EIGRP features of a UX 2.0 service profile, optionally per VPN/VRF feature or one feature |
| "Which EIGRP features does the Branch-Service profile have?" |
| Write. Create an EIGRP feature in a service profile; returns its ID |
| "Create an EIGRP AS 100 feature in Branch-Service." |
| Write. Replace a feature (full definition); with |
| "Add network 10.30.0.0/16 to the EIGRP feature." |
| Write. Delete a feature; with |
| "Detach the EIGRP feature from VPN 20." |
| Write. Attach an existing feature to a LAN VPN feature (sdwan) or VRF feature (sd-routing) |
| "Attach the EIGRP feature to the VPN 20 feature." |
Application-aware routing, flows and statistics (7)
Tool | Description | Key parameters | Example prompt |
| AAR tunnel statistics (loss, latency, jitter) |
| "Show tunnel loss and latency on Branch-1." |
| SLA classes used by application-aware routing |
| "Which SLA classes are configured on Branch-1?" |
| cFlowd flow records |
| "Show cFlowd flows on Branch-3." |
| cFlowd packet statistics |
| "cFlowd statistics of Branch-3." |
| Packet flow logs |
| "Show logged flows on Branch-2." |
| Number of logged flows |
| "How many flows are being logged on Branch-2?" |
| SD-WAN statistics: ACL drops, data policy, device metrics |
| "Any data-policy drops on Branch-2?" |
UX 2.0 configuration (27)
The solution parameter selects sdwan (default), sd-routing, nfvirtual or mobility. Groups and profiles can be passed by ID or exact name, and devices by hostname, system IP, UUID or chassis number. The dedicated tools cover all 40 configuration-group, policy-group and topology-group operations of the 26.2 spec.
Tool | Description | Key parameters | Example prompt |
| One-call summary: configuration, policy and topology groups with device counts and deployment state, plus feature-profile counts per type |
| "Are any configuration groups out of sync or failed?" |
| Configuration groups with feature profiles, device counts and deployment state |
| "How many configuration groups are on vManage?" |
| One configuration group with its profiles and associated devices |
| "Which devices does configuration group Branch-CG configure?" |
| Device-specific variable values (all devices or one) |
| "Show the variables of Branch-1 in Branch-CG." |
| Read-only preview: configuration the group would push vs. running config, secrets masked. |
| "What would Branch-CG change on Branch-1 if I deployed now?" |
| Read-only. For the devices attached to a device template, their values for the configuration group converted from it (and its SIG policy group), from their template values; reports missing and invalid values and template variables no group uses; secret values (passwords, keys, SNMP communities) are masked |
| "Plan the Branch-CG values of the devices on template Branch-CG." |
| Read-only. Defects the template-to-group conversion left, against the feature templates: services turned off, NAT lost, SIG settings reset to group defaults, stray tunnel settings; each with its fix |
| "Did the conversion break anything in Branch-CG?" |
| Policy groups with profiles, device counts and state |
| "List the policy groups." |
| One policy group with profiles and devices |
| "Which devices use policy group Branch-PG?" |
| Topology groups (hub-and-spoke, mesh) |
| "Which topology groups exist?" |
| One topology group with its profiles |
| "Show topology group Hub-Spoke." |
| Feature profiles per type ( |
| "List all transport profiles." |
| One profile with its features (parcels) |
| "Show the features in the Hub-Transport profile." |
| Global, regions, areas and sites. With |
| "Which sites are under the EMEA region?" |
| Cisco Cyber Vision centers configured in the network settings of the hierarchy, or one center's ID by name |
| "Which Cyber Vision centers are configured?" |
| Write. Add or edit Cyber Vision centers in the network settings |
| "Add Cyber Vision center CV-1 at 10.10.10.10." |
| Write. Remove a Cyber Vision center (by ID, or by name, which is looked up) |
| "Remove Cyber Vision center CV-1." |
| Device variables of a configuration or policy group: values (all devices or one, optionally with suggestions), the variables schema, or a vManage-side fetch |
| "Which variables does EMEA-Policy-Group need per device?" |
| Automatic device-association rules of a configuration or policy group; bulk rule-association preview of a topology group |
| "Which rules add devices to Branch-CG?" |
| Read-only preview for a policy or topology group: configuration it would push vs. running config. Secrets are masked. Nothing is deployed. |
| "What would EMEA-Policy-Group change on EMEA-Paris?" |
| Write. Create a configuration, policy or topology group; returns its ID |
| "Create configuration group Lab-CG with the Lab profiles." |
| Write. Replace a group definition (name, description, profiles). Devices change only on deploy. |
| "Add the CLI profile to Branch-CG." |
| Write. Delete a group; optionally its feature profiles too (configuration and policy groups) |
| "Delete the unused Lab-CG." |
| Write. Add, replace or remove the devices of a configuration or policy group |
| "Add Branch-3 to Branch-CG." |
| Write. Set device variable values of a configuration or policy group |
| "Set the site ID variable of Branch-3 to 300." |
| Write. Pushes configuration to devices. Deploy a configuration, policy or topology group to the given devices; returns the vManage task |
| "Deploy Branch-CG to Branch-3." |
| Write. Pushes configuration to the device. Move one device from its device template to the configuration group converted from it, in approved steps: |
| "Migrate Branch-3 from template Branch-CG." |
Network hierarchy. The hierarchy tools cover all 4 network-hierarchy operations in the 26.2 spec (the Cyber Vision network settings: 2 reads, 1 create/edit, 1 delete) plus the hierarchy list and node detail (GET /v1/network-hierarchy[/{id}]), which vManage serves but does not document. Nodes are found by node ID, hierarchy path, site ID or name; a name used by more than one node is refused with the matching paths. vManage 26.2 accepts network settings only on the Global node (other nodes return NWHAR0005), so the Cyber Vision tools default to it. The 26.2 API has no operation to create, rename, move or delete regions, areas or sites, so the server cannot change the hierarchy itself; do that in the Manager GUI (Configuration → Network Hierarchy).
Recommended change workflow: get_config_group / get_group_variables → change with update_group, associate_group_devices or update_group_variables → preview_config_group_device_config or preview_group_device_config for each device → deploy_group after you approve the diff.
Review view. view: "review" sorts what a deploy would change into dropped (settings the group does not configure), changed (same setting, new value: console-baud-rate 115200 -> 9600), secretsChanged (passwords, keys and hashes with a new value, masked; type 5/8/9 hashes are marked as possibly only re-salted), added, and defaults (no action needed), each line with its section (interface GigabitEthernet2 > ip nat outside). For a configuration group with a policy group of the same name, where the template-to-group conversion puts SIG, the SIG settings are listed apart in fromPolicyGroup. Settings that device templates and configuration groups only write differently are not reported. Review dropped, changed and secretsChanged before deploying.
Migrating from device templates. vManage's template-to-group conversion creates the groups but not the devices' values, and on 20.18 it leaves defects. Check the groups first with find_config_group_conversion_defects and fix what it reports, then plan the values with plan_config_group_variables. Then move one device at a time with deploy_template_migration: prepare → read the review with the user → deploy → status until healthy → deploy_policy_group for a device with SIG → the next device. Between deploy and deploy_policy_group, a SIG device has no SIG tunnels: vManage deploys a policy group only on a device that runs its configuration group, and the conversion doesn't carry the SIG provider's credentials, so set them in vManage first (sig_ready: true confirms it). Before deploy, undo by removing the device from its groups and re-attaching its template. What prepare records (the device's running config, masked, and its BFD sessions) is kept in VMANAGE_STATE_DIR, so a migration continues after a server restart; without it, deploy_policy_group needs accept_review: true after the SIG settings are checked by hand. Only one write step runs per device at a time, also across server processes (VS Code and other MCP clients each start one); status can follow a running step.
Templates and policy – UX 1.0 (7)
Tool | Description | Key parameters | Example prompt |
| Device (master) templates |
| "List the device templates." |
| Feature templates | – | "How many feature templates exist?" |
| Devices attached to a device template |
| "Which devices use template X?" |
| Definition of a device or feature template |
| "Show the definition of device template X." |
| Policy lists (app, color, prefix, site, SLA, TLOC, VPN, ...) |
| "Show all site lists." |
| Policy definitions of one type |
| "List the app-route policy definitions." |
| Centralized (vSmart), localized (vEdge) and security policies |
| "Which centralized policy is active?" |
Routing and multicast feature templates – UX 1.0 (7)
These tools only act on the routing and multicast template types: cisco_bgp, cisco_ospf, cisco_ospfv3, eigrp, cedge_igmp, cedge_pim, cedge_multicast (IOS XE) and bgp, ospf, igmp, pim, multicast (vEdge); other templates are refused. The write tools follow the same rules as the UX 2.0 write tools. Changing a template does not reconfigure devices until their device templates are pushed again, and vManage refuses to delete a template that a device template still uses.
Tool | Description | Key parameters | Example prompt |
| Routing and multicast feature templates with attached device counts |
| "Which OSPF feature templates exist?" |
| One template's definition and the device templates using it |
| "Show the BGP-Hub template and where it is used." |
| Field definition of a routing template type |
| "What fields does a Cisco OSPFv3 template have?" |
| Write. Create a routing feature template |
| "Create a Cisco BGP template for AS 65001." |
| Write. Replace a routing template (type cannot change) |
| "Change the hello interval in the OSPF-Branch template." |
| Write. Delete a routing template |
| "Delete the unused BGP-Lab template." |
| Write. Copy a routing template under a new name; returns the new ID (not attached anywhere) |
| "Copy the BGP-Hub template as BGP-Hub-Lab." |
Multicast: IGMP, PIM, overlay multicast, MFIB (10)
The ten tools cover all 26 multicast operations in the 26.2 spec: 15 real-time monitoring endpoints (grouped by view), the multicast feature schema, and the 4 read and 6 write operations for multicast features. vManage has UX 2.0 multicast features only in SD-WAN service profiles (profile level and per LAN VPN), so profile_type accepts only service and solution only sdwan. UX 1.0 IGMP, PIM and multicast templates use the routing and multicast template tools. OMP multicast routes stay in get_omp_multicast. The write tools follow the same rules as the OSPF write tools.
Tool | Description | Key parameters | Example prompt |
| IGMP joined groups, interfaces, statistics or summary |
| "Which multicast groups have receivers behind Branch-1?" |
| PIM neighbors, interfaces, RP mappings or statistics |
| "Which RP does Branch-1 use for 239.1.1.1?" |
| SD-WAN overlay multicast: topology, RPF, replicators or PIM tunnels |
| "Which replicator does Branch-2 use?" |
| Multicast forwarding (MFIB): summary, outgoing interface lists or statistics |
| "Is multicast traffic being forwarded on Hub-1?" |
| Multicast features of a UX 2.0 service profile, optionally per LAN VPN feature or one feature |
| "Which multicast settings does Branch-Service configure?" |
| JSON schema vManage expects for a multicast feature body |
| "What fields does a multicast feature have?" |
| Write. Create a multicast feature in a service profile; returns its ID |
| "Create a multicast feature with a static RP of 10.1.1.1." |
| Write. Replace a feature (full definition); with |
| "Enable SPT-only in the multicast feature." |
| Write. Delete a feature; with |
| "Detach the multicast feature from VPN 10." |
| Write. Attach an existing feature to a LAN VPN feature |
| "Attach the multicast feature to the VPN 10 feature." |
IPv6: monitoring, policy objects, trackers (11)
The eleven tools cover all 83 IPv6 operations in the 26.2 spec apart from OSPFv3 (which the OSPF tools cover): 15 real-time monitoring endpoints, 36 UX 1.0 IPv6 policy-object operations (IPv6 prefix lists, data IPv6 prefix lists, IPv6 ACL and IPv6 device-access definitions) and 32 UX 2.0 IPv6 tracker and tracker-group operations (SD-WAN transport profiles and WAN Ethernet/cellular interfaces). The write tools follow the same rules as the other write tools.
Tool | Description | Key parameters | Example prompt |
| IPv6 state by |
| "Which IPv6 routes does Branch-1 learn over OMP in VPN 10?" |
| IPv6 ACL names, associations, counters, policers; SGACL IPv6 counters and permissions |
| "Are IPv6 ACL counters increasing on Hub-1?" |
| UX 1.0 IPv6 prefix lists, data IPv6 prefix lists, |
| "Show the IPv6 ACLs and the CLI they render to." |
| Write. Create an IPv6 list or definition |
| "Create an IPv6 prefix list with 2001:db8:10::/48." |
| Write. Replace a list or definition; |
| "Add a sequence to the IPv6 ACL." |
| Write. Delete by ID, or every prefix list with an info tag |
| "Delete the lab IPv6 prefix lists." |
| IPv6 trackers or tracker groups of a transport profile or one WAN interface, or their body schema |
| "Which IPv6 trackers does the Transport profile use?" |
| Write. Create an IPv6 tracker or tracker group |
| "Create an IPv6 tracker probing 2001:db8::1." |
| Write. Attach a tracker to a WAN Ethernet or cellular interface feature |
| "Attach the IPv6 tracker to GigabitEthernet1." |
| Write. Replace a tracker; with the interface scope, edits its association |
| "Change the IPv6 tracker interval to 30 s." |
| Write. Delete a tracker; with the interface scope, only detaches it |
| "Detach the IPv6 tracker from the cellular interface." |
For IPv6 routes use view: "routes": it works on every platform. IOS XE edges reject the fib view (/device/ip/v6fib is answered only by vEdge and controllers), and their /device/ip/routetable is empty, so routes reads the IETF routing list and keeps only IPv6 entries (prefix and protocol are matched by the server).
CLI add-ons: RIP, RIPng and other CLI – UX 2.0 and UX 1.0 (10)
CLI add-ons carry raw IOS XE configuration that is appended to a device's configuration. They are how protocols without a vManage API, such as RIP (router rip) and RIPng (ipv6 router rip), are configured. UX 2.0 keeps them as config features in CLI feature profiles (SD-WAN and SD-Routing; all 10 operations covered); UX 1.0 as cli-template feature templates.
The write tools follow the same rules as the other write tools (VMANAGE_ALLOW_WRITE=true, confirm: true, validated against the spec). Update tools change only the fields you give and keep the rest. Devices get the change when their configuration group is deployed (UX 2.0) or their device template is pushed again (UX 1.0). vManage does not check the CLI text until then, so preview it with preview_config_group_device_config first.
Tool | Description | Key parameters | Example prompt |
| CLI add-on features of all CLI profiles or one, with their configuration text |
| "Which CLI add-ons configure RIP?" ( |
| One CLI add-on feature |
| "Show the add-on CLI of the Branch CLI profile." |
| Write. Add a CLI add-on feature to a CLI profile |
| "Add RIPng on the LAN to the Branch CLI profile." |
| Write. Change a CLI add-on feature (omitted fields unchanged; |
| "Add network 10.20.0.0 to the RIP add-on." |
| Write. Delete a CLI add-on feature |
| "Remove the RIP add-on from the Branch CLI profile." |
| UX 1.0 CLI add-on templates ( |
| "Which CLI templates contain ipv6 router rip?" |
| One CLI template: configuration text and the device templates using it |
| "Show the RIP-CLI template and where it is used." |
| Write. Create a CLI add-on template |
| "Create a CLI template with RIP version 2 for C8000V." |
| Write. Change a CLI template (type and device models kept) |
| "Replace the config of the RIP-CLI template." |
| Write. Delete a CLI template |
| "Delete the unused RIP-CLI template." |
Cloud OnRamp, administration and applications (8)
Tool | Description | Key parameters | Example prompt |
| Cloud OnRamp for SaaS: sites per application | – | "Cloud OnRamp status for Office 365." |
| Cloud OnRamp gateway sites | – | "Which sites are Cloud OnRamp gateways?" |
| Cloud OnRamp client sites | – | "Which sites are Cloud OnRamp clients?" |
| Cloud OnRamp applications and VPNs | – | "Which SaaS apps are enabled for Cloud OnRamp?" |
| Active alarms |
| "Any active alarms for site 103?" |
| Certificate validity summary | – | "Are any certificates about to expire?" |
| Manager cluster health per node | – | "Is the vManage cluster healthy?" |
| Custom application definitions | – | "List the custom applications." |
Anything without a dedicated tool, such as OSPF, EIGRP, NAT, IPsec/IKE, QoS, multicast, cellular, UTD, statistics or the audit log, is available through search_api_operations and call_api_operation.
Installation
Prerequisites: Node.js 20.12+, npm, and HTTPS access to Catalyst SD-WAN Manager.
git clone https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp.git
cd cisco-catalyst-sdwan-mcp
npm ci
cp .env.example .env # then edit .env (see Configuration)
npm run buildCheck that it starts. Press Ctrl+C to stop it:
npm start
# stderr: Cisco Catalyst SD-WAN MCP Server running on stdioThe command your MCP client will run is:
node /absolute/path/to/cisco-catalyst-sdwan-mcp/build/index.jsRecommended: deploy outside cloud-synced folders
If the project is in OneDrive, iCloud Drive, Dropbox or Google Drive, the sync client can move files to the cloud and the server then fails with ETIMEDOUT when it starts. Deploy a runtime copy instead:
npm run deploy
# Deployed to ~/mcp-servers/catalyst-sdwan-mcp
# MCP command: node ~/mcp-servers/catalyst-sdwan-mcp/build/index.jsnpm run deploy builds the server and copies build/, .env (permissions 600) and the production dependencies to ~/mcp-servers/catalyst-sdwan-mcp. Set CATALYST_SDWAN_MCP_HOME to use another folder. Run it again after every code or .env change, then restart your MCP client.
Configuration
The server reads .env from the project (or deployed) root folder. You can also pass the variables through your MCP client's env settings. Values the client sets take precedence over .env.
Variable | Required | Default | Description |
| Yes | Manager hostname or IP (no | |
| Yes | API user | |
| Yes | API password | |
| No |
| HTTPS port |
| No |
|
|
| No |
|
|
| No | – | The AAA user password |
| No |
| Where |
| No |
| Timeout for real-time device queries (calls with a |
| No |
| Timeout for everything else: inventory, configuration, statistics and login. |
| No |
| Maximum simultaneous requests sent to the Manager |
| No |
| Parallel per-edge queries in a fabric-wide sweep (synced data) |
| No |
| Parallel per-edge queries in a real-time fabric sweep ( |
| No |
| Time budget of a fabric-wide sweep; edges not reached are reported under |
| No |
| Maximum reachable edges per synced sweep (real-time sweeps: 200) |
| No |
|
|
| No | SHA-256 fingerprint of the Manager's certificate (colons optional). Only that certificate is accepted, self-signed or not. Get it with | |
| No | PEM file of an internal CA that signed the Manager's certificate (trusted in addition to Node's CAs) | |
| No |
|
|
| No | Multi-tenant Manager with a provider account: scope every call to this tenant (name, tenant ID, org name or subdomain) | |
| No |
|
|
TLS certificate of the Manager
The server verifies the Manager's certificate on every connection (since 1.1.0). It accepts:
A certificate issued by a CA Node trusts, with a matching host name. This is the default and needs no setting.
A certificate issued by your internal CA: set
VMANAGE_CA_FILEto its PEM file.One specific certificate (typical for a self-signed lab Manager): pin it with
VMANAGE_TLS_FINGERPRINT.npm run fingerprintprints the fingerprint of the certificate the configured Manager presents. Check it against the Manager's own records (Administration → Certificates) before you set it. If the certificate changes, calls fail with "does not match the pinned fingerprint" until you update it.
VMANAGE_TLS_INSECURE=true turns verification off. It exists for throwaway labs only.
Upgrading from 1.0.x, where verification was off: a Manager with a self-signed certificate now needs
VMANAGE_TLS_FINGERPRINT (or VMANAGE_TLS_INSECURE=true), otherwise calls fail with "The TLS certificate of vManage
… is not trusted".
Multi-tenant Managers
Tenant user: set
VMANAGE_HOSTto the tenant's Manager URL and use the tenant's credentials. No other setting is needed.Provider user, one tenant: set
VMANAGE_TENANT. The server gets aVSessionIdfor that tenant after login (POST /tenant/{tenantId}/vsessionid), sends it on every call, and renews it after a re-login or when the Manager rejects it.Provider user, several tenants: set
VMANAGE_ALLOW_TENANT_SWITCH=trueand passtenantper call, e.g. "List unreachable devices for tenant Org A". Withouttenant, calls useVMANAGE_TENANT, or the provider view if that is unset. Switching is off by default so an assistant cannot reach other tenants unless you allow it.
Cached data (device inventory, fabric results, lists) is kept per tenant, so results never cross tenants, and parallel calls for different tenants are independent. Tenant management calls (/tenant...) always run in the provider context.
The OpenAPI spec is cached in ~/.cache/catalyst-sdwan-mcp/ for 24 hours. If the Manager is unreachable, an older cached copy is used. Delete the file to force a refresh after an upgrade.
VMANAGE_HOST=vmanage.example.com
VMANAGE_USERNAME=mcp-readonly
VMANAGE_PASSWORD=change-me
VMANAGE_PORT=443
VMANAGE_USE_JWT=true
VMANAGE_ALLOW_WRITE=falseUse a dedicated Manager account. A read-only user group such as operator is enough unless you plan to enable writes.
Integrating with MCP clients
In every example below, replace /absolute/path/to/build/index.js with your path:
~/mcp-servers/catalyst-sdwan-mcp/build/index.js(expanded) if you usednpm run deployotherwise
<project>/build/index.js
On Windows use forward slashes (C:/mcp/catalyst-sdwan-mcp/build/index.js) or escaped backslashes in JSON. Clients do not expand ~, so always give the full path.
OpenChamber / OpenCode
OpenChamber runs on OpenCode, so MCP servers are configured in OpenCode's config. The desktop app bundles OpenCode 2.
Add the server to a project config (
opencode.jsonin the folder you open in OpenChamber) or to the global config (~/.config/opencode/opencode.json).OpenCode 2.x (OpenChamber 2.x): servers go under
mcp.servers:{ "$schema": "https://opencode.ai/config.json", "mcp": { "servers": { "catalyst-sdwan": { "type": "local", "command": ["node", "/absolute/path/to/build/index.js"], "timeout": { "startup": 60000 } } } } }Or add it from the CLI. Add
--globalto make it available in every project:opencode mcp add catalyst-sdwan -- node /absolute/path/to/build/index.jsOpenCode 1.x: servers go directly under
mcpand useenabled:{ "$schema": "https://opencode.ai/config.json", "mcp": { "catalyst-sdwan": { "type": "local", "command": ["node", "/absolute/path/to/build/index.js"], "enabled": true, "timeout": 60000 } } }Restart OpenChamber completely (macOS:
Cmd+Q, then reopen).Verify with
/mcpsin a session, or from a terminal in the project folder. Use the OpenCode CLI that matches your OpenChamber; the desktop app's copy on macOS is:/Applications/OpenChamber.app/Contents/Resources/opencode-cli/opencode mcp list # ✓ catalyst-sdwan connected
The message "This file still uses the OpenCode 1 format" means the config uses the 1.x layout. Move the server under mcp.servers as shown above.
Visual Studio Code (GitHub Copilot)
Requires VS Code with GitHub Copilot Chat in Agent mode.
Create
.vscode/mcp.jsonin your workspace for a single project, or run MCP: Open User Configuration from the Command Palette for all workspaces:{ "servers": { "catalyst-sdwan": { "type": "stdio", "command": "node", "args": ["/absolute/path/to/build/index.js"] } } }To keep the password out of files, let VS Code prompt for it. Values in
envoverride.env:{ "inputs": [ { "type": "promptString", "id": "vmanage-password", "description": "vManage password", "password": true } ], "servers": { "catalyst-sdwan": { "type": "stdio", "command": "node", "args": ["/absolute/path/to/build/index.js"], "env": { "VMANAGE_HOST": "vmanage.example.com", "VMANAGE_USERNAME": "mcp-readonly", "VMANAGE_PASSWORD": "${input:vmanage-password}" } } } }If the server lives in the workspace you have open, you can use a relative path. The server then reads
.envfrom the project root:{ "servers": { "catalyst-sdwan": { "type": "stdio", "command": "node", "args": ["${workspaceFolder}/build/index.js"] } } }Alternatively, from a terminal:
code --add-mcp '{"name":"catalyst-sdwan","command":"node","args":["/absolute/path/to/build/index.js"]}'Start the server: open
mcp.jsonand click Start above the server, or run MCP: List Servers.In Copilot Chat, switch to Agent mode, open the tools picker and make sure the
catalyst-sdwantools are enabled.
Visual Studio 2022
Requires Visual Studio 2022 17.14 or later with GitHub Copilot.
Create
.mcp.jsonin your solution folder, or%USERPROFILE%\.mcp.jsonfor all solutions:{ "servers": { "catalyst-sdwan": { "type": "stdio", "command": "node", "args": ["C:/mcp/catalyst-sdwan-mcp/build/index.js"] } } }Open GitHub Copilot Chat, select Agent mode, click the tools icon and enable the
catalyst-sdwantools.
Cursor
Edit
~/.cursor/mcp.json(all projects) or.cursor/mcp.json(one project), or use Settings → MCP → Add new MCP server:{ "mcpServers": { "catalyst-sdwan": { "command": "node", "args": ["/absolute/path/to/build/index.js"] } } }Optionally add
"env": { "VMANAGE_HOST": "...", ... }instead of using.env.Open Settings → MCP and check that
catalyst-sdwanshows a green status and lists its tools.Use the tools from the Agent chat.
Claude Desktop
Open Settings → Developer → Edit Config, or edit the file directly:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
{ "mcpServers": { "catalyst-sdwan": { "command": "node", "args": ["/absolute/path/to/build/index.js"] } } }Restart Claude Desktop. The tools appear under the tools (hammer) icon in the chat box.
Claude Code
claude mcp add catalyst-sdwan --scope user -- node /absolute/path/to/build/index.js
claude mcp listWindsurf
Edit ~/.codeium/windsurf/mcp_config.json, then refresh the MCP servers in Cascade:
{
"mcpServers": {
"catalyst-sdwan": {
"command": "node",
"args": ["/absolute/path/to/build/index.js"]
}
}
}Docker
Build the image:
docker build -t catalyst-sdwan-mcp:latest .MCP clients start the container per session over stdio. Pass the settings with --env-file; the image never contains .env. Example for Cursor or Claude Desktop:
{
"mcpServers": {
"catalyst-sdwan": {
"command": "docker",
"args": ["run", "-i", "--rm", "--env-file", "/absolute/path/to/.env", "catalyst-sdwan-mcp:latest"]
}
}
}Example for VS Code (.vscode/mcp.json):
{
"servers": {
"catalyst-sdwan": {
"type": "stdio",
"command": "docker",
"args": ["run", "-i", "--rm", "--env-file", "/absolute/path/to/.env", "catalyst-sdwan-mcp:latest"]
}
}
}Example for OpenCode 2.x / OpenChamber (opencode.json):
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"servers": {
"catalyst-sdwan": {
"type": "local",
"command": ["docker", "run", "-i", "--rm", "--env-file", "/absolute/path/to/.env", "catalyst-sdwan-mcp:latest"]
}
}
}
}Examples
Sample session
Representative answers from a lab fabric (Manager 26.2.1, Catalyst 8000V edges). Names and addresses are anonymized.
"How many devices are in the SD-WAN fabric?" → list_devices
Type | Count | Reachable |
vManage | 1 | 1 |
vSmart | 2 | 2 |
vBond | 1 | 1 |
WAN edge | 13 | 13 |
Total: 17 devices, all reachable.
"List the total number of TLOCs on Branch-1." → get_control_wan_interfaces, get_omp_tlocs
Color | Interface | Encap | State |
| GigabitEthernet1 | IPsec | up |
| GigabitEthernet2 | IPsec | up |
Total: 2 TLOCs, each advertised over OMP to both Controllers.
"How many configuration groups are on vManage, and which one configures the branch sites?" → list_config_groups, get_config_group
6 configuration groups. Example mapping:
Sites | Configuration group |
Hub-1, Hub-2 | Hub-CG |
Branch-1, Branch-2 | Branch-CG (added by tag rule) |
"Is OSPF running on Branch-1?" → get_ospf_interfaces (version: "ospfv2" and "ospfv3"), get_ospf_neighbors
Version | Interface | VPN | Area | Network type | State |
OSPFv2 | GigabitEthernet3 | 10 | 0 | broadcast | DR |
OSPFv3 (IPv6) | GigabitEthernet3 | 10 | 0 | point-to-point | point-to-point |
OSPF runs in service VPN 10 with one OSPFv2 neighbor on GigabitEthernet3. get_ospf_process returns no rows on this device, so the answer is based on interfaces and neighbors.
"Show the BGP neighbors and routes of Branch-1, and the BGP features in its service profile." → get_bgp_neighbors, get_bgp_routes, get_bgp_config
2 BGP neighbors, 16 BGP routes; the service profile contains 2 BGP features.
Natural-language prompts
Ask your assistant | Tools it uses |
"List all SD-WAN devices with hostname, type, model, system IP, site ID, reachability and version." |
|
"Give me an overview of the UX 2.0 configuration: which configuration groups are out of sync or failed?" |
|
"Which devices are in configuration group Branch-CG, and what are their variable values?" |
|
"What would configuration group Branch-CG change on Branch-1 if I deployed it now?" |
|
"What would policy group EMEA-Policy-Group change on EMEA-Paris?" |
|
"Which settings would deploying Branch-CG drop or change on Branch-1?" |
|
"Add Branch-3 to Branch-CG, set its variables, show me the diff, then deploy." (writes enabled) |
|
"Show the features in the Branch-Transport transport profile." |
|
"Which sites are in the network hierarchy, and what is under the EMEA region?" |
|
"Which Cyber Vision centers are configured, and add CV-1 at 10.10.10.10." (writes enabled for the add) |
|
"Which devices are unreachable, and what do their control connection histories show?" |
|
"Show the OMP routes that Branch-1 receives in VPN 10." |
|
"Which TLOCs does Branch-1 advertise, and are its BFD sessions up?" |
|
"Give me a fabric-wide control-plane summary: control connections and OMP peers per device." |
|
"How many WAN edges are authorized on the validator?" |
|
"Show OSPF neighbors on Branch-1." |
|
"Which interfaces run OSPFv3 on Branch-1, and in which area?" |
|
"Show the external LSAs in the OSPF database of Hub-1." |
|
"Which BGP neighbors does Hub-1 have in VPN 10, and which routes does it learn from 198.51.100.9?" |
|
"Which BGP and OSPF features does the Branch-Service profile contain, and which VPNs use them?" |
|
"What fields do I need to create a BGP feature in a transport profile?" |
|
"Create a BGP feature for AS 65001 in Branch-Service and attach it to the VPN 10 feature." (writes enabled) |
|
"Detach the OSPFv3 IPv6 feature from VPN 10 and delete it." (writes enabled) |
|
"Which BGP, OSPF and OSPFv3 feature templates exist, and which device templates use them?" |
|
"Copy the BGP-Hub template as BGP-Hub-Lab." (writes enabled) |
|
"Is EIGRP running on Branch-3, and does it have feasible successors?" |
|
"Which EIGRP features does Branch-Service contain, and which LAN VPNs use them?" |
|
"Create an EIGRP AS 100 feature in Branch-Service and attach it to the VPN 20 feature." (writes enabled) |
|
"Which EIGRP feature templates exist, and what fields does one have?" |
|
"Which IGMP groups has Branch-1 joined, and which PIM RP does it use?" |
|
"Is multicast traffic forwarded on Hub-1, and through which replicator?" |
|
"Create a multicast feature in Branch-Service and attach it to VPN 10." (writes enabled) |
|
"Which IPv6 routes does Branch-1 learn over OMP in VPN 10?" |
|
"Show the IPv6 neighbor cache and IPv6 interface statistics of Hub-1." |
|
"Which IPv6 prefix lists and IPv6 ACLs exist, and what CLI does the ACL render to?" |
|
"Create an IPv6 tracker and attach it to the WAN interface of the Transport profile." (writes enabled) |
|
"Is RIP or RIPng configured anywhere?" |
|
"Add RIPng to the Branch-CLI profile, redistributing connected routes." (writes enabled) |
|
"Which certificates expire soon, and are there active critical alarms?" |
|
"List the centralized policies and the device templates in use." |
|
Tool calls (JSON arguments)
Received OMP routes in one VPN:
{ "name": "get_omp_routes", "arguments": { "device_id": "Branch-1", "direction": "received", "vpn_id": "10" } }Network hierarchy: all sites, one node by name, path or site ID, and Cyber Vision centers (Global node by default):
{ "name": "get_network_hierarchy", "arguments": { "label": "site", "fields": ["name", "hierarchyPath", "siteId"] } }{ "name": "get_network_hierarchy", "arguments": { "node": "Global/EMEA/France" } }{
"name": "create_hierarchy_cybervision",
"arguments": {
"body": { "data": { "cvCenterInstances": [{ "cvName": { "value": "CV-1" }, "cvAddress": { "value": "10.10.10.10" }, "cvKey": { "value": "<cyber-vision-token>" }, "cvVPNInterface": { "value": 1 } }] } },
"confirm": true
}
}{ "name": "delete_hierarchy_cybervision", "arguments": { "center_name": "CV-1", "confirm": true } }Routing protocol monitoring (BGP with filters, OSPFv3, OSPF database):
{ "name": "get_bgp_neighbors", "arguments": { "device_id": "Hub-1", "vpn_id": "10", "as": "65010" } }{ "name": "get_bgp_routes", "arguments": { "device_id": "Hub-1", "prefix": "10.1.0.0/16" } }{ "name": "get_ospf_neighbors", "arguments": { "device_id": "Branch-1", "version": "ospfv3" } }{ "name": "get_ospf_database", "arguments": { "device_id": "Hub-1", "view": "external" } }{ "name": "get_eigrp_topology", "arguments": { "device_id": "Branch-3" } }EIGRP features exist only in service profiles; create one, then attach it to a LAN VPN feature:
{
"name": "create_eigrp_feature",
"arguments": {
"profile_type": "service",
"profile": "Branch-Service",
"body": { "name": "EIGRP-100", "description": "Branch EIGRP", "data": { "asNum": { "optionType": "global", "value": 100 } } },
"confirm": true
}
}{
"name": "associate_eigrp_feature",
"arguments": { "profile_type": "service", "profile": "Branch-Service", "vpn_feature_id": "<lan-vpn-feature-id>", "feature_id": "<eigrp-feature-id>", "confirm": true }
}UX 2.0 routing features (read):
{ "name": "get_ospf_config", "arguments": { "profile_type": "service", "profile": "Branch-Service", "version": "ospfv3-ipv6" } }{ "name": "get_bgp_config", "arguments": { "solution": "sd-routing", "profile_type": "transport", "profile": "WAN-Transport", "global_vrf": true } }{ "name": "get_bgp_feature_schema", "arguments": { "profile_type": "service", "schema_type": "post" } }UX 2.0 routing features (write; VMANAGE_ALLOW_WRITE=true and user approval). Create the feature, then attach it to a VPN feature with the returned ID. Take the data fields from get_bgp_feature_schema or from an existing feature in get_bgp_config:
{
"name": "create_bgp_feature",
"arguments": {
"profile_type": "service",
"profile": "Branch-Service",
"body": { "name": "BGP-65001", "description": "Branch BGP", "data": { "asNum": { "optionType": "global", "value": 65001 } } },
"confirm": true
}
}{
"name": "associate_bgp_feature",
"arguments": { "profile_type": "service", "profile": "Branch-Service", "vpn_feature_id": "<lan-vpn-feature-id>", "feature_id": "<bgp-feature-id>", "confirm": true }
}{
"name": "delete_ospf_feature",
"arguments": { "profile_type": "service", "profile": "Branch-Service", "version": "ospfv3-ipv6", "vpn_feature_id": "<lan-vpn-feature-id>", "feature_id": "<ospfv3-feature-id>", "confirm": true }
}IPv6 monitoring, policy objects and trackers:
{ "name": "get_ipv6_status", "arguments": { "device_id": "Branch-1", "view": "routes", "vpn_id": "10", "protocol": "omp" } }{ "name": "get_ipv6_status", "arguments": { "device_id": "Branch-1", "view": "omp-received", "count_by": "vpn-id" } }{ "name": "get_ipv6_policy_object", "arguments": { "kind": "acl", "object_id": "<aclv6-definition-id>", "preview": true } }{
"name": "create_ipv6_policy_object",
"arguments": {
"kind": "prefix-list",
"body": { "name": "Branch-v6", "description": "Branch LAN prefixes", "entries": [{ "ipv6Prefix": "2001:db8:10::/48" }] },
"confirm": true
}
}{
"name": "associate_ipv6_tracker",
"arguments": {
"profile": "Transport",
"vpn_feature_id": "<wan-vpn-feature-id>",
"interface_type": "ethernet",
"interface_feature_id": "<wan-interface-feature-id>",
"tracker_id": "<ipv6-tracker-id>",
"confirm": true
}
}Multicast monitoring and configuration:
{ "name": "get_pim_status", "arguments": { "device_id": "Branch-1", "view": "rp-mapping" } }{ "name": "get_mfib", "arguments": { "device_id": "Hub-1", "view": "oil" } }{ "name": "get_multicast_config", "arguments": { "profile_type": "service", "profile": "Branch-Service", "vpn_feature_id": "<lan-vpn-feature-id>" } }CLI add-ons (RIP and RIPng have no dedicated API, so they are configured as CLI). Find where RIP is configured, then add a RIPng block to a UX 2.0 CLI profile:
{ "name": "list_cli_addons", "arguments": { "contains": "router rip" } }{
"name": "create_cli_addon",
"arguments": {
"profile": "Branch-CLI",
"name": "RIPng-LAN",
"description": "RIPng on LAN VPN 10",
"config": "ipv6 router rip RIPNG\n redistribute connected\n!\ninterface GigabitEthernet3\n ipv6 rip RIPNG enable",
"confirm": true
}
}The UX 1.0 equivalent:
{
"name": "create_cli_template",
"arguments": { "name": "RIP-v2", "config": "router rip\n version 2\n network 10.0.0.0\n no auto-summary", "device_types": ["vedge-C8000V"], "confirm": true }
}UX 1.0 routing feature templates:
{ "name": "list_routing_templates", "arguments": { "protocol": "ospfv3" } }{ "name": "get_routing_template_schema", "arguments": { "template_type": "cisco_ospf" } }{ "name": "clone_routing_template", "arguments": { "template_id": "<template-id>", "name": "BGP-Hub-Lab", "description": "Lab copy", "confirm": true } }{
"name": "create_routing_template",
"arguments": {
"body": {
"templateName": "BGP-65001",
"templateDescription": "Branch BGP",
"templateType": "cisco_bgp",
"deviceType": ["vedge-C8000V"],
"templateMinVersion": "15.0.0",
"templateDefinition": { },
"factoryDefault": false
},
"confirm": true
}
}Fill templateDefinition from get_routing_template_schema, or start from an existing template with clone_routing_template and change it with update_routing_template.
Find an API operation, check its parameters, then call it (works for any operation, including those that also have a dedicated tool):
{ "name": "search_api_operations", "arguments": { "query": "ospf neighbor" } }{ "name": "describe_api_operation", "arguments": { "operation_id": "createOSPFNeighbors" } }{ "name": "call_api_operation", "arguments": { "operation_id": "createOSPFNeighbors", "query": { "deviceId": "<system-ip>" }, "max_items": 50 } }Path parameters and statistics queries:
{
"name": "call_api_operation",
"arguments": {
"operation_id": "getMasterTemplateDefinition",
"path_params": { "templateId": "<template-id>" }
}
}{
"name": "call_api_operation",
"arguments": {
"operation_id": "postDocCount_MonitoringAlarmsDetails_1604",
"body": { "query": { "condition": "AND", "rules": [{ "field": "entry_time", "type": "date", "operator": "last_n_hours", "value": ["24"] }] } }
}
}Operation IDs can differ between Manager releases. Use search_api_operations to find the ID on your release.
Statistics .../page operations return results in pages with a scrollId. all_pages: true keeps fetching pages until max_items rows are collected (up to 50 pages):
{
"name": "call_api_operation",
"arguments": {
"operation_id": "getPostStatBulkRawData_MonitoringApplicationAwareRouting_2504",
"query": { "count": 100 },
"body": { "query": { "condition": "AND", "rules": [{ "field": "entry_time", "type": "date", "operator": "last_n_hours", "value": ["1"] }] } },
"all_pages": true,
"max_items": 500
}
}A write operation, when VMANAGE_ALLOW_WRITE=true, after the user has approved it:
{ "name": "call_api_operation", "arguments": { "operation_id": "<write-operation-id>", "body": { }, "confirm": true } }Without confirm: true, or with writes disabled, the server refuses the call and explains why.
Security
Read-only by default. POST, PUT and DELETE operations, and GETs documented as actions, are refused unless
VMANAGE_ALLOW_WRITE=true. Each write call then also needsconfirm: true, which assistants should set only after the user approves. The dedicated write tools are not even listed until writes are enabled.Scoped write tools. The BGP, OSPF and routing template write tools run through the same gate as
call_api_operation: the request is resolved to an operation in the Manager's spec and validated before it is sent. They only reach their own protocol's features or templates; IDs must be UUIDs, and a template of another type (for examplecisco_vpn) is refused. A template's type cannot be changed by an update. Profile and template changes are never deployed to devices by these tools.Blocked endpoints. Operations that issue or expose tokens, passwords, OTPs, credentials or bootstrap configurations are never callable. Neither are file uploads or server-sent event streams.
Validation. Path and query parameters must exist in the spec, required ones must be present, and types and enums are checked. Path values are URL-encoded and
./..are rejected.Redaction and limits. Values of keys such as
password,token,csrfandsessionIdare replaced with***redacted***. List responses are capped (default 200 rows,max_itemsto change) and output stays under 200,000 characters.Masked device configurations. The group previews (
preview_config_group_device_config,preview_group_device_config) replace secret values in the running and rendered configurations with****, in every view: passwords and secrets (including type 5/8/9 hashes, which can be cracked offline), enable and shared secrets, OSPF authentication and MD5 keys, key-chain key strings, IKE pre-shared keys and PSKs, SIG partner and API keys, SNMP communities and SNMPv3 auth/priv passwords. The encryption type is kept (secret 9 ****). Thediffandreviewviews compare the unmasked configurations and mask only the lines they return, so a changed secret is still reported as a change. Route-map communities,crypto key generateand key-chain IDs are not secrets and stay readable. Masking is pattern-based; review a preview before sharing it.TLS. The Manager's certificate is verified on every connection: a trusted CA, your internal CA (
VMANAGE_CA_FILE), or exactly one pinned certificate (VMANAGE_TLS_FINGERPRINT). Turning verification off needsVMANAGE_TLS_INSECURE=trueand logs a warning. With a pinned certificate, TLS sessions are not resumed, so every new connection presents the certificate and is checked.Credentials. Keep
.envout of version control (it is in.gitignore), restrict its permissions (chmod 600 .env), and use a dedicated least-privilege Manager account.Access-level detection is a heuristic. It uses the operationId and spec description. Test against a lab Manager before you enable writes on a production fabric.
Testing and verification
Four test suites check the server. Only npm test runs without a Manager; the others call a real Manager and send read operations only.
Command | Needs a Manager | What it checks | Runs in CI |
| No (simulated vManage) | 344 checks: every tool family, spec coverage of all routing/multicast/IPv6/CLI, configuration/policy/topology group and network-hierarchy operations, write protection, input validation, resilience, multi-tenancy, tool-list size | Yes: Node.js 20, 22 and 24 |
| Yes | 39 control-plane, OMP and Validator calls plus 3 input-validation checks | No |
| Yes | UX 2.0, fabric-wide, paging and response-shaping tools; hostname resolution, parallel calls, error handling, with timings | No |
| Yes (≈25 min) | Every read operation that needs no IDs (≈1,260 on 26.2) plus every dedicated read tool; writes API_COVERAGE.md and api_coverage.csv | No |
npm run build # compile TypeScript
npm test # offline tests against a simulated vManage (no lab needed; runs in CI)
# <edge>, <controller>, <validator>: hostname or system IP of a WAN edge, Controller and Validator in your fabric
npm run test:control-plane -- <edge> <controller> <validator>
npm run test:ux2 -- <edge-hostname>
npm run verify:api -- <edge> <controller> <validator>Offline tests (npm test)
npm test starts a simulated Manager on localhost (HTTPS with a throwaway certificate created by openssl) that serves the real 26.2.1 OpenAPI spec, and drives the real MCP server against it over stdio. GitHub Actions runs it on every push and pull request (.github/workflows/ci.yml).
Area | What is checked |
Tool list | 121 tools on a read-only server with no write tool listed, 163 with |
Client and resilience | Hostname resolution, |
Response shaping |
|
Fabric-wide tools | Health table and Manager deployment detection, BFD and TLOC sweeps: concurrency cap, time budget with resume, overload breaker, synced data re-checked live |
Multi-tenancy | Fixed tenant, per-call tenant switching, |
API catalog | Statistics paging with |
Routing, multicast, IPv6 and CLI | Spec coverage (below), method/path/query/body of every request, per-view filters, read-only previews |
Write protection | Every write tool is refused while |
Input validation | Non-UUID IDs, unknown views/versions/scopes, wrong profile types and solutions, wrong template types, oversized CLI text and empty updates are rejected before any request |
Secret masking | No password, hash, SIG key or SNMP community reaches the assistant in the |
Review view | Dropped, changed, added and default settings sorted with their section; SIG settings apart when a policy group has the configuration group's name; repeated settings (name servers) paired one to one |
Coverage by area
Every one of the 163 tools belongs to one area below. Offline is what npm test checks against the simulated Manager. Live is the suite that runs the tools against a real 26.2.1 Manager. Read tools are verified live; write tools only up to the write gate, because writes are disabled on the lab.
Area | UX | Tools | vManage APIs the tools call | Offline ( | Live |
API catalog | – | 4 | Any of the 4,128 spec operations, validated against the spec | Statistics paging ( |
|
Fabric-wide health, BFD and TLOCs | – | 3 |
| Health table, Manager deployment, sweeps: concurrency cap, time budget with resume, overload breaker, synced data re-checked live |
|
Devices and inventory | – | 5 |
| Hostname resolution, |
|
Control plane, OMP, Validator | – | 28 |
|
|
|
Data plane, interfaces, system | – | 9 |
| Real-time timeout, unknown-device rejection |
|
App-aware routing, flows, statistics | – | 7 |
| – |
|
BGP | 2.0 | 9 |
| Full spec sweep (see next table) |
|
OSPF and OSPFv3 | 2.0 | 10 |
| Full spec sweep |
|
EIGRP | 2.0 | 8 |
| Full spec sweep |
|
Multicast: IGMP, PIM, MFIB | 2.0 | 10 |
| Full spec sweep |
|
IPv6 | 1.0 and 2.0 | 11 |
| Full spec sweep |
|
Configuration groups, policy groups, topology groups | 2.0 | 21 |
| Full spec sweep (40 operations), device-name to UUID resolution, write protection, cache invalidation after a write |
|
Feature profiles and network hierarchy | 2.0 | 6 |
| Full spec sweep of the network hierarchy (4 operations), node lookup by ID, path, site ID and name (ambiguous names refused), |
|
UX 2.0 CLI add-ons | 2.0 | 5 |
| Full spec sweep |
|
Device and feature templates | 1.0 | 4 |
| List timeout |
|
Policies, policy lists, policy definitions | 1.0 | 3 |
| – |
|
Routing and multicast feature templates | 1.0 | 7 |
| Requests, template-type guard |
|
CLI add-on templates | 1.0 | 5 |
| Requests, template-type guard, |
|
Cloud OnRamp and administration | – | 8 |
| – |
|
Total | 163 |
Every write tool (41) is additionally checked offline for refusal while VMANAGE_ALLOW_WRITE=false and without confirm: true, and for the exact method, path and body when allowed. Live, write tools were checked only up to the write gate (writes disabled on the lab).
Spec sweeps
For the areas marked "Full spec sweep", the tests read every operation of the area from the published 26.2.1 spec, call every tool with every scope (solution, profile type, VPN/VRF, interface, version), and fail if an operation is never reached or a tool calls a path that is not in the spec.
OSPF and OSPFv3 share the same 10 tools; the version argument selects the protocol (ospfv2/ospfv3 for monitoring, ospf/ospfv3-ipv4/ospfv3-ipv6 for features). Their 144 spec operations are split into two rows so each protocol's share is visible; the two rows add up to the OSPF total.
Area | Monitoring reads | Configuration reads | Read-only previews | Writes (POST/PUT/DELETE) | Total operations | Tools |
BGP | 3 | 22 | – | 30 | 55 | 9 |
OSPFv2 | 7 | 18 | – | 27 | 52 | 10 (shared with OSPFv3) |
OSPFv3 (IPv4 and IPv6 address families) | 2 | 36 | – | 54 | 92 | Same 10 tools |
EIGRP | 3 | 8 | – | 12 | 23 | 8 |
Multicast | 15 | 5 | – | 6 | 26 | 10 |
IPv6 (without OSPFv3) | 15 | 28 | 4 | 36 | 83 | 11 |
UX 2.0 CLI add-ons | – | 4 | – | 6 | 10 | 5 |
UX 2.0 configuration, policy and topology groups | – | 15 | 5 | 20 | 40 | 21 |
UX 2.0 network hierarchy (Cyber Vision network settings) | – | 2 | – | 2 | 4 | 3 |
Total | 45 | 138 | 9 | 193 | 385 | 74 |
Monitoring reads are real-time device queries (
/device/...).Configuration reads are UX 2.0 feature reads (SD-WAN and SD-Routing service/transport profiles, per VPN/VRF or interface) and UX 1.0 policy-object reads. They include the feature-schema endpoints: 2 for BGP, 1 for multicast and 2 for IPv6 trackers. IPv6 splits into 14 UX 1.0 policy-object reads and 14 UX 2.0 tracker reads.
Read-only previews are POST operations that only render configuration and save nothing:
get_ipv6_policy_objectwithpreview_body(4), the configuration/policy/topology group device previews (3) and the configuration/policy group variable fetches (2). They work with writes disabled.
UX 1.0 template types
The UX 1.0 template tools use vManage's generic feature-template API, so a template's type decides which tool may act on it; any other type is refused:
Tools | Template types accepted |
Routing and multicast template tools (7) | IOS XE: |
CLI add-on template tools (5) |
|
Live tests
test:control-plane and test:ux2 are regression tests against a lab Manager: each prints one PASS/FAIL line per call (with timings for test:ux2) and exits non-zero on any failure.
verify:api calls every read operation that needs no IDs or input through the real MCP server, then every dedicated read tool (looking up a real configuration group, profile and template first). It records each result in API_COVERAGE.md and api_coverage.csv. The reports replace device IDs and sampled group, profile and template names with placeholders such as <edge> and <config-group>, so they can be published. It sends many calls, so run it against a lab Manager.
Results on Catalyst SD-WAN Manager 26.2.1:
Item | Result |
Operations in the spec | 4,128 (2,392 read / 1,672 write / 64 blocked) |
Read operations live-tested ( | 1,261: 1,113 returned data, 148 errors from the Manager or lab (feature not configured, query body required, provider-only role) |
Read tools ( | 113 / 119 verified live. The 6 that need IDs were run by hand: 4 passed; |
Write tools (41) | Verified live only up to the write gate (writes disabled on the lab); their method, path and body are checked offline |
| 42 / 42 passed (39 live calls + 3 input-validation checks) |
| 53 / 53 passed: UX 2.0 groups, profiles and preview, 6 parallel real-time calls, synced data, response shaping, fabric-wide sweeps cross-checked against per-device tools, error handling |
To try individual tools interactively, use the MCP Inspector:
npx @modelcontextprotocol/inspector node /absolute/path/to/build/index.jsSet VMANAGE_ALLOW_WRITE=true in the environment the Inspector passes to the server to see the write tools as well.
Troubleshooting
Symptom | Cause / fix |
| Project is in a cloud-synced folder whose files were moved to the cloud. Run |
| No network path to the Manager (often a disconnected VPN). The server gives up after 10 s instead of hanging. Spec-based tools keep working from the cached spec. |
A tool is missing or behaves like an old version | The client is starting a different copy of the server. Check every config the client reads: for OpenCode, both the project |
Calls take ~2 s each | That is the Manager's own response time per request, even on a reused connection. Prefer the combined tools ( |
| The previous call found vManage unreachable, so calls fail immediately for 10 s instead of each waiting for a timeout. Restore connectivity and retry. |
| The message names the timeout that applied: real-time device queries use |
OpenChamber: "This file still uses the OpenCode 1 format" or "No MCP servers configured" | OpenCode 2 reads only |
|
|
| Fixed in this version (token duration is 1800 s). Rebuild. |
| Set |
| Expected in read-only mode. Enable deliberately, then |
| They are listed only when |
| vManage could not render the group for that device, usually because the device is not associated with the group or is outside the topology group's rules. Check |
| vManage 26.2 keeps network settings (Cyber Vision centers) only on the Global node. Omit |
| Two nodes share that name. Pass the hierarchy path (for example |
No tool to create, rename or delete a region, area or site | The 26.2 API has no such operation (the server refuses operations that are not in the spec). Change the hierarchy in the Manager GUI. |
| IOS XE edges do not answer the |
| The call does not match the spec. Run |
| Some IOS XE releases report nothing there for OSPF in a service VPN. Use |
BGP or OSPF calls on one edge take 30–60 s | Real-time queries are answered by the device itself; a busy edge (high CPU) answers slowly. Narrow with |
| The routing and multicast template tools only act on BGP, OSPF, OSPFv3, EIGRP, IGMP, PIM and multicast templates. Use |
| vManage has UX 2.0 multicast features only in SD-WAN service profiles. |
| vManage has EIGRP features only in service profiles. Use the service profile of the site. |
No RIP or RIPng tool | vManage 26.2 has no RIP/RIPng API. Configure them as CLI with |
| The CLI template tools only act on |
| Check the scope arguments: |
| vManage rejected the body. Build it from |
| Statistics endpoints need a query body even when the spec marks it optional. See the statistics example above. |
| The response was larger than the limit. Continue with |
Node warns about | Comes from your shell environment, not this server. Remove the variable if you don't need it. |
| Pin the certificate: |
| The Manager's certificate changed (renewed or replaced), or the address reaches another server. Check, then update |
Project structure
src/
index.ts # entry point: loads .env, starts stdio server
server.ts # MCP tool definitions and handlers
services/vmanageApi.ts # HTTPS client (undici), JWT/session auth, retries, caching, generic request()
services/apiCatalog.ts # OpenAPI-driven catalog: search, describe, validated calls, path-to-operation matching, paging, access control
services/configReview.ts # group previews: masks secrets in device configurations, sorts the review view
services/configVariables.ts # template-to-group migration: maps template values onto group variables
services/configDefects.ts # template-to-group migration: conversion defects and their fixes
services/templateMigration.ts # template-to-group migration: value planning and the deploy_template_migration steps
services/migrationStore.ts # deploy_template_migration state across restarts (masked) and per-device lock
utils/config.ts # environment configuration
scripts/
deploy.mjs # deploy runtime copy outside cloud-synced folders
test-mock.mjs # offline tests against a simulated vManage (npm test, CI)
test-control-plane.mjs # live regression test
test-ux2.mjs # live UX 2.0 / fabric-wide tools test
verify-api-coverage.mjs # full coverage run and report
.github/workflows/ci.yml # build + offline tests on Node.js 20/22/24
.vscode/mcp.json # VS Code MCP server registration
API_COVERAGE.md, api_coverage.csv # last coverage report
Dockerfile, docker-compose.ymlReferences
License
MIT. See LICENSE.
Available Tools
83 toolscall_api_operationA
Call any vManage API operation by operation_id. Parameters and body are validated against the vManage OpenAPI spec. Read operations run directly; write operations require VMANAGE_ALLOW_WRITE=true on the server and confirm: true (only after the user approves the change).
Inputs: operation_id (required), body, query, confirm, +2 more.
describe_api_operationA
Show the documented parameters, request body schema/example, access level and description for one vManage API operation.
Inputs: operation_id (required).
get_app_log_flow_countB
Get count of packet flows being logged for a device.
Inputs: device_id (required).
get_app_log_flowsC
Get packet flow logging information for a device.
Inputs: device_id (required).
get_app_route_sla_classC
Get SLA class information for application-aware routing on a device.
Inputs: device_id (required).
get_app_route_statisticsB
Get application-aware routing statistics (tunnel stats) for a device.
Inputs: device_id (required).
get_attached_devicesB
Get devices attached to a specific device template.
Inputs: template_id (required).
get_bfd_sessionsB
Get BFD (Bidirectional Forwarding Detection) sessions for a device.
Inputs: device_id (required).
get_bfd_summaryC
Get BFD session summary for a device.
Inputs: device_id (required).
get_bfd_tlocB
Get BFD session summary per TLOC for a device.
Inputs: device_id (required).
get_bgp_neighborsC
Get BGP neighbors for a device.
Inputs: device_id (required).
get_bgp_routesC
Get BGP routes for a device.
Inputs: device_id (required).
get_bgp_summaryC
Get BGP summary for a device.
Inputs: device_id (required).
get_bridge_tableB
Get bridge forwarding table for a device.
Inputs: device_id (required).
get_certificate_summaryB
Get certificate validity summary for devices.
Inputs: no named parameters.
get_cflowd_flowsC
Get cflowd flow information for a device.
Inputs: device_id (required).
get_cflowd_statisticsC
Get cflowd packet statistics for a device.
Inputs: device_id (required).
get_cloudx_appsC
Get CloudExpress apps and VPNs configuration.
Inputs: no named parameters.
get_cloudx_client_listC
Get CloudExpress client/site list.
Inputs: no named parameters.
get_cloudx_gateway_listC
Get CloudExpress gateway list.
Inputs: no named parameters.
get_cloudx_statusB
Get CloudExpress (Cloud OnRamp) status - sites per application.
Inputs: no named parameters.
get_cluster_statusA
Get vManage cluster health status per node.
Inputs: no named parameters.
get_config_groupA
Get one configuration group (by ID or exact name) with its feature profiles and associated devices.
Inputs: config_group (required).
get_config_group_device_variablesB
Get device-specific variable values of a configuration group (all devices, or one device).
Inputs: config_group (required), device.
get_control_affinityC
Get controller group affinity configuration or status for a device.
Inputs: device_id (required), type.
get_control_connectionsB
Get control plane connection status for a device. Shows connections to vSmart/vBond.
Inputs: device_id (required), synced, peer_type, system_ip.
get_control_connections_historyB
Get control connection history for a device (past connection attempts, errors, and down reasons).
Inputs: device_id (required).
get_control_countB
Get fabric-wide control connection counts, optionally for one site.
Inputs: site_id.
get_control_linksB
Fabric-wide: list control connection links between all devices in the given state.
Inputs: state (required).
get_control_local_propertiesB
Get control plane local properties for a device (system-ip, site-id, org name, certificate status, vBond address, max controllers).
Inputs: device_id (required), synced.
get_control_network_summaryB
Fabric-wide: per-device control plane summary (control connections, OMP peers, vSmart peers, reachability).
Inputs: state.
get_control_statisticsC
Get control plane DTLS connection statistics for a device.
Inputs: device_id (required).
get_control_statusB
Fabric-wide: control connection up/down status counts (dashboard view).
Inputs: no named parameters.
get_control_summaryC
Get control plane summary (device count) for a device.
Inputs: device_id (required).
get_control_valid_devicesA
Get the authorized device lists held by a Controller (vSmart). Use a controller system-ip.
Inputs: device_id (required), list.
get_control_wan_interfacesB
Get control plane WAN interface (TLOC) state for a device: color, public/private IP and port, control connection counts.
Inputs: device_id (required), synced.
get_device_arpB
Get ARP table (IPv4 to MAC mappings) for a device.
Inputs: device_id (required).
get_device_detailsB
Get detailed information for a specific device by device ID or system IP.
Inputs: device_id (required).
get_device_interfacesC
Get interface status and configuration for a device.
Inputs: device_id (required).
get_device_tlocC
Get TLOC (Transport Locator) information for a device.
Inputs: device_id (required).
get_device_vpnC
Get VPN configuration for a device.
Inputs: device_id (required).
get_feature_profileB
Get one UX 2.0 feature profile with its features (parcels): e.g. system (AAA, banner, logging, NTP...), transport (WAN VPN, interfaces, routing), service (LAN VPNs, interfaces, routing).
Inputs: profile (required), profile_type (required), solution.
get_network_connections_summaryA
Fabric-wide: reachable/unreachable counts per device class (vSmart, WAN Edge, vBond, vManage).
Inputs: no named parameters.
get_network_hierarchyA
Get the UX 2.0 network hierarchy (global, regions, areas and sites) used by configuration groups and policies.
Inputs: no named parameters.
get_omp_cloudxC
Get OMP Cloud OnRamp (CloudExpress) routes for a device.
Inputs: device_id (required).
get_omp_linksA
Fabric-wide: list OMP peering links between all devices in the given state.
Inputs: state (required).
get_omp_multicastC
Get OMP multicast routes or multicast auto-discovery entries for a device.
Inputs: device_id (required), type, direction.
get_omp_peersC
Get OMP (Overlay Management Protocol) peers for a device.
Inputs: device_id (required), synced.
get_omp_routesA
Get OMP routes received or advertised by a device. Filter by VPN and/or prefix to limit output.
Inputs: device_id (required), prefix, vpn_id, direction.
get_omp_servicesA
Get OMP service routes (VPN, firewall, IDS, etc.) known to a device.
Inputs: device_id (required).
get_omp_statusA
Fabric-wide: OMP peering up/down status counts (dashboard view).
Inputs: no named parameters.
get_omp_summaryC
Get OMP summary for a device.
Inputs: device_id (required).
get_omp_tlocsC
Get OMP TLOC routes received or advertised by a device.
Inputs: device_id (required), color, direction.
get_policy_groupA
Get one policy group (by ID or exact name) with its profiles and associated devices.
Inputs: policy_group (required).
get_sdwan_statsB
Get SD-WAN statistics (ACL drops, data policy, device metrics) for a device.
Inputs: device_id (required).
get_system_statusA
Get system status (CPU, memory, uptime) for a device.
Inputs: device_id (required).
get_template_definitionC
Get the definition/configuration of a device or feature template.
Inputs: template_id (required), template_type (required).
get_topology_groupA
Get one topology group (by ID or exact name) with its topology profiles.
Inputs: topology_group (required).
get_ux2_overviewA
UX 2.0 configuration overview in one call: configuration groups, policy groups and topology groups with device counts and deployment state (up-to-date / failed / in progress), plus feature profile counts per type.
Inputs: solution.
get_validator_connectionsB
Get connections on a Validator (vBond), current or history. Use the validator system-ip.
Inputs: device_id (required), history.
get_validator_local_propertiesB
Get Validator (vBond) local properties (org name, certificate state, system-ip).
Inputs: device_id (required).
get_validator_proxy_mappingC
Get Validator (vBond) NAT/proxy mapping table.
Inputs: device_id (required).
get_validator_statisticsC
Get Validator (vBond) DTLS/control packet statistics.
Inputs: device_id (required).
get_validator_summaryC
Get Validator (vBond) connection summary.
Inputs: device_id (required).
get_validator_valid_devicesB
Get the authorized device lists held by a Validator (vBond).
Inputs: device_id (required), list.
list_alarmsC
List active alarms from vManage.
Inputs: limit, site_id.
list_api_categoriesA
List all vManage API categories (from the connected vManage OpenAPI spec) with counts of read, write and blocked operations. Start here to explore APIs not covered by a dedicated tool.
Inputs: filter.
list_config_groupsB
List UX 2.0 configuration groups with their feature profiles, device counts and deployment state.
Inputs: name, solution.
list_controllersA
List vManage, vSmart, and vBond controllers in the fabric.
Inputs: no named parameters.
list_custom_appsB
List custom application definitions.
Inputs: no named parameters.
list_devicesA
List all devices in the SD-WAN fabric (vEdges, vSmarts, vBonds, vManage). Returns hostname, system-ip, device-type, status, site-id, version.
Inputs: model.
list_device_templatesB
List device templates (master templates) in vManage.
Inputs: feature.
list_feature_profilesA
List UX 2.0 feature profiles. Without profile_type, returns every profile type of the solution (system, transport, service, cli, policy-object, application-priority, embedded-security, ...).
Inputs: solution, profile_type.
list_feature_templatesB
List all feature templates in vManage.
Inputs: no named parameters.
list_policiesC
List centralized (vsmart), localized (vedge) and security policies.
Inputs: policy_type.
list_policy_definitionsB
List policy definitions of one type (ACL, app-route, data, control, etc.).
Inputs: definition_type (required).
list_policy_groupsA
List UX 2.0 policy groups with their profiles, device counts and deployment state.
Inputs: solution.
list_policy_listsB
List policy lists (app, aspath, color, community, data-prefix, etc.).
Inputs: list_type.
list_reachable_devicesA
List devices that are currently reachable in the SD-WAN fabric.
Inputs: no named parameters.
list_topology_groupsB
List UX 2.0 topology groups (hub-and-spoke / mesh topologies) with device counts and state.
Inputs: solution.
list_vedge_inventoryA
List WAN edge inventory (authorized device list) with certificate and validity status.
Inputs: no named parameters.
preview_config_group_device_configA
Read-only: render the configuration a configuration group would push to one device, compared with its running configuration. Shows a line diff by default. Nothing is deployed.
Inputs: device (required), config_group (required), view.
search_api_operationsA
Search every vManage API operation by keywords (matched against path, operationId, category and summary). Returns operation_id values for describe_api_operation / call_api_operation.
Inputs: limit, query, access, method, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 83 tools
Most tools target distinct resources (OMP, BFD, BGP, CloudExpress, config groups), but several fabric-wide control tools overlap heavily (get_control_summary, get_control_status, get_control_count, get_control_network_summary) and OMP has similar summary/status variants. Descriptions help somewhat, but an agent could easily misselect among these near-duplicates.
Names overwhelmingly follow a snake_case verb_noun pattern (list_devices, get_omp_peers, get_bfd_summary), which is easy to scan. Minor deviations appear in generic API tools (search_api_operations, describe_api_operation, call_api_operation) and preview_config_group_device_config, but the convention remains readable.
83 tools is far beyond a reasonable surface for one server and forces agents to sift through many near-duplicate monitoring endpoints. While the SD-WAN domain is broad, the count feels inflated and would benefit from consolidation into aggregate or parameterized tools.
The surface covers a wide range of SD-WAN monitoring domains (devices, control/OMP, BFD, BGP, templates, policies, UX 2.0 groups) and provides a generic API escape hatch for uncovered operations. Some lifecycle gaps remain (most tools are read-only; write coverage relies on call_api_operation), but core observability is well represented.
Maintenance
Related MCP Connectors
Lets AI agents analyze API metrics, request logs, and traces, and manage apps and alerts.
Ask your Quickbase apps in plain language. Read-only by default; writes need human approval.
Deploy, monitor, and manage your OpenClaw AI assistants via natural language.
Ask about your Kodem Security data and act on findings in plain language, with your permissions.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to query HPE Aruba Networking Central data (sites, devices, clients, alerts, events) through natural language.9MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage Cisco Meraki networks through natural language, including organizations, networks, devices, switches, wireless, and appliances.1GPL 3.0
- AlicenseAqualityDmaintenanceEnables AI agents to securely access and query Prisma SD-WAN operational data for inventory, health checks, topology analysis, and policy verification through natural language.275MIT
- AlicenseBqualityDmaintenanceEnables natural language automation of Cisco SD-WAN vManage, including device management, template deployment, policy configuration, monitoring, and software upgrades.2MIT