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

A Model Context Protocol (MCP) server that exposes Aruba CX (AOS-CX) switches to MCP-capable AI agents (Claude, VS Code Copilot, etc.). It turns the switch REST API (/rest/v10.x) and the SSH CLI into a curated set of safe, structured tools for observability, troubleshooting and configuration of a campus / data-center fabric (VLANs, routing, BGP/OSPF, EVPN-VXLAN, VSX/VSF, port access / 802.1X, NAE, ARC…).

The server runs as a Docker container, speaks MCP over streamable HTTP, and ships with optional named Bearer-token authentication and JSON audit logging.

Quick start

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"

The MCP endpoint is then available at http://<docker-host>:8002/mcp. Point your MCP client at it (see §10). Full details and platform notes are in §3.

Related MCP server: HPE Aruba Networking Central MCP Server

Table of contents

1. What this server does

2. Available tools

3. Installation (macOS / Linux / Windows)

4. Volumes

5. Environment variables

6. Inventory management

7. Security: Bearer auth & audit logging

8. Token management

9. Operations runbook

10. Connecting an MCP client

11. Prompts (guided operations) & skills

1. What this server does

• Single entry point to a fleet of AOS-CX switches described in an inventory.

• Read (observe): interfaces, VLANs, routing/ARP/MAC tables, BGP/OSPF/EVPN, VXLAN tunnels, VSX/VSF stack state, hardware health, logs, 802.1X / port-access, NAE scripts, application recognition (ARC), full configs.

• Write (configure): VLAN services, VLANs/SVIs/trunks, LAGs (static, LACP, MC-LAG, EVPN multihoming), loopbacks, routed ports, VRFs, static routes, BGP, OSPF, redistribution, EVPN/VXLAN, VSX, DHCP relay, port groups, port authentication, virtual-MAC, ARC — each paired with a verify_* read-back tool.

• Orchestrate: multi-step workflows (VSX pair, L3 links, access ports, RADIUS/802.1X, VXLAN overlay and VLAN services, full fabric underlay/overlay) in one plan → apply call, with a per-device checkpoint.

• Safety rails:

  • Per-device access_mode (read-only by default; writes are denied unless a device is explicitly read-write).

  • Site-scoped operations (site parameter) to act on a group of devices.

  • SSH write-command detection to block configuration changes via raw CLI on read-only devices.

• Dynamic inventory: merge the local file with NetBox / Nautobot sources of truth, with optional HashiCorp Vault credential resolution.

2. Available tools

Tools are grouped by purpose. Read tools require a device to be reachable; write tools additionally require the device to be read-write.

Inventory & sessions

Raw access (escape hatches)

System & hardware

get_system_info, get_hardware_health, get_boot_history, get_transceivers, get_ssh_config, get_logs, get_poe_status (Power-over-Ethernet: per-port draw in watts/amps/volts, powering state, powered-device class, plus the chassis-wide PoE power budget).

Containers & licensing

get_containers (on-switch application containers: status, image, CPU/memory limits, VRF networks), get_feature_pack (licensing / subscription state: management mode, validity, expiration, per-feature enforcement).

Cloud management

get_aruba_central (HPE ANW Central / Aruba Central connection state: connected, instantiation, config source, location, VRF/source IP, Activate connectivity).

L2 / L3 state

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.

Routing protocols

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.

