ArubaOS-CX MCP Server (hpe-cx-mcp)

Un servidor Model Context Protocol (MCP) que expone los conmutadores Aruba CX (AOS-CX) a agentes de IA compatibles con MCP (Claude, VS Code Copilot, etc.). Convierte la API REST del conmutador (/rest/v10.x) y la CLI SSH en un conjunto seleccionado de herramientas seguras y estructuradas para la observabilidad, el diagnóstico y la configuración de un tejido de campus / centro de datos (VLANs, enrutamiento, BGP/OSPF, EVPN-VXLAN, VSX/VSF, acceso de puerto / 802.1X, NAE, ARC…).

El servidor se ejecuta como un contenedor Docker, habla MCP sobre streamable HTTP e incluye autenticación opcional con tokens Bearer con nombre y registro de auditoría JSON.

Inicio rápido

cd cx-mcp

# 1) Provide credentials (git-ignored)
cp .env.example .env                 # then edit: set ARUBA_DEFAULT_PASSWORD (and any source tokens)

# 2) Provide the device list (git-ignored)
cp inventory/inventory.example.yaml inventory/inventory.yaml   # then edit: your switches & IPs

# 3) Build and start
docker compose up -d --build

# 4) Watch it come up
docker compose logs -f hpe-cx-mcp    # wait for "✅ hpe-cx-mcp server is up and running"

El endpoint MCP queda disponible en http://<docker-host>:8002/mcp. Apunte su cliente MCP a esa dirección (ver §9). Los detalles completos y las notas por plataforma se encuentran en §3.

Related MCP server: API-Central

Tabla de contenido

1. Qué hace este servidor

2. Herramientas disponibles

3. Instalación (macOS / Linux / Windows)

4. Volúmenes

5. Variables de entorno

6. Gestión del inventario

7. Seguridad: autenticación Bearer y registro de auditoría

8. Gestión de tokens

9. Conexión de un cliente MCP

1. Qué hace este servidor

• Punto de entrada único a un parque de conmutadores AOS-CX descritos en un inventario.

• Lectura (observación): interfaces, VLANs, tablas de enrutamiento/ARP/MAC, BGP/OSPF/EVPN, túneles VXLAN, estado de pila VSX/VSF, salud del hardware, registros, 802.1X / acceso de puerto, scripts NAE, reconocimiento de aplicaciones (ARC), configuraciones completas.

• Escritura (configuración): servicios VLAN, loopbacks, puertos enrutados, VRFs, BGP, OSPF, EVPN/VXLAN, autenticación de puerto, MAC virtual, ARC — cada uno combinado con una herramienta de verificación verify_*.

• Medidas de seguridad:

  • Por dispositivo access_mode (read-only por defecto; se deniegan las escrituras salvo que un dispositivo sea explícitamente read-write).

  • Operaciones acotadas por sitio (parámetro site) para actuar sobre un grupo de dispositivos.

  • Detección de comandos de escritura por SSH para bloquear cambios de configuración a través de la CLI en bruto en dispositivos de solo lectura.

• Inventario dinámico: fusiona el archivo local con las fuentes de verdad NetBox / Nautobot, con resolución opcional de credenciales mediante HashiCorp Vault.

2. Herramientas disponibles

Las herramientas se agrupan por finalidad. Las herramientas de lectura requieren que un dispositivo sea accesible; las de escritura requieren además que el dispositivo sea read-write.

Inventario y sesiones

Acceso en bruto (vías de escape)

Sistema y hardware

get_system_info, get_hardware_health, get_boot_history, get_transceivers, get_ssh_config, get_logs.

Contenedores y licencias

get_containers (contenedores de aplicaciones en el conmutador: estado, imagen, límites de CPU/memoria, redes VRF), get_feature_pack (estado de licencias / suscripción: modo de gestión, validez, caducidad, control por funcionalidad).

Gestión en la nube

get_aruba_central (estado de conexión de HPE ANW Central / Aruba Central: conectado, instanciación, fuente de configuración, ubicación, VRF/IP de origen, conectividad Activate).

Estado L2 / L3

get_interfaces, get_loopbacks, get_routed_ports, get_vlan_interfaces, get_vlans, get_lldp_neighbors, get_mac_table, get_arp_table, get_routing_table, get_spanning_tree.

Protocolos de enrutamiento

get_bgp_neighbors, get_bgp_config, get_bgp_routes, get_ospf_overview, get_ospf_neighbors, get_ospf_interfaces.

