Cisco vManage MCP Server

Un servidor de solo lectura de Model Context Protocol para Cisco SD-WAN vManage que permite a los clientes de IA consultar el estado de la malla, los dispositivos, los túneles, las sesiones BFD, los pares OMP, las alarmas, las políticas y el estado de la configuración mediante lenguaje natural.

El proyecto está deliberadamente construido alrededor de un límite simple:

Las APIs recopilan datos. Python calcula las señales. El LLM explica la evidencia.

En lugar de pedir a un modelo que improvise conclusiones de red a partir de las respuestas sin procesar de la API, el servidor expone herramientas estructuradas y una capa de correlación determinista. Los servicios Python calculan las señales de salud, el alcance de los fallos, el radio de impacto y las hipótesis de causa raíz jerarquizadas; el cliente de IA se utiliza después para seleccionar herramientas, explicar la evidencia resultante y adaptar el nivel de detalle al operador.

20 herramientas de solo lectura: 16 herramientas de recuperación y 4 flujos de trabajo de diagnóstico.

Proyecto independiente. No es un producto oficial de Cisco ni una integración compatible con Cisco.

Por qué lo construí

La resolución de problemas en SD-WAN a menudo implica moverse entre el estado del dispositivo, las conexiones de control, las sesiones BFD, las alarmas, el rendimiento de los túneles y la información de políticas antes de que surja una imagen útil.

Este proyecto explora cómo la IA puede facilitar la consulta de esos datos operativos sin convertir al modelo de lenguaje en la fuente de verdad. Proporciona acceso en lenguaje natural a la telemetría de vManage, mientras mantiene el razonamiento de red, los controles de seguridad y la procedencia de la evidencia en el código de aplicación normal.

Entre las preguntas habituales se incluyen:

• "¿Cómo está la malla de SD-WAN?"

• "¿Qué sitios se ven afectados por este incidente?"

• "¿Este fallo de dispositivo está aislado o forma parte de un problema más amplio?"

• "¿Está la malla suficientemente estable para un cambio planificado?"

• "Dame un resumen breve del incidente para la dirección y el detalle técnico para ingeniería."

Related MCP server: central-mcp-server

Diseño de la IA

La IA se usa de dos maneras distintas en este proyecto.

IA en tiempo de ejecución

Los clientes MCP, como Claude, pueden seleccionar y llamar a las herramientas del servidor mediante lenguaje natural. El modelo recibe resultados estructurados en lugar de acceso sin restricciones a vManage y no es responsable de calcular las señales de salud de red subyacentes.

El diseño en tiempo de ejecución sigue cinco principios:

1. Las APIs recopilan datos, Python calcula las señales, el LLM explica los resultados.

2. Las conclusiones llevan evidencia. Las señales de salud y diagnóstico hacen referencia a los datos de la API de vManage utilizados para derivarlas.

3. Los resultados parciales son explícitos. Si una fuente falla, la respuesta identifica lo que falta en lugar de presentar una evaluación incompleta como completa.

4. Solo lectura por diseño. La superficie de herramientas actual usa únicamente operaciones GET.

5. Auditarlo todo. Las llamadas a herramientas y la actividad de la API pueden registrarse con los valores sensibles enmascarados.

Desarrollo asistido por IA

El desarrollo asistido por IA se utilizó para acelerar la creación de prototipos, la implementación, la generación de pruebas y la iteración. La arquitectura, el comportamiento de la API de vManage, la lógica de red, las reglas de correlación, los límites de seguridad y las salidas técnicas se validaron de forma independiente mediante pruebas unitarias, respuestas simuladas de la API y pruebas contra el sandbox de SD-WAN de Cisco DevNet.

El objetivo era usar la IA para aumentar la velocidad de la ingeniería, manteniendo un control explícito sobre las partes del sistema donde la corrección, la semántica de red y la seguridad operativa son importantes.

Arquitectura

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"]

Herramientas disponibles

Herramientas de recuperación (16)

Herramientas de diagnóstico (4)

Correlación y diagnóstico

La capa de diagnóstico combina múltiples observaciones de vManage antes de presentar una evaluación. Puede:

• correlacionar bordes WAN inalcanzables con el estado de las conexiones de control y de BFD

• mapear fallos de BFD a condiciones relacionadas con el transporte

• distinguir patrones de fallo a nivel de dispositivo, a nivel de sitio o de toda la malla

• estimar el radio de impacto por sitio y por número de dispositivos afectados

• clasificar hipótesis de causa raíz con confianza y observaciones de apoyo

• identificar cuándo los datos faltantes hacen que una evaluación esté incompleta

Ejemplo:

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

Una hipótesis se presenta como hipótesis. El servidor no trata la correlación como prueba de una causa raíz física.

