catalyst-sdwan-super-mcp

A FastMCP server that exposes the Cisco Catalyst SD-WAN Manager (vManage) REST API as MCP tools, so any MCP-compatible LLM client (Claude Code, Claude Desktop, Cursor, …) can query and manage your SD-WAN overlay in natural language.

Tools are generated dynamically from the official OpenAPI specs — drop in a new spec and the tools rebuild themselves. No per-version Python, no codegen.

📖 Documentation: https://thomaschristory.github.io/catalyst-sdwan-super-mcp/

Quick start

Run it with uvx — no clone, no install. The credentials below are Cisco's public, always-on DevNet sandbox, so this is a true end-to-end trial without a vManage of your own:

VMANAGE_HOST=sandbox-sdwan-2.cisco.com \
VMANAGE_USERNAME=devnetuser VMANAGE_PASSWORD='RG!_Yw919_83' \
  VMANAGE_VERIFY_SSL=false uvx catalyst-sdwan-super-mcp

That boots the server in stdio, read-only mode against sandbox-sdwan-2.cisco.com with adaptive tool splitting on. On first run it auto-fetches the vManage 20.18 OpenAPI spec from Cisco DevNet (the default version). VMANAGE_VERIFY_SSL=false is needed only because the sandbox uses a self-signed certificate — drop it for a production vManage with a valid cert.

Prefer a persistent install?

pipx install catalyst-sdwan-super-mcp      # or: uv tool install catalyst-sdwan-super-mcp
sdwan-mcp --help

Supported vManage versions: 20.15+. Older releases are out of scope — see issue #13.

Add it to your MCP client

Every block below uses the published CLI — no source checkout, no absolute paths to wrangle. The examples target the DevNet sandbox; to use your own vManage, swap in VMANAGE_HOST (and friends) as shown in Point at your own vManage below.

Claude Code

One command:

claude mcp add sdwan \
  -e VMANAGE_HOST=sandbox-sdwan-2.cisco.com \
  -e VMANAGE_USERNAME=devnetuser \
  -e VMANAGE_PASSWORD='RG!_Yw919_83' \
  -e VMANAGE_VERIFY_SSL=false \
  -- uvx catalyst-sdwan-super-mcp

…or commit a project-local .mcp.json:

{
  "mcpServers": {
    "sdwan": {
      "command": "uvx",
      "args": ["catalyst-sdwan-super-mcp"],
      "env": {
        "VMANAGE_HOST": "sandbox-sdwan-2.cisco.com",
        "VMANAGE_USERNAME": "devnetuser",
        "VMANAGE_PASSWORD": "RG!_Yw919_83",
        "VMANAGE_VERIFY_SSL": "false"
      }
    }
  }
}

Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\), then restart Claude Desktop — sdwan shows up in the MCP indicator:

