Cisco vManage MCP Server

A read-only Model Context Protocol server for Cisco SD-WAN vManage that lets AI clients query fabric health, devices, tunnels, BFD sessions, OMP peers, alarms, policies and configuration state through natural language.

The project is deliberately built around a simple boundary:

APIs gather facts. Python computes signals. The LLM explains the evidence.

Rather than asking a model to improvise network conclusions from raw API payloads, the server exposes structured tools and a deterministic correlation layer. The Python services compute health signals, failure scope, blast radius and ranked root-cause hypotheses; the AI client is then used to select tools, explain the resulting evidence and adapt the level of detail to the operator.

20 read-only tools: 16 retrieval tools and 4 diagnostic workflows.

Independent project. Not an official Cisco product or Cisco-supported integration.

Why I built it

SD-WAN troubleshooting often means moving between device state, control connections, BFD sessions, alarms, tunnel performance and policy information before a useful picture emerges.

This project explores how AI can make that operational data easier to query without making the language model the source of truth. It provides natural-language access to vManage telemetry while keeping network reasoning, safety controls and evidence provenance in normal application code.

Typical questions include:

• "How is the SD-WAN fabric looking?"

• "Which sites are affected by this incident?"

• "Is this device failure isolated or part of a wider problem?"

• "Is the fabric healthy enough for a planned change?"

• "Give me a short incident summary for leadership and the technical detail for engineering."

Related MCP server: central-mcp-server

AI design

AI is used in two distinct ways in this project.

Runtime AI

MCP clients such as Claude can select and call the server's tools using natural language. The model receives structured results rather than unrestricted access to vManage and is not responsible for calculating the underlying network health signals.

The runtime design follows five principles:

1. APIs gather facts, Python computes signals, LLM explains results.

2. Conclusions carry evidence. Health and diagnostic signals reference the vManage API data used to derive them.

3. Partial results are explicit. If one source fails, the response identifies what is missing rather than presenting an incomplete assessment as complete.

4. Read-only by design. The current tool surface uses GET operations only.

5. Audit everything. Tool calls and API activity can be recorded with sensitive values redacted.

AI-assisted development

AI-assisted development was used to accelerate prototyping, implementation, test generation and iteration. Architecture, vManage API behaviour, networking logic, correlation rules, security boundaries and technical outputs were independently validated through unit tests, mocked API responses and testing against the Cisco DevNet SD-WAN sandbox.

The aim was to use AI to increase engineering velocity while retaining explicit control over the parts of the system where correctness, networking semantics and operational safety matter.

Architecture

flowchart TD
    subgraph Clients["AI Clients"]
        C1["Claude Desktop"]
        C2["Claude Code"]
        C3["Cursor / Other MCP Clients"]
    end

    Clients -- "stdio or HTTP/MCP" --> Server

    subgraph Server["cisco-vmanage-mcp"]
        subgraph Tools["MCP Tools"]
            T1["Device Monitoring"]
            T2["Alarms & Events"]
            T3["Tunnel / BFD / OMP"]
            T4["Interfaces & Control"]
            T5["Diagnostics & Correlation"]
        end

        subgraph Services["Deterministic Python Services"]
            S1["Health Signals"]
            S2["Failure Scope"]
            S3["Root-Cause Hypotheses"]
            S4["Blast Radius"]
            S5["Audit & Evidence"]
        end
    end

    Tools --> Services
    Services --> VMClient["VManageClient\nhttpx + session/auth handling"]
    VMClient --> API["Cisco SD-WAN vManage\n/dataservice/... REST API"]
    API --> Network["SD-WAN Fabric"]

Available tools

Retrieval tools (16)

Diagnostic tools (4)

Correlation and diagnostics

The diagnostic layer combines multiple vManage observations before presenting an assessment. It can:

• correlate unreachable WAN edges with control-connection and BFD state

• map BFD failures to likely transport-related conditions

• distinguish device-level, site-level and fabric-wide failure patterns

• estimate blast radius by site and affected device count

• rank root-cause hypotheses with confidence and supporting observations

• identify when missing data makes an assessment incomplete

Example:

Fabric Health: CRITICAL

Controllers: 3/3 reachable
WAN Edges: 3/4 reachable

Impact scope: site
Site 100 is affected while other sites remain reachable.

Hypothesis: site transport outage
Confidence: high
Evidence:
- edge unreachable
- no BFD sessions
- no control connections
- other sites healthy

Data sources:
- GET /dataservice/device: OK
- GET /dataservice/alarms/count: OK

A hypothesis is presented as a hypothesis. The server does not treat correlation as proof of physical root cause.

Operational guardrails

The current server is intentionally read-only.

• all 20 MCP tools use read-only vManage API operations

• readOnlyHint: true and destructiveHint: false annotations are exposed to MCP clients

• credentials come from environment variables and are never returned in tool output