High availability (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.

Port access / 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.

Application Recognition & Control (ARC)

get_app_recognition, get_app_visibility.

Configuration management

list_configs, get_config, get_full_config, compare_configs, manage_config (save / checkpoint / rollback), backup_config (export campaign to an external SFTP/TFTP server, see §5).

Configure (write) + verify pairs

Each configure_* tool has a matching verify_* read-back tool:

Orchestrators (multi-step writes)

Each orchestrator builds one ordered step list per device, runs it inside a single auto-checkpoint and stops at the first failing step (the switch then reverts). Plan mode shows every step and, for the fabric tools, the IP allocation, without writing anything.

Per-device values (ip_address, source_ip, virtual_mac, router_id) accept a {device: value} mapping or loopback0/auto. A shared literal is refused unless the devices sharing it are one VSX pair. VSF secondary members are refused as targets (address the conductor instead).

Write protection: a configure_* / create_* / delete_* / manage_config call on a read-only device is refused. Mark the device access_mode: read-write in the inventory to allow changes.

Tool exposure: flat toolset (default) vs legacy atomic tools

The server can expose its capabilities in two mutually exclusive ways, chosen by the CX_FLAT_TOOLSET flag (see §5):

Flat toolset (CX_FLAT_TOOLSET=true — the default). The atomic tools listed above are collapsed into 19 flat dispatchers (plus the 10 kept-atomic tools below — 29 tools advertised in total) driven by a scope (and, for writes, an action) argument. The underlying REST client code is unchanged — the dispatchers only route to it, so there is no behavioural regression. Every read dispatcher also accepts device: str | list, site or source (an external source-of-truth query) and fans the call out in parallel, returning one envelope {scope, results, errors, summary}. An optional limit caps long list fields in the response.

Plus 10 kept-atomic tools: list_devices, list_sites, get_logs, run_ssh_commands, manage_config, backup_config, logout, rollback, orchestrate_fabric_underlay, orchestrate_fabric_overlay (these two take spines/leafs lists instead of a single device). Write dispatchers keep the plan → apply → verify lifecycle and the per-device read-only guard. Domain fields are passed in a params object (keys documented in each dispatcher's docstring).

Legacy atomic tools (CX_FLAT_TOOLSET=false). The full per-tool catalog above is exposed instead, optionally shaped by the three layers below. Use this for an instant rollback to the previous behaviour.

Progressive disclosure, functional prefixes & write safety (legacy mode only)

Three optional layers (active only when CX_FLAT_TOOLSET=false, each gated by its own env flag — see §5) shape how the legacy tools are exposed:

1. Progressive disclosure (CX_DEFERRED_TOOLS) — instead of advertising the full catalog (100+ tools), the server publishes only ~27 Tier-1 tools (the most-used read/diagnostic tools, the escape hatches, the orchestrators and the meta-tools). Every other tool is deferred (Tier-2) and reached on demand via two meta-tools:

This keeps the agent's tool list small and cheap while leaving the entire surface reachable.

2. Functional prefixes (CX_TOOL_PREFIXES) — advertised tools are renamed <domain>__<tool> to group them by domain, e.g. routing__get_bgp_neighbors, overlay__configure_evpn, service__create_vlan_service, meta__invoke_tool. Domains: inventory, exec, system, interface, switching, routing, overlay, redundancy, security, app, nae, config, service, meta. invoke_tool accepts either the prefixed or the bare name.

3. Write safety (CX_WRITE_SAFETY) — a preview→apply workflow with rollback:

Workflow: call any write tool with apply=false (the default) to get a plan and a dry_run_token; then call apply_plan(dry_run_token=…) to apply that exact plan. Idempotent configure_* merges have no automatic inverse and are reported as unsupported by rollback. When CX_REQUIRE_DRY_RUN_TOKEN=true (the shipped default), a direct apply is refused on every write path:

• Flat toolset (configure_interface / configure_routing / configure_security / configure_service): action=plan returns a dry_run_token; action=apply (or delete) must pass dry_run_token=… with the same params. The plan is re-computed and hash-compared before the write (TOCTOU guard), the token is single-use, and a rollback_id is attached when the plan is reversible.

• Legacy layer: apply=true through invoke_tool is refused — use the preview→apply_plan path.

3. Installation (macOS / Linux / Windows)

Prerequisites

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

  • macOS / Windows: Docker Desktop.

  • Linux: Docker Engine + the Compose plugin.

• Network reachability from the Docker host to the switches' management IPs (HTTPS/443 for REST, TCP/22 for SSH).

• REST access must be configured on the target devices and in the correct VRF: in Read-Write mode for Read and Write access, and Read-only mode for read-only access.

• SSH access must also be configured on the target devices for the tools that require it.

Configure (first run)

Secrets and deployment-specific settings live outside docker-compose.yml, in files that are git-ignored so they are never committed. Two templates are shipped — copy each one and fill it in:

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 is injected into the container via env_file: in docker-compose.yml. Minimum content (see .env.example for the full list):

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=

Never commit .env or inventory/inventory.yaml — they hold real credentials and device IPs. Only the *.example templates are tracked by git.

Build & start (all platforms)

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

The server listens on http://<host>:8002/mcp (host port 8002 → container 8000, see docker-compose.yml). The image is built as hpe-cx-mcp:latest and runs as the container hpe-cx-mcp.

Check it is running:

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) …"

The ✅ … server is up and running line is emitted once the listener is ready. If startup fails instead, the server logs ❌ hpe-cx-mcp server failed to start followed by the full traceback (then exits non-zero).

Note: every docker compose up -d --build rebuilds the image and restarts the server, which invalidates any existing MCP session. After a rebuild, reconnect your client (MCP: Disconnect → Connect) to pick up the current tools.

Platform notes

Linux

• Bind-mounted folders are owned by your host user. The container runs as uid 1000; if your host user is not uid 1000, make the writable folders readable/writable by uid 1000:

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

• To reach switches on the host's local L2 network you may uncomment network_mode: host in docker-compose.yml (Linux only).

macOS (Docker Desktop)

• File sharing is handled by the VM; bind mounts work out of the box and uid remapping is automatic — no manual chown needed in most cases.

• network_mode: host is not supported the same way as on Linux; keep the default ports: mapping (8002:8000).

Windows (Docker Desktop + WSL2)

• Run the commands from a WSL2 shell or PowerShell. Storing the project inside the WSL2 filesystem (e.g. \\wsl$\… / ~/cx-mcp) is strongly recommended for correct file permissions and performance.

• Use forward slashes in docker-compose.yml volume paths (./inventory:/app/inventory:ro).

• network_mode: host is not available; keep the ports: mapping.

4. Volumes

Three host folders are mounted into the container:

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

The application code is baked into the image — only these data folders are mounted. After changing any *.py, rebuild with docker compose up -d --build (a plain restart is not enough).

Ownership (Linux): logs/ and secrets/ must be writable by container uid 1000. secrets/ should be 0700 and its .tokens file is written 0600 by the server itself.

5. Environment variables

Secrets and deployment-specific values (credentials, external-source tokens) are provided through the git-ignored .env file, which docker-compose.yml loads via env_file: (copy .env.example to .env, see §3). Non-secret operational flags (MCP_*, CX_*, INVENTORY_FILE) are set directly in docker-compose.yml under environment:. Booleans accept true/1/yes/on.

Transport

Device credentials & API (set in .env; overridable per device in the inventory)

Inventory & external sources

SFTP/TFTP configuration backups

Use backup_config to run an export campaign for a device or an entire site. protocol="sftp" is the default; protocol="tftp" is available for legacy backup servers but has neither encryption nor authentication, so use it only on a trusted management network. It transfers running-config by default (or startup-config) and returns the remote path and byte count per device, never the configuration content. The default filename is {hostname}_{timestamp}_config.cfg; pass filename_format to change it. Only {hostname} and UTC {timestamp} (YYYYMMDDTHHMMSSZ) are permitted.

TLS verification towards the switches

Bearer authentication (ON in the shipped compose)

Audit logging (ON in the shipped compose, writes)

Progressive disclosure, prefixes & write safety (optional)

Apply-time safety rails

6. Inventory management

The inventory file (inventory/inventory.yaml) declares the devices and how to reach them. It is git-ignored (it holds real IPs and credentials); create it once from the shipped template:

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

Values in the file override environment variables. Supported formats: YAML, JSON, TOML.

Minimal example

defaults:
  username: admin
  password: "secret"
  api_version: latest        # auto-detect the newest REST version
  verify_ssl: false          # lab only (self-signed certs); default is true
  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

Per-device options

host (required), username, password, api_version, verify_ssl, timeout, tags, description, site, ssh_port, ssh_username, ssh_password, access_mode (read-only | read-write), vault (true to fetch credentials from Vault).

Sites

The site concept is optional and lets tools target a group of devices (list_devices(site=…), run_on_site(site, …)). Use either a per-device site: field or a top-level sites: block grouping devices.

Inventory source options

There are several ways to decide where the device list comes from:

1. Local only (default) — devices from the file:

   source: local        # may be omitted

2. Single external source — pull from a source of truth:

   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. Merged sources with priority — a device present in several sources is taken from the higher-priority one:

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

Credential resolution priority (highest first):

1. Device-specific credentials set on the device entry.

2. HashiCorp Vault (when vault is enabled globally or per device).

3. Environment variables / inventory defaults.

After editing the inventory, apply changes without rebuilding via the refresh_inventory tool, or restart the container.

Startup validation (fail-fast)

The inventory file is validated at startup. If it cannot be parsed (YAML/JSON/ TOML syntax error) or violates the expected schema (e.g. a mis-indented source: key, or source set to a non-string/list value), the server logs a specific English error and refuses to start rather than silently running with an empty or partial inventory:

❌ 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.

The container exits with a non-zero status code (visible in docker logs / docker compose ps). Fix the reported line and restart. Notes:

• A missing inventory file is only a warning (it can be mounted later) — the server still starts.

• External source reachability (NetBox / Nautobot / Infrahub being down) is not fatal: the parsed local inventory remains usable and the dynamic merge degrades gracefully.

• The runtime refresh_inventory tool applies the same validation but never crashes a running server: on a bad file it returns an error and keeps the previously loaded inventory.

7. Security: Bearer auth & audit logging

Both features are disabled by default and fully backward compatible.

• Authentication (CX_AUTH_ENABLED=true): every request to /mcp must carry Authorization: Bearer <token>. Missing/invalid tokens get HTTP 401. The token's name becomes the actor recorded in the audit log, so you always know who did what. If auth is enabled but no token exists yet, the server still starts but in LOCKED mode: every MCP request is refused with HTTP 503 (fail-closed) so the services are unreachable. Create the first token (see §8) and restart the container to unlock — the token store is loaded once at startup.

• Audit (CX_AUDIT_ENABLED=true): one JSON line per tool call in logs/audit.jsonl, including actor, src_ip, tool, category (read/write), targeted device, redacted arguments, outcome, HTTP status_code and duration_ms. Secrets (passwords/tokens) are masked.

Enable both:

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

docker compose up -d --build

8. Token management

Tokens are stored in secrets/.tokens (perms 0600). Manage them inside the running container with the bundled CLI:

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

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

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

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

Generated tokens are prefixed cx_. Use one distinct token per client/agent to get per-actor attribution in the audit log.

First token: when authentication is enabled, the server starts LOCKED (HTTP 503 on every request) until a token exists. After creating the first token, apply it without a restart by hot-reloading (see below):

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

(a docker compose restart hpe-cx-mcp also works).

Hot reload (no rebuild / no restart)

Token and inventory files are loaded into memory at startup. After editing secrets/.tokens (via the CLI above) or inventory/inventory.yaml, apply the changes to the running server by sending it a reload signal:

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

This reloads both the tokens and the inventory in place — adding/revoking a token, or adding/updating a device, takes effect on the next request. The command only sends the signal; the outcome (counts, errors) is written to the logs:

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

Reloading is manual and explicit — there is no automatic file watching.

If clients connect through a shared relay, all calls appear under the relay's single token; for per-agent attribution, connect directly to hpe-cx-mcp with distinct tokens.

9. Operations runbook

Day-2 procedures for a production deployment. Every command runs from the cx-mcp/ directory on the Docker host.

9.1 Health & version

curl -s http://localhost:8002/healthz | jq        # 200 ok/degraded, 503 unavailable
docker inspect --format '{{.State.Health.Status}}' hpe-cx-mcp
docker inspect --format '{{index .Config.Labels "org.opencontainers.image.version"}}' hpe-cx-mcp

/healthz needs no token and never returns secrets. problems[] names the cause (locked, inventory: 0 devices, inventory reload failed). It is what the Docker HEALTHCHECK and any load balancer should probe.

9.2 Upgrade / rollback of the server

# upgrade: bump ./VERSION, add a CHANGELOG entry, then
export CX_VERSION=$(cat VERSION) && docker compose up -d --build
# rollback: re-run with the previous, still-present image tag
CX_VERSION=1.0.0 docker compose up -d --no-build

Images are tagged hpe-cx-mcp:<version> (never latest). After any rebuild, MCP clients must reconnect (tool schemas are cached client-side).

9.3 Token lifecycle (one token per client)

docker compose exec hpe-cx-mcp python security/cx_token_manager.py generate --name <client>
docker compose exec hpe-cx-mcp python security/cx_token_manager.py list
docker compose exec hpe-cx-mcp python security/cx_token_manager.py revoke --name <client>
docker compose exec hpe-cx-mcp python security/cx_reload.py   # apply without restart

Rotate: generate the new token, hand it over, revoke the old one, reload. If /healthz reports locked, no token exists: generate one and reload.

9.4 Inventory change

Edit inventory/inventory.yaml, then python security/cx_reload.py (as above). A syntax/schema error keeps the previous inventory in memory and is reported in /healthz → inventory.last_error and the logs. Fix and reload.

9.5 Applying a change safely (what the agent goes through)

1. configure_*(action='plan', …) → plan + dry_run_token (TTL CX_DRY_RUN_TTL).

2. configure_*(action='apply', dry_run_token=…, same params) → the plan is recomputed and hash-compared; the write runs inside a firmware auto-checkpoint; on success the checkpoint is confirmed and a rollback_id is returned.

3. Protected objects (CX_PROTECTED_OBJECTS) are refused unless force=true.

If an apply fails mid-way the response says auto-checkpoint left ARMED: the switch reverts by itself after CX_AUTO_CHECKPOINT_MINUTES. To keep the partial state instead, call manage_config(device, action='confirm') before the deadline. The safety net is on by default; disable it globally with CX_AUTO_CHECKPOINT=false, or for one call with auto_checkpoint=false (the per-device result then reports checkpoint: disabled).

9.6 Undoing a change

rollback(rollback_id='rb_…')                       # objects CREATED by the apply
manage_config(device, action='list_checkpoints')   # otherwise: firmware checkpoints
manage_config(device, action='restore_checkpoint', name='<checkpoint>')

rollback only removes objects the apply created (VLAN-service steps, loopbacks, VRFs, L3 VNIs). Updates of pre-existing objects are listed as unsupported — restore a checkpoint (or startup-config) for those.

9.7 Reading the audit trail

tail -f logs/audit.jsonl | jq '{ts,actor,src_ip,tool,category,outcome,duration_ms}'
jq -c 'select(.category=="write" and .outcome!="completed")' logs/audit.jsonl
docker compose logs -f hpe-cx-mcp | grep '"tool"'      # same records on stdout

One JSON line per call (CX_AUDIT_LEVEL=writes → writes only); actor is the token name, arguments are redacted. Files rotate 10 MB × 5 under ./logs.

9.8 Incident checklist

10. Connecting an MCP client

Point your MCP client at the streamable-HTTP endpoint:

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

When authentication is enabled, add the header:

Authorization: Bearer cx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Example (VS Code mcp.json style):

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

11. Prompts (guided operations) & skills

Prompts

Beyond individual tools, the server exposes MCP prompts (tools/prompts.py) — reusable, multi-step operation guides an agent can follow end-to-end instead of being told which tool to call at each step. Each prompt returns a short plan referencing the tools/dispatchers above; the agent still asks for confirmation before any apply-mode write.

Data Center

Campus

Cross-domain (DC + Campus)

Skills

skills/ holds installable SKILL.md domain-knowledge packages (playbooks, gotchas, thresholds) that complement the prompts above:

Each skill is a self-contained SKILL.md (YAML frontmatter name+description plus a Markdown body) — install/copy it into your assistant's skills directory to load the domain knowledge alongside this MCP server's tools.