Cisco SD-WAN MCP Server

cisco-sdwan-mcp is an MCP server for Cisco Catalyst SD-WAN Manager (vManage), built with FastMCP.

It gives an LLM client a working view of your SD-WAN fabric — inventory, device health, control and data plane state, alarms, path quality, templates and policies — so you can ask "why is the Frankfurt branch down?" and get an answer backed by real controller data instead of a guess.

Read-only by default. The configuration-changing tools are not registered unless you explicitly enable them, and even then every call requires a human to approve it.

Contents

• What you get
• Quickstart
• Configuration
• Write protection
• Tool reference
• Prompts
• Resources
• Connecting an MCP client
• Transports
• Authenticating MCP clients
• Docker
• Deploying
• Adding your own tools
• Testing
• Troubleshooting
• Project structure

What you get

Plus four workflow prompts and three resources.

Three design decisions are worth knowing up front, because they shape every tool:

• Responses are projected, not dumped. A vManage device record carries 60+ fields; a 200-device fabric would bury a model's context. Each tool returns the fields that answer the question and accepts detailed=true when you want everything.
• Counts always accompany results. Every list reports count (what matched) alongside returned (what you got), so "3 devices are down" is never confused with "3 devices are down in the first 100 I looked at".
• Failures come back as answers. A wrong password, an unreachable controller or an unknown hostname returns a readable message — often with the valid options — rather than raising. The model can then correct itself or tell you exactly what to fix.

Quickstart

Prerequisites

• Python 3.11+
• uv (recommended) or pip
• A reachable Cisco Catalyst SD-WAN Manager (vManage) and an account on it

Make a dedicated vManage account. Give it a read-only role to start. The account's privileges are the real security boundary — see Write protection.

Install

From PyPI, if you only want to run it:

uvx cisco-sdwan-mcp        # no install, run it straight
pip install cisco-sdwan-mcp

From a checkout, if you want to change it:

git clone https://github.com/pcDamasceno/cisco-sdwan-mcp.git
cd cisco-sdwan-mcp

# with uv (recommended)
uv sync --extra dev

# with pip
pip install -e ".[dev]"

Configure

cp .env.example .env

The three settings you must fill in:

SDWAN_VMANAGE_URL=https://vmanage.example.com:8443
SDWAN_USERNAME=automation-readonly
SDWAN_PASSWORD=...

The server reads .env from the repository root at startup — set SDWAN_ENV_FILE to load a different file. Variables already present in the environment (compose env_file, Kubernetes secrets) are never overwritten by it, and the startup log names the file it used.

Run

uv run python -m cisco_sdwan_mcp.server        # or: python -m cisco_sdwan_mcp.server

The server starts over HTTP on 0.0.0.0:8000. The MCP endpoint is at http://localhost:8000/mcp, a health probe at http://localhost:8000/healthz, and this README at http://localhost:8000/.

Startup logs confirm what it will talk to before any client connects:

INFO  cisco_sdwan_mcp.server: vManage controller: vmanage.example.com:8443 (user automation-readonly, TLS verify: True)
INFO  cisco_sdwan_mcp.server: Write tools: disabled (read-only)

First call

Point an MCP client at it (see Connecting an MCP client) and ask for get_fabric_summary. It is one round trip and exercises authentication, TLS and reachability at once:

{
  "total_devices": 42,
  "by_type": {"vedge": 38, "vsmart": 2, "vbond": 1, "vmanage": 1},
  "by_reachability": {"reachable": 40, "unreachable": 2},
  "unreachable_count": 2,
  "unreachable_devices": [{"host-name": "BR2-EDGE1", "system-ip": "10.0.0.12", "site-id": "1002"}]
}

Configuration

Everything is environment-driven; .env.example is the annotated reference.

vManage connection

Server

SDWAN_USERNAME/SDWAN_PASSWORD authenticate this server to vManage. MCP_AUTH governs how clients authenticate to this server. They are unrelated, and you generally want both.

TLS

vManage very often presents a self-signed or private-CA certificate. In descending order of preference:

1. Point SDWAN_CA_BUNDLE at the controller's CA — verification stays on.
2. Add the CA to certificates/, which the Docker build installs into the container trust store automatically.
3. Only as a last resort, on a lab you control, set SDWAN_VERIFY_SSL=false. The server logs a warning naming the host each time it does this, because it means anything on the path can read the credentials.

Write protection

The tools that change configuration are gated twice.

Gate 1 — registration. With SDWAN_ENABLE_WRITES unset or false, the module holding them is never imported. They do not appear in the tool list, so a model cannot call them by mistake, misinterpretation or prompt injection. The server is read-only by construction, not by policy.