EVPN / VXLAN

get_evpn_config, get_evpn_routes, get_evpn_multihoming, get_vxlan_config, get_vxlan_tunnels, get_vxlan_static_peers, get_evpn_vtep_neighbors.

Alta disponibilidad (VSX / VSF)

get_vsx_status, get_vsx_config, get_vsx_sync, get_vsf_status, get_vsf_config, get_maintenance_mode.

NAE (Network Analytics Engine)

get_nae_scripts, get_nae_script, get_nae_agents, get_nae_agent.

Acceso de puerto / AAA / 802.1X

get_port_access_clients, get_port_access_client_detail, get_port_access_auth_config, get_port_access_summary, get_port_access_policies, get_port_access_roles, get_port_access_gbps, get_gbp_role_maps, get_port_access_abps, get_radius_servers, get_tacacs_servers, get_aaa_authentication, get_aaa_accounting.

Reconocimiento y control de aplicaciones (ARC)

get_app_recognition, get_app_visibility.

Gestión de configuración

list_configs, get_config, get_full_config, compare_configs, manage_config (guardar / checkpoint / rollback).

Configuración (escritura) + pares de verificación

Cada herramienta configure_* tiene una herramienta de verificación verify_* asociada:

Además, 7 herramientas atómicas conservadas: list_devices, list_sites, get_logs, run_ssh_commands, manage_config, logout, rollback. Los dispatchers de escritura mantienen el ciclo de vida plan → apply → verify y la protección de solo lectura por dispositivo. Los campos de dominio se pasan en un objeto params (claves documentadas en el docstring de cada dispatcher).

Herramientas atómicas heredadas (CX_FLAT_TOOLSET=false). Se expone en su lugar el catálogo completo por herramienta descrito arriba, opcionalmente configurado por las tres capas siguientes. Úselo para una reversión instantánea al comportamiento anterior.

Divulgación progresiva, prefijos funcionales y seguridad de escritura (solo modo heredado)

Tres capas opcionales (activas solo cuando CX_FLAT_TOOLSET=false, cada una controlada por su propia variable de entorno — consulte §5) configuran cómo se exponen las herramientas heredadas:

1. Divulgación progresiva (CX_DEFERRED_TOOLS) — en lugar de anunciar el catálogo completo (más de 100 herramientas), el servidor publica solo ~27 herramientas de Nivel 1 (las herramientas de lectura/diagnóstico más usadas, las vías de escape, los orquestadores y las meta-herramientas). Todas las demás herramientas están diferidas (Nivel 2) y se alcanzan bajo demanda mediante dos meta-herramientas:

Esto mantiene la lista de herramientas del agente pequeña y económica, dejando toda la superficie accesible.

2. Prefijos funcionales (CX_TOOL_PREFIXES) — las herramientas anunciadas se renombran <dominio>__<herramienta> para agruparlas por dominio, p. ej. routing__get_bgp_neighbors, overlay__configure_evpn, service__create_vlan_service, meta__invoke_tool. Dominios: inventory, exec, system, interface, switching, routing, overlay, redundancy, security, app, nae, config, service, meta. invoke_tool acepta tanto el nombre con prefijo como el nombre simple.

3. Seguridad de escritura (CX_WRITE_SAFETY) — un flujo de trabajo vista-previa→aplicación con reversión:

Flujo de trabajo: llame a cualquier herramienta de escritura con apply=false (el valor predeterminado) para obtener un plan y un dry_run_token; luego llame a apply_plan(dry_run_token=…) para aplicar ese plan exacto. Las fusiones idempotentes de configure_* no tienen inverso automático y se notifican como unsupported por rollback. Cuando CX_REQUIRE_DRY_RUN_TOKEN=true, se rechaza una aplicación directa (apply=true) a través de invoke_tool — los llamadores deben pasar por la ruta vista-previa→apply_plan.

3. Instalación (macOS / Linux / Windows)

Requisitos previos

• Docker y Docker Compose v2 (docker compose …).

  • macOS / Windows: Docker Desktop.

  • Linux: Docker Engine + el plugin de Compose.

• Conectividad de red desde el host de Docker hasta las IPs de gestión de los switches (HTTPS/443 para REST, TCP/22 para SSH).

• El acceso REST debe estar configurado en los dispositivos de destino y en la VRF correcta: en modo Read-Write para acceso de lectura y escritura, y en modo Read-only para acceso de solo lectura.