• audit logging redacts passwords and session tokens

• transient failures use retry with exponential backoff

• authentication refresh is concurrency-safe

• partial-result handling preserves useful evidence when one source is unavailable

• tool descriptions define what the model may and may not infer from a result

Failure handling

The client distinguishes operational failures rather than collapsing them into generic errors:

• RateLimitError

• NotFoundError

• PermissionError

• TimeoutError

• ConnectionError

For transient HTTP failures such as 429 and 5xx responses, requests can be retried with exponential backoff. If one data source remains unavailable, diagnostic responses explicitly identify the missing source and which conclusions may therefore be incomplete.

Project structure

src/cisco_vmanage_mcp/
├── server.py               # MCP server and tool registration
├── client.py               # Async vManage client, auth, retry/backoff
├── services/
│   ├── health_check.py     # Deterministic health signals
│   ├── correlation.py      # Failure scope, hypotheses, blast radius
│   └── audit.py            # Structured audit logging
├── tools/
│   ├── device_tools.py
│   ├── tunnel_tools.py
│   ├── alarm_tools.py
│   ├── health_tools.py
│   ├── policy_tools.py
│   ├── config_tools.py
│   └── diagnostic_tools.py
├── models/                 # Pydantic validation
└── utils/
    ├── errors.py           # Exception taxonomy
    └── formatters.py       # Structured output formatters

tests/
└── test_health_and_correlation.py

Quick start

Requires Python 3.11 or newer.

git clone https://github.com/weegienamja/sdwan-mcp-server.git
cd sdwan-mcp-server

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

cp .env.example .env
# Add your vManage connection details to .env

pytest -v
npx @modelcontextprotocol/inspector python -m cisco_vmanage_mcp

Configuration

VMANAGE_VERIFY_SSL=false is intended for lab and DevNet sandbox use. Enable certificate verification for production environments.

Use with Claude Code

cd sdwan-mcp-server

claude mcp add cisco-vmanage \
  -e VMANAGE_HOST=sandbox-sdwan-2.cisco.com \
  -e VMANAGE_PORT=443 \
  -e VMANAGE_USERNAME=your_username \
  -e VMANAGE_PASSWORD=your_password \
  -e VMANAGE_VERIFY_SSL=false \
  -- .venv/bin/python -m cisco_vmanage_mcp

Then query the fabric in natural language:

How is the SD-WAN fabric looking?
Are there any critical alarms?
Which sites are affected?
Show BFD sessions for this edge.
Is the fabric healthy enough for a planned change?

Any MCP-compatible client can use the server. The project has been exercised with Claude-based clients and the MCP Inspector.

Testing

The repository currently includes 46 unit tests using mocked vManage responses.

Coverage includes:

• health signal computation

• alarm precedence

• site grouping

• device vs site vs fabric-wide failure scope

• root-cause hypothesis ranking

• fabric health assessment

• partial-result behaviour

• device diagnosis

• audit redaction

• exception mapping and error handling

pip install -e ".[dev]"
pytest -v

The server has also been tested against the Cisco DevNet always-on SD-WAN sandbox running vManage 20.10.1.

Compatibility

Example operator workflows

Telemetry

Optional anonymous telemetry is disabled by default and requires explicit opt-in.

When enabled, it can record:

• tool name

• anonymous user hash

• execution duration

• success/failure

• server version

• timestamp

It does not collect credentials, device IPs or hostnames, alarm content, API response bodies, configuration data or other personally identifiable information.

export VMANAGE_MCP_TELEMETRY=true
export SPLUNK_HEC_URL=https://your-splunk-instance:8088/services/collector
export SPLUNK_HEC_TOKEN=your-hec-token

To keep telemetry disabled, do not set VMANAGE_MCP_TELEMETRY, or explicitly set it to false.

Security

• credentials are read from environment variables

• session cookies remain in memory only

• credentials and tokens are redacted from audit output

• XSRF tokens are refreshed on authentication failures with concurrency-safe re-authentication

• no current MCP tool modifies vManage configuration

• SSL verification can be enabled with VMANAGE_VERIFY_SSL=true

Roadmap

Potential future work includes:

• pre-change/post-change snapshot comparison

• topology-aware overlay path tracing

• SLA and application-route performance trending

• event-driven alerting

• cross-domain correlation with other network observability and security systems

• automated diagnostic runbooks built from constrained tools

• larger-scale CML and fabric performance testing

Any future write capability would require a separate safety model rather than simply extending the current read-only toolset.

Licence

Licensed under the Apache License 2.0.

Acknowledgements

• Cisco DevNet for the SD-WAN sandbox used for integration testing

• Model Context Protocol and the Python MCP tooling used to expose the server

Contributing

Issues and pull requests are welcome where repository access permits. New or modified tools should include unit tests, preserve the read-only safety model unless explicitly designed otherwise, and keep deterministic network logic outside the LLM layer.