Gate 2 — confirmation. With writes enabled, each call still asks the user through MCP elicitation, naming the template or policy and the devices affected, before anything reaches vManage. Clients that do not implement elicitation cannot silently proceed — the call is refused unless the caller passes confirm=true, which puts the decision in a human's hands either way.

SDWAN_ENABLE_WRITES=true uv run python -m cisco_sdwan_mcp.server

WARNING cisco_sdwan_mcp.tools: SDWAN_ENABLE_WRITES=true — configuration-changing tools are registered.
                   Each one still requires explicit user confirmation before it runs.

The vManage account is the real boundary. SDWAN_ENABLE_WRITES controls which tools exist in this server; it does nothing about what the account can do through any other path. If a change must be impossible, use a read-only vManage role — do not rely on this flag alone.

vManage applies configuration asynchronously: a write returns a task_id, meaning accepted, not applied. Poll get_task_status(task_id) until it reports done.

The intended flow for a template push, with a review step in the middle:

list_device_templates          → find the template
get_device_template            → see what it configures and who has it
get_template_input_variables   → the exact per-device values (read-only preview)
check_device_health            → never push to an already-broken device
attach_device_template         → asks for approval, returns a task_id
get_task_status                → confirm it actually landed

And for a config-group fabric, where edits and deploys are separate steps:

get_device_config_group          → which group owns the device
get_feature_profile / get_parcel → find the parcel and its current values
get_parcel_schema                → which parcel a setting lives in, and its shape
update_parcel                    → asks for approval; changes intent only
get_device_running_config        → snapshot before the push
deploy_config_group              → asks for approval, returns a task_id
get_task_status                  → confirm it landed, then re-diff the running config

Tool reference

Every tool takes limit (cap on records) and most take detailed (return all vManage fields instead of the summary set).

Inventory

Device health

These poll the device through vManage, so they reflect live state but cost a round trip to the edge. Prefer check_device_health over three separate calls.

Alarms and events

Path quality

These read vManage's statistics database — fast, but only as fresh as the last collection cycle (30 minutes on most deployments). For live state, use the device health tools.

Templates and policy

Config groups and feature profiles

The UX-2.0 configuration model: a config group bundles feature profiles (system, transport, service, cli, policy-object), each profile holds parcels — the actual configuration payloads — and a device belongs to at most one group. On a fabric managed this way the template endpoints report nothing useful; these tools are the equivalent surface. vManage reports membership on the WAN-edge inventory as "managed-by": "Config-Group <name>", which is also what get_device and list_inventory surface.

With writes enabled, the config-group counterparts to a template push are update_parcel (edit structured knobs read-modify-write), update_cli_addon_config (append/replace raw IOS-XE lines in a CLI add-on profile, returns a diff) and deploy_config_group (push the group to named member devices — the only step that touches production). Edits mark members configGroupUpToDate: false until deployed. attach_device_template refuses devices a config group manages, so the two configuration models cannot fight over a device.

Prompts

Reusable workflows that encode the order an engineer actually works in — control plane before data plane, evidence before conclusions.

Resources

Connecting an MCP client

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "cisco-sdwan": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

VS Code (GitHub Copilot) — .vscode/mcp.json