• El acceso SSH también debe estar configurado en los dispositivos de destino para las herramientas que lo requieran.

Configuración (primera ejecución)

Los secretos y los ajustes específicos del despliegue viven fuera de docker-compose.yml, en archivos que están ignorados por git para que nunca se confirmen. Se incluyen dos plantillas: copie cada una y complétela:

cd cx-mcp

# 1) Credentials & external source tokens  →  .env  (git-ignored)
cp .env.example .env
#    then edit .env and set at least ARUBA_DEFAULT_PASSWORD

# 2) Device inventory  →  inventory/inventory.yaml  (git-ignored)
cp inventory/inventory.example.yaml inventory/inventory.yaml
#    then edit it: list your switches, their IPs and per-device access_mode

.env se inyecta en el contenedor mediante env_file: en docker-compose.yml. Contenido mínimo (consulte .env.example para la lista completa):

ARUBA_DEFAULT_USERNAME=admin
ARUBA_DEFAULT_PASSWORD=your-switch-password
ARUBA_API_VERSION=latest
# Optional external sources of truth (leave empty if unused):
NETBOX_URL=
NETBOX_TOKEN=
INFRAHUB_URL=
INFRAHUB_TOKEN=

Nunca confirme .env ni inventory/inventory.yaml — contienen credenciales reales e IPs de dispositivos. Solo las plantillas *.example están controladas por git.

Compilar e iniciar (todas las plataformas)

cd cx-mcp
docker compose up -d --build

El servidor escucha en http://<host>:8002/mcp (puerto del host 8002 → contenedor 8000, consulte docker-compose.yml). La imagen se compila como hpe-cx-mcp:latest y se ejecuta como el contenedor hpe-cx-mcp.

Compruebe que está en ejecución:

docker compose logs -f hpe-cx-mcp
# look for, in order:
#   "Uvicorn running on http://0.0.0.0:8000"
#   "✅ hpe-cx-mcp server is up and running on http://0.0.0.0:8000 — if your agent
#    already has an open MCP connection, reset it (MCP: Disconnect → Connect) …"

La línea ✅ … server is up and running se emite una vez que el listener está listo. Si el inicio falla, el servidor registra ❌ hpe-cx-mcp server failed to start seguido del traceback completo (y luego sale con código distinto de cero).

Nota: cada docker compose up -d --build recompila la imagen y reinicia el servidor, lo que invalida cualquier sesión MCP existente. Después de una recompilación, vuelva a conectar su cliente (MCP: Disconnect → Connect) para recoger las herramientas actuales.

Notas por plataforma

Linux

• Las carpetas montadas por bind mount pertenecen a su usuario del host. El contenedor se ejecuta como uid 1000; si su usuario del host no es uid 1000, haga que las carpetas de escritura sean legibles/escribibles por uid 1000:

  mkdir -p logs secrets
  sudo chown -R 1000:1000 logs secrets
  chmod 700 secrets

• Para alcanzar los switches en la red L2 local del host, puede descomentar network_mode: host en docker-compose.yml (solo Linux).

macOS (Docker Desktop)

• El uso compartido de archivos lo gestiona la VM; los bind mounts funcionan sin configuración adicional y el re-mapeo de uid es automático — no se necesita chown manual en la mayoría de los casos.

• network_mode: host no se admite de la misma manera que en Linux; mantenga la asignación ports: predeterminada (8002:8000).

Windows (Docker Desktop + WSL2)

• Ejecute los comandos desde un shell de WSL2 o PowerShell. Se recomienda encarecidamente almacenar el proyecto dentro del sistema de archivos de WSL2 (p. ej. \\wsl$\… / ~/cx-mcp) para obtener permisos de archivo y rendimiento correctos.

• Use barras diagonales en las rutas de volumen de docker-compose.yml (./inventory:/app/inventory:ro).

• network_mode: host no está disponible; mantenga la asignación ports:.

4. Volúmenes

Tres carpetas del host se montan en el contenedor:

volumes:
  - ./inventory:/app/inventory:ro
  - ./logs:/app/logs
  - ./secrets:/app/secrets

El código de la aplicación está integrado en la imagen — solo se montan estas carpetas de datos. Después de cambiar cualquier *.py, recompile con docker compose up -d --build (un reinicio simple no es suficiente).