{
  "mcpServers": {
    "sdwan": {
      "command": "uvx",
      "args": ["catalyst-sdwan-super-mcp"],
      "env": {
        "VMANAGE_HOST": "sandbox-sdwan-2.cisco.com",
        "VMANAGE_USERNAME": "devnetuser",
        "VMANAGE_PASSWORD": "RG!_Yw919_83",
        "VMANAGE_VERIFY_SSL": "false"
      }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project):

{
  "mcpServers": {
    "sdwan": {
      "command": "uvx",
      "args": ["catalyst-sdwan-super-mcp"],
      "env": {
        "VMANAGE_HOST": "sandbox-sdwan-2.cisco.com",
        "VMANAGE_USERNAME": "devnetuser",
        "VMANAGE_PASSWORD": "RG!_Yw919_83",
        "VMANAGE_VERIFY_SSL": "false"
      }
    }
  }
}

Any other stdio client (Cline, Continue, Windsurf, Zed, …)

Same shape everywhere: point the client at the uvx catalyst-sdwan-super-mcp command with VMANAGE_* in the environment.

Tips

• VMANAGE_VERIFY_SSL=false is included because the DevNet sandbox uses a self-signed cert. Drop it (or set true) when pointing at a production vManage with a valid certificate.
• Installed the package? Replace "command": "uvx", "args": ["catalyst-sdwan-super-mcp"] with "command": "sdwan-mcp", "args": [].
• Need writes? Add "--read-write" to args (off by default — see below).
• Network transport / bearer auth? SSE and streamable-HTTP setups live in docs/guides/mcp-clients.md.

Point at your own vManage

The host defaults to the DevNet sandbox. To target your own controller, set VMANAGE_HOST (and VMANAGE_PORT if it isn't 443). With a valid TLS certificate, leave SSL verification on — i.e. drop VMANAGE_VERIFY_SSL entirely or set it to true:

VMANAGE_HOST=vmanage.example.com \
VMANAGE_PORT=443 \
VMANAGE_USERNAME=your-user \
VMANAGE_PASSWORD='your-pass' \
  uvx catalyst-sdwan-super-mcp

The same keys go in any client's env block — e.g. for .mcp.json:

{
  "mcpServers": {
    "sdwan": {
      "command": "uvx",
      "args": ["catalyst-sdwan-super-mcp"],
      "env": {
        "VMANAGE_HOST": "vmanage.example.com",
        "VMANAGE_PORT": "443",
        "VMANAGE_USERNAME": "your-user",
        "VMANAGE_PASSWORD": "your-pass"
      }
    }
  }
}

VMANAGE_USE_JWT (default true; set false for the legacy session login) and VMANAGE_TIMEOUT round out the connection settings. Full reference, including the optional sdwan-mcp.yaml equivalents and ${ENV} interpolation, in the configuration docs.

What you get

• Adaptive tool splitting. A size-driven splitter (max_actions_per_tool, default 150) chops huge OpenAPI sections into right-sized tools — 360 tools on 20.18 RW out of the box, all under the cap. See docs/guides/tool-splitting.md.
• Read-only by default. --read-write registers POST/PUT/DELETE/PATCH explicitly. Write tools are never even put in the LLM's context in RO mode.
• Two auth modes to vManage: JWT (vManage 20.18.1+) and JSESSIONID + XSRF (older).
• Three transports: stdio, SSE, streamable-HTTP. The HTTP transports ship with first-class bearer-token auth (transport.auth.type: bearer) and auto-demote non-loopback binds to 127.0.0.1 when no auth is configured. See docs/guides/mcp-clients.md.
• Response pagination for bulk endpoints. The dispatcher auto-follows scroll and offset endpoints up to a configurable cap and returns a stitched payload with a resumable cursor. See docs/guides/pagination.md.
• Configurable retry + timeout on the httpx client. Transient 5xx and connection errors retry with exponential backoff + jitter; mutating verbs are skipped by default. See docs/reference/configuration.md.
• Auto-fetch specs. Bump sdwan.active_version and the loader pulls the matching spec from developer.cisco.com on startup. Pre-warm explicitly with sdwan-mcp fetch --version <V> or list known versions with sdwan-mcp list-versions. See docs/guides/spec-versions.md.
• Version diff: sdwan-mcp --diff 20.15 20.18 shows added/removed/changed operations before upgrade.
• Docker: multi-stage image, specs mounted as a volume so versions ship without rebuilding.

Project layout

sdwan_mcp/          source package
  server.py         entrypoint, CLI, subcommands (fetch, list-versions)
  config.py         YAML + env interpolation
  loader.py         spec loading, adaptive splitting, indexing
  auth.py           JWT + session login to vManage
  transport_auth.py bearer-token middleware for SSE / streamable-HTTP
  dispatcher.py     httpx client, retry + timeout, param routing
  pagination.py     scroll + offset auto-follow
  fetcher/          live spec ingestion from developer.cisco.com (20.16+)
  tools.py          dynamic MCP tool registration
  diff.py           version diff utility
tests/              pytest suite (respx for HTTP)
docs/               mkdocs-material site, deployed to GitHub Pages
specs/{version}/    OpenAPI YAML/JSON, one folder per vManage version
.github/workflows/  lint, test, docker, docs, release

Architecture quick look

See docs/architecture/overview.md. At a glance:

LLM ──(MCP)──► FastMCP ──► tools.py ──► dispatcher.py ──► httpx ──► vManage
                  ▲                           │
                  │           auth.py ◄───────┘
              loader.py
                  ▲
              specs/{version}/*.{yaml,json}

Develop / hack on it

The PyPI package ships the server only; clone the repo if you want the bundled specs (20.15 / 20.16 / 20.18), the test suite, or the docs site:

git clone https://github.com/thomaschristory/catalyst-sdwan-super-mcp.git
cd catalyst-sdwan-super-mcp
uv sync --group dev --group docs
uv run sdwan-mcp --help
uv run pytest

Contribution guidelines, the release process, and the security posture for fork PRs live in docs/contributing/.

Status

Actively maintained and published on PyPI. Pre-1.0 — under semver that means minor releases may change behavior, so pin a version in production. What's solid today:

• Read-only by default — mutations require an explicit --read-write, the recommended starting posture.
• Dynamic tool generation from the official vManage OpenAPI specs (20.15 / 20.16 / 20.18), with on-demand auto-fetch for newer versions.
• JWT and session auth to vManage; stdio, SSE, and streamable-HTTP transports, with bearer-token auth on the HTTP ones.
• Response pagination, configurable retry/timeout, and an opt-in debug capture of the upstream exchange for diagnosing opaque vManage errors.

Releases are tagged on PyPI and recorded in CHANGELOG.md; open work is on the issue tracker. Contributions welcome.

License: Apache 2.0.