Salvaguardas operativas

El servidor actual es intencionadamente de solo lectura.

• las 20 herramientas de MCP usan operaciones de solo lectura de la API de vManage

• las anotaciones readOnlyHint: true y destructiveHint: false se exponen a los clientes MCP

• las credenciales provienen de variables de entorno y nunca se devuelven en la salida de las herramientas

• el registro de auditoría enmascara contraseñas y tokens de sesión

• los fallos transitorios se reintentan con backoff exponencial

• la renovación de autenticación es segura para la concurrencia

• la gestión de resultados parciales conserva la evidencia útil cuando una fuente no está disponible

• las descripciones de las herramientas definen qué puede y qué no puede inferir el modelo de un resultado

Gestión de fallos

El cliente distingue los fallos operativos en lugar de reducirlos a errores genéricos:

• RateLimitError

• NotFoundError

• PermissionError

• TimeoutError

• ConnectionError

Para fallos HTTP transitorios, como respuestas 429 y 5xx, las solicitudes se pueden reintentar con backoff exponencial. Si una fuente de datos sigue sin estar disponible, las respuestas de diagnóstico identifican explícitamente la fuente que falta y qué conclusiones pueden estar por lo tanto incompletas.

Estructura del proyecto

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

Inicio rápido

Requires Python 3.11 o superior.

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

Configuración

VMANAGE_VERIFY_SSL=false está pensado para laboratorios y sandbox de DevNet. Habilite la verificación de certificados para entornos de producción.

Uso con 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

Después, consulta la malla en lenguaje natural:

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?

Cualquier cliente compatible con MCP puede usar el servidor. El proyecto se ha probado con clientes basados en Claude y con MCP Inspector.

Pruebas

El repositorio incluye actualmente 46 pruebas unitarias que usan respuestas simuladas de vManage.

La cobertura incluye:

• cálculo de señales de salud

• precedencia de alarmas

• agrupación por sitio

• alcance de fallo: dispositivo vs. sitio vs. malla

• clasificación de hipótesis de causa raíz

• evaluación de la salud de la malla

• comportamiento con resultados parciales

• diagnóstico de dispositivos

• enmascaramiento de auditoría

• mapeo de excepciones y manejo de errores

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

El servidor también se ha probado contra el sandbox de SD-WAN siempre activo de Cisco DevNet con vManage 20.10.1.

Compatibilidad

Ejemplos de flujos de trabajo de operador

Telemetría

La telemetría anónima opcional está deshabilitada por defecto y requiere una aceptación explícita.

Cuando está habilitada, puede registrar:

• nombre de la herramienta

• hash de usuario anónimo

• duración de la ejecución

• éxito/fallo

• versión del servidor

• marca de tiempo

No recopila credenciales, IPs de dispositivos ni nombres de host, contenido de alarmas, cuerpos de respuestas de API, datos de configuración ni otra información de identificación personal.

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

Para mantener la telemetría deshabilitada, no establezca VMANAGE_MCP_TELEMETRY, o establézcala explícitamente en false.

Seguridad

• las credenciales se leen de variables de entorno

• las cookies de sesión permanecen solo en memoria

• las credenciales y tokens se redactan de la salida de auditoría

• los tokens XSRF se renuevan en fallos de autenticación con re-autenticación segura para concurrencia

• ninguna herramienta MCP actual modifica la configuración de vManage

• la verificación SSL se puede habilitar con VMANAGE_VERIFY_SSL=true

Hoja de ruta

El trabajo futuro potencial incluye:

• comparación de instantáneas previas y posteriores al cambio

• trazado de rutas de overlay con conocimiento de topología

• tendencias de rendimiento de SLA y rutas de aplicación

• alertas basadas en eventos

• correlación entre dominios con otros sistemas de observabilidad y seguridad de red

• runbooks de diagnóstico automatizados construidos a partir de herramientas restringidas

• pruebas de rendimiento de CML y malla a mayor escala

Cualquier capacidad de escritura futura requeriría un modelo de seguridad separado en lugar de simplemente extender el conjunto de herramientas de solo lectura actual.

Licencia

Licenciado bajo la Licencia Apache 2.0.

Agradecimientos

• Cisco DevNet por el sandbox de SD-WAN utilizado para las pruebas de integración

• Model Context Protocol y las herramientas MCP de Python utilizadas para exponer el servidor

Contribuciones

Las incidencias y solicitudes de extracción son bienvenidas donde el acceso al repositorio lo permita. Las herramientas nuevas o modificadas deben incluir pruebas unitarias, preservar el modelo de seguridad de solo lectura a menos que se diseñen explícitamente de otra manera, y mantener la lógica de red determinista fuera de la capa LLM.