Propiedad (Linux): logs/ y secrets/ deben ser escribibles por el uid 1000 del contenedor. secrets/ debe tener permisos 0700 y su archivo .tokens lo escribe el propio servidor con permisos 0600.

5. Variables de entorno

Los secretos y los valores específicos del despliegue (credenciales, tokens de fuentes externas) se proporcionan a través del archivo .env ignorado por git, que docker-compose.yml carga mediante env_file: (copie .env.example a .env, consulte §3). Los indicadores operativos no secretos (MCP_*, CX_*, INVENTORY_FILE) se establecen directamente en docker-compose.yml bajo environment:. Los booleanos aceptan true/1/yes/on.

Transporte

Credenciales de dispositivo y API (definidas en .env; se pueden anular por dispositivo en el inventario)

Inventario y orígenes externos

Autenticación Bearer (opcional, DESACTIVADA por defecto)

Registro de auditoría (opcional, DESACTIVADO por defecto)

Divulgación progresiva, prefijos y seguridad de escritura (opcional)

6. Gestión del inventario

El archivo de inventario (inventory/inventory.yaml) declara los dispositivos y cómo acceder a ellos. Está ignorado por git (contiene IPs y credenciales reales); créelo una vez a partir de la plantilla incluida:

cp inventory/inventory.example.yaml inventory/inventory.yaml

Los valores del archivo anulan las variables de entorno. Formatos admitidos: YAML, JSON, TOML.

Ejemplo mínimo

defaults:
  username: admin
  password: "secret"
  api_version: latest        # auto-detect the newest REST version
  verify_ssl: false
  timeout: 30
  access_mode: read-only     # writes denied unless overridden per device

devices:
  Spine1:
    host: 192.0.2.21
    description: "Core switch"
    tags: [core, spine]
    site: campus-principal
    access_mode: read-write   # allow configuration changes on this device
  Access-01:
    host: 192.0.2.23
    site: campus-principal

Opciones por dispositivo

host (obligatorio), username, password, api_version, verify_ssl, timeout, tags, description, site, ssh_port, ssh_username, ssh_password, access_mode (read-only | read-write), vault (true para obtener credenciales de Vault).

Sitios

El concepto site es opcional y permite que las herramientas apunten a un grupo de dispositivos (list_devices(site=…), run_on_site(site, …)). Use un campo site: por dispositivo o un bloque sites: de nivel superior que agrupe dispositivos.

Opciones de origen del inventario

Hay varias formas de decidir de dónde proviene la lista de dispositivos:

1. Solo local (predeterminado) — dispositivos del archivo:

   source: local        # may be omitted

2. Origen externo único — extraer de una fuente de verdad:

   source: netbox
   sources:
     netbox:
       type: netbox            # netbox | nautobot | infrahub
       url: https://netbox.example.com
       token: "<api-token>"    # or via NETBOX_TOKEN env var
       verify_ssl: false

3. Orígenes combinados con prioridad — un dispositivo presente en varios orígenes se toma del de mayor prioridad:

   source: [local, netbox]
   source_priority: [local, netbox]   # local wins over netbox

Prioridad de resolución de credenciales (de mayor a menor):

1. Credenciales específicas del dispositivo definidas en la entrada del dispositivo.

2. HashiCorp Vault (cuando vault está activado globalmente o por dispositivo).

3. Variables de entorno / valores predeterminados del inventario.

Tras editar el inventario, aplique los cambios sin reconstruir mediante la herramienta refresh_inventory, o reinicie el contenedor.

Validación al arrancar (fail-fast)

El archivo de inventario se valida al arrancar. Si no se puede analizar (error de sintaxis YAML/JSON/TOML) o infringe el esquema esperado (p. ej. una clave source: mal indentada, o source definido con un valor que no es cadena/lista), el servidor registra un error específico en inglés y se niega a arrancar en lugar de ejecutarse silenciosamente con un inventario vacío o parcial:

❌ Inventory file '/app/inventory/inventory.yaml' failed validation — the server will NOT start.
   YAML syntax error: expected '<document start>', but found '<block mapping start>'
     in "<unicode string>", line 22, column 1
   Fix the inventory file, then restart the container.

El contenedor sale con un código de estado distinto de cero (visible en docker logs / docker compose ps). Corrija la línea indicada y reinicie. Notas:

• Un archivo de inventario ausente es solo una advertencia (se puede montar más tarde) — el servidor sigue arrancando.