{
  "servers": {
    "cisco-sdwan": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

With token auth enabled

{
  "mcpServers": {
    "cisco-sdwan": {
      "url": "http://localhost:8000/mcp",
      "headers": { "Authorization": "Bearer dev-token" }
    }
  }
}

With an OAuth mode (github, google, oauth-proxy, …) no header is needed — MCP clients discover the flow and open the login screen themselves.

stdio (local subprocess)

From PyPI — nothing to clone, uvx fetches the package on first run:

{
  "mcpServers": {
    "cisco-sdwan": {
      "command": "uvx",
      "args": ["cisco-sdwan-mcp"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "SDWAN_VMANAGE_URL": "https://vmanage.example.com:8443",
        "SDWAN_USERNAME": "automation-readonly",
        "SDWAN_PASSWORD": "..."
      }
    }
  }
}

From a checkout:

{
  "mcpServers": {
    "cisco-sdwan": {
      "command": "uv",
      "args": ["run", "python", "-m", "cisco_sdwan_mcp.server"],
      "cwd": "/absolute/path/to/cisco-sdwan-mcp",
      "env": {
        "MCP_TRANSPORT": "stdio",
        "SDWAN_VMANAGE_URL": "https://vmanage.example.com:8443",
        "SDWAN_USERNAME": "automation-readonly",
        "SDWAN_PASSWORD": "..."
      }
    }
  }
}

Transports: HTTP vs stdio

• HTTP (default) — the deployment transport. Serves many clients concurrently, works behind load balancers, and is the only transport where MCP_AUTH applies. Everything in deploy/ assumes it.
• stdio — for local single-user use where a desktop client spawns the server as a subprocess. No network listener, so MCP_HOST/MCP_PORT and MCP_AUTH do not apply; the process is secured by your OS user.

MCP_TRANSPORT=stdio uv run python -m cisco_sdwan_mcp.server

Deploying anywhere or serving multiple users → HTTP. One client on your own machine → either works.

Authenticating MCP clients

Authentication of clients to this server is off by default and selected at startup with MCP_AUTH. The factory lives in cisco_sdwan_mcp/auth.py; all modes are backed by FastMCP's built-in providers.

# Development tokens (never in production — tokens sit in plain env vars)
MCP_AUTH=static MCP_AUTH_STATIC_TOKENS=dev-token uv run python -m cisco_sdwan_mcp.server

# JWT via your IdP's JWKS endpoint
MCP_AUTH=jwt
MCP_AUTH_JWKS_URI=https://idp.example.com/realms/main/protocol/openid-connect/certs
MCP_AUTH_ISSUER=https://idp.example.com/realms/main
MCP_AUTH_AUDIENCE=cisco-sdwan-mcp

The full variable reference for every mode is in .env.example.

Notes:

• Auth applies to the HTTP transport only.
• /healthz and / stay public — probes and humans don't carry tokens; the MCP endpoint returns 401 without a valid token.
• OAuth flows require HTTPS on the public URL in production.
• To add your own scheme, write a builder in cisco_sdwan_mcp/auth.py and register it in _BUILDERS (provider docs).

A server exposing your WAN topology should not run MCP_AUTH=none on a reachable network. See deploy/README.md.

Docker

cp .env.example .env      # fill in vManage URL and credentials
docker compose up -d --build

Or manually:

docker build -t cisco-sdwan-mcp .
docker run -p 8000:8000 \
  -e SDWAN_VMANAGE_URL=https://vmanage.example.com:8443 \
  -e SDWAN_USERNAME=automation-readonly \
  -e SDWAN_PASSWORD=... \
  cisco-sdwan-mcp

Helper scripts build the image, replace any container of the same name, and start the server at http://localhost:8000/mcp, passing your .env through:

bash scripts/run_docker.sh          # Linux/macOS
.\scripts\run_docker.ps1            # Windows PowerShell

The image includes a HEALTHCHECK against /healthz, so docker ps shows container health out of the box.

Corporate CA certificates

Drop any .crt/.pem root CA files into certificates/. The build adds them to the container trust store and runs update-ca-certificates automatically — which covers both a TLS-intercepting proxy and a vManage certificate signed by your internal CA. Leave the directory empty if you don't need it.

For a proxy, HTTP_PROXY/HTTPS_PROXY/NO_PROXY are predefined Docker build args and need no Dockerfile edits:

docker build --build-arg HTTPS_PROXY=http://proxy.example.com:8080 -t cisco-sdwan-mcp .
docker run -p 8000:8000 -e HTTPS_PROXY=http://proxy.example.com:8080 cisco-sdwan-mcp

Deploying

The container is a plain HTTP server on port 8000 with a /healthz probe, so it runs anywhere. deploy/ ships raw Kubernetes manifests, a Helm chart, a Styrmin driver and a Cloud Run service definition — see deploy/README.md for full walkthroughs, including the SD-WAN-specific parts: reaching a management-network controller from the cloud, private-CA handling, and vManage's per-account session limits.

kubectl apply -k deploy/kubernetes

helm install sdwan-mcp oci://ghcr.io/pcdamasceno/charts/cisco-sdwan-mcp \
  --set sdwan.vmanageUrl=https://vmanage.example.com:8443

gcloud run services replace deploy/cloud-run-service.yaml --region europe-west3

This repository is also a Styrmin Application Driver — driver.styrmin.yml and values.j2.yml at the root are what Styrmin reads when it clones it. See deploy/styrmin.md.

/healthz deliberately does not check vManage. A brief controller outage should not restart pods — tools report the problem per call, and the server recovers on its own.

Adding your own tools

Capabilities live in three packages, one module per concern. Each package's __init__.py imports its modules so the decorators run — add a module, add one import line.

# cisco_sdwan_mcp/tools/my_tools.py
from cisco_sdwan_mcp.sdwan.client import get_client
from cisco_sdwan_mcp.sdwan.formatting import envelope, project
from cisco_sdwan_mcp.tools._helpers import resolve_device_id, sdwan_tool


@sdwan_tool
async def get_dhcp_leases(device: str, limit: int = 100) -> dict:
    """Show DHCP leases the device is serving.

    Args:
        device: Hostname, system IP or chassis number.
        limit: Maximum leases to return.
    """
    system_ip = await resolve_device_id(device)
    client = await get_client()
    records = await client.get_data(
        "/dataservice/device/dhcp/server", {"deviceId": system_ip}
    )
    fields = ("ifname", "address", "client-id", "state", "expires")
    return envelope(project(records, fields), limit=limit, device=device)

Then add my_tools to the import list in cisco_sdwan_mcp/tools/__init__.py.

Use @sdwan_tool rather than @mcp.tool — it registers the tool and converts SD-WAN failures into a readable {"error", "message"} result. Reach for the shared helpers rather than reimplementing them:

The docstring is what the model reads to decide whether to call your tool — say what question it answers, not just which endpoint it hits. Keep write operations in config_tools.py so the registration gate keeps covering them.

Testing

uv run pytest      # or: pytest

The suite runs against a fake vManage (httpx.MockTransport) rather than a live controller, so it covers the things that actually break in the field:

• the login handshake, including vManage answering a failed login with HTTP 200 and an HTML body
• CSRF token handling, and controllers older than 19.2 that have no token endpoint
• session expiry mid-session → one transparent re-login and retry
• error translation: unreachable host, timeout, 403, non-JSON response
• every read tool's filtering, projection and truncation
• the write gate, verified in a fresh interpreter: the configuration tools are absent without SDWAN_ENABLE_WRITES=true and present with it
• write confirmation: declining, or a client that cannot prompt, must not produce an HTTP call to vManage

tests/conftest.py holds the fake controller; use it as the pattern for your own tools.

Troubleshooting

Set LOG_LEVEL=DEBUG for more detail. Note that vManage error bodies can be verbose — check what yours returns before enabling debug logs in a shared environment.

Project structure

.
├── cisco_sdwan_mcp/
│   ├── mcp.py                    ← Shared FastMCP instance, auth wiring, /healthz
│   ├── auth.py                   ← MCP client authentication factory (MCP_AUTH)
│   ├── server.py                 ← Entry point: transport selection, startup logging
│   ├── sdwan/                    ← vManage integration layer (no MCP knowledge)
│   │   ├── config.py             ← SDWAN_* settings
│   │   ├── client.py             ← Async client: login, CSRF, session recovery
│   │   ├── formatting.py         ← Projection, envelopes, vManage query builder
│   │   └── errors.py             ← Exception hierarchy
│   ├── tools/
│   │   ├── _helpers.py           ← @sdwan_tool, device resolution
│   │   ├── inventory_tools.py    ← Devices and fabric summary
│   │   ├── monitoring_tools.py   ← Control plane, BFD, OMP, interfaces, health
│   │   ├── alarm_tools.py        ← Alarms and events
│   │   ├── statistics_tools.py   ← Tunnel and interface statistics
│   │   ├── template_tools.py     ← Templates and policies (read-only)
│   │   ├── config_group_tools.py ← Config groups, feature profiles, parcels (read-only)
│   │   ├── config_tools.py       ← Template/policy writes — imported only when enabled
│   │   └── config_group_write_tools.py ← Parcel/CLI/deploy writes — same gate
│   ├── resources/sdwan_resources.py
│   └── prompts/sdwan_prompts.py
├── tests/
│   ├── conftest.py               ← Fake vManage (httpx.MockTransport)
│   ├── sample_data.py            ← Representative vManage payloads
│   ├── test_client.py            ← Login, session recovery, error translation
│   ├── test_formatting.py        ← Projection, envelopes, query building
│   ├── test_tools.py             ← Read tools via the in-memory MCP client
│   ├── test_config_tools.py      ← The write confirmation gate
│   ├── test_config_group_tools.py← Config-group reads, writes and the template guardrail
│   ├── test_server.py            ← Registration, the write gate, public routes
│   └── test_auth.py              ← MCP client auth factory
├── deploy/                       ← Kubernetes + Cloud Run
├── scripts/                      ← Docker helper scripts (bash / PowerShell)
├── certificates/                 ← Drop-in CA certificates for Docker builds
├── .env.example                  ← Annotated reference of every variable
├── docker-compose.yml
├── Dockerfile
└── pyproject.toml

Resources

• Cisco Catalyst SD-WAN Manager API docs
• FastMCP documentation
• Model Context Protocol specification

License

MIT