• La accesibilidad de los orígenes externos (que NetBox / Nautobot / Infrahub estén caídos) no es fatal: el inventario local analizado sigue siendo utilizable y la combinación dinámica se degrada con elegancia.

• La herramienta refresh_inventory en tiempo de ejecución aplica la misma validación pero nunca bloquea un servidor en ejecución: con un archivo incorrecto devuelve un error y conserva el inventario cargado anteriormente.

7. Seguridad: autenticación Bearer y registro de auditoría

Ambas funciones están desactivadas por defecto y son totalmente compatibles con versiones anteriores.

• Autenticación (CX_AUTH_ENABLED=true): toda solicitud a /mcp debe llevar Authorization: Bearer <token>. Los tokens ausentes o no válidos reciben HTTP 401. El nombre del token se convierte en el actor registrado en el registro de auditoría, de modo que siempre se sabe quién hizo qué. Si la autenticación está activada pero aún no existe ningún token, el servidor arranca igualmente pero en modo BLOQUEADO: toda solicitud MCP se rechaza con HTTP 503 (fail-closed), de modo que los servicios quedan inaccesibles. Cree el primer token (véase §8) y reinicie el contenedor para desbloquearlo: el almacén de tokens se carga una sola vez al arrancar.

• Auditoría (CX_AUDIT_ENABLED=true): una línea JSON por cada llamada de herramienta en logs/audit.jsonl, que incluye actor, src_ip, tool, category (lectura/escritura), device objetivo, arguments censurados, outcome, status_code HTTP y duration_ms. Los secretos (contraseñas/tokens) se enmascaran.

Active ambas:

# docker-compose.yml
CX_AUTH_ENABLED:  "true"
CX_AUDIT_ENABLED: "true"

docker compose up -d --build

8. Gestión de tokens

Los tokens se almacenan en secrets/.tokens (permisos 0600). Gestionelos dentro del contenedor en ejecución con la CLI incluida:

# Create a named token (prints the secret once — save it)
docker compose exec hpe-cx-mcp python cx_token_manager.py generate --name vscode-dev

# List tokens (names, descriptions, created — secret truncated)
docker compose exec hpe-cx-mcp python cx_token_manager.py list

# Show one token
docker compose exec hpe-cx-mcp python cx_token_manager.py show --name vscode-dev

# Revoke a token
docker compose exec hpe-cx-mcp python cx_token_manager.py revoke --name vscode-dev

Los tokens generados llevan el prefijo cx_. Use un token distinto por cliente/agente para obtener la atribución por actor en el registro de auditoría.

Primer token: cuando la autenticación está activada, el servidor arranca BLOQUEADO (HTTP 503 en toda solicitud) hasta que exista un token. Tras crear el primer token, aplíquelo sin reiniciar mediante la recarga en caliente (véase más abajo):

docker compose exec hpe-cx-mcp python cx_reload.py

(también funciona docker compose restart hpe-cx-mcp).

Recarga en caliente (sin reconstruir / sin reiniciar)

Los archivos de tokens e inventario se cargan en memoria al arrancar. Tras editar secrets/.tokens (mediante la CLI anterior) o inventory/inventory.yaml, aplique los cambios al servidor en ejecución enviándole una señal de recarga:

docker compose exec hpe-cx-mcp python cx_reload.py

Esto recarga ambos, los tokens y el inventario, en su lugar: añadir/revocar un token, o añadir/actualizar un dispositivo, surte efecto en la siguiente solicitud. El comando solo envía la señal; el resultado (recuentos, errores) se escribe en los registros:

docker compose logs --tail=20 hpe-cx-mcp

La recarga es manual y explícita: no hay vigilancia automática de archivos.

Si los clientes se conectan a través de un relé compartido, todas las llamadas aparecen bajo el token único del relé; para la atribución por agente, conéctese directamente a hpe-cx-mcp con tokens distintos.

9. Conexión de un cliente MCP

Apunte su cliente MCP al endpoint streamable-HTTP:

URL:  http://<docker-host>:8002/mcp

Cuando la autenticación está habilitada, añade el encabezado:

Authorization: Bearer cx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Ejemplo (estilo mcp.json de VS Code):

{
  "servers": {
    "hpe-cx-mcp": {
      "type": "http",
      "url": "http://localhost:8002/mcp",
      "headers": { "Authorization": "Bearer cx_xxxxxxxxxxxxxxxxxxxx" }
    }
  }
}