ArubaOS-CX MCP 서버(hpe-cx-mcp)

Model Context Protocol(MCP) 서버로, MCP를 지원하는 AI 에이전트(Claude, VS Code Copilot 등)에 Aruba CX(AOS-CX) 스위치를 노출합니다. 스위치 REST API(/rest/v10.x)와 SSH CLI를 캠퍼스/데이터센터 패브릭(VLAN, 라우팅, BGP/OSPF, EVPN-VXLAN, VSX/VSF, 포트 액세스 / 802.1X, NAE, ARC…)을 위한 선별된 안전한 구조적 도구 세트로 변환합니다.

서버는 Docker 컨테이너로 실행되며 streamable HTTP를 통해 MCP를 사용하고, 선택적 명명된 Bearer-토큰 인증 및 JSON 감사 로깅을 제공합니다.

빠른 시작

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"

그런 다음 MCP 엔드포인트는 **http://<docker-host>:8002/mcp**에서 사용할 수 있습니다. MCP 클라이언트를 이 주소로 지정하세요(§9 참조). 전체 세부 사항 및 플랫폼별 참고 사항은 §3에 있습니다.

Related MCP server: API-Central

목차

1. 이 서버가 하는 일

2. 사용 가능한 도구

3. 설치(macOS / Linux / Windows)

4. 볼륨

5. 환경 변수

6. 인벤토리 관리

7. 보안: Bearer 인증 및 감사 로깅

8. 토큰 관리

9. MCP 클라이언트 연결

1. 이 서버가 하는 일

• 인벤토리에 정의된 AOS-CX 스위치 플릿에 대한 단일 진입점.

• 읽기(관찰): 인터페이스, VLAN, 라우팅/ARP/MAC 테이블, BGP/OSPF/EVPN, VXLAN 터널, VSX/VSF 스택 상태, 하드웨어 상태, 로그, 802.1X / 포트 액세스, NAE 스크립트, 애플리케이션 인식(ARC), 전체 구성.

• 쓰기(구성): VLAN 서비스, 루프백, 라우팅 포트, VRF, BGP, OSPF, EVPN/VXLAN, 포트 인증, 가상-MAC, ARC — 각각 verify_* 읽기-백 도구와 쌍을 이룹니다.

• 안전 장치:

  • 장치별 access_mode(기본값은 read-only; 장치가 명시적으로 read-write가 아닌 한 쓰기는 거부됨).

  • 사이트 범위(site-scoped) 작업(site 매개변수) — 장치 그룹을 대상으로 작업합니다.

  • 읽기 전용 장치에서 원시 CLI를 통한 구성 변경을 차단하는 SSH 쓰기 명령 탐지.

• 동적 인벤토리: 로컬 파일을 NetBox / Nautobot 소스 오브 트루스와 병합하고, 선택적으로 HashiCorp Vault 자격 증명 해석을 지원합니다.

2. 사용 가능한 도구

도구는 용도별로 그룹화됩니다. 읽기 도구는 장치에 연결할 수 있어야 하며, 쓰기 도구는 추가로 장치가 read-write여야 합니다.

인벤토리 및 세션

원시 액세스(이스케이프 해치)

시스템 및 하드웨어

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

컨테이너 및 라이선싱

get_containers(스위치 내 애플리케이션 컨테이너: 상태, 이미지, CPU/메모리 한도, VRF 네트워크), get_feature_pack(라이선스/구독 상태: 관리 모드, 유효성, 만료, 기능별 적용).

클라우드 관리

get_aruba_central(HPE ANW Central / Aruba Central 연결 상태: 연결됨, 인스턴스화, 구성 소스, 위치, VRF/소스 IP, Activate 연결).

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.

라우팅 프로토콜

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.

고가용성(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.

포트 액세스 / 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.

애플리케이션 인식 및 제어(ARC)

get_app_recognition, get_app_visibility.

구성 관리

list_configs, get_config, get_full_config, compare_configs, manage_config(저장 / 체크포인트 / 롤백).

구성(쓰기) + 검증 쌍

각 configure_* 도구에는 일치하는 verify_* 읽기-백 도구가 있습니다:

쓰기 보호: read-only 장치에 대한 configure_* / create_* / delete_* / manage_config 호출은 거부됩니다. 변경을 허용하려면 인벤토리에서 장치를 access_mode: read-write로 표시하세요.

도구 노출: 플랫 툴셋(기본값) vs 레거시 원자적 도구

서버는 CX_FLAT_TOOLSET 플래그로 선택되는 두 가지 상호 배타적 방식으로 기능을 노출할 수 있습니다(§5 참조):

플랫 툴셋(CX_FLAT_TOOLSET=true — 기본값). 위에 나열된 ~101개의 원자적 도구는 scope(및 쓰기의 경우 action) 인수로 구동되는 ~23개의 플랫 디스패처로 축소됩니다. 기본 REST 클라이언트 코드는 변경되지 않습니다 — 디스패처는 단지 해당 코드로 라우팅할 뿐이므로 동작 회귀가 없습니다. 모든 읽기 디스패처는 device: str | list, site 또는 source(외부 소스 오브 트루스 쿼리)도 허용하며 호출을 병렬로 분산하고 하나의 엔벨로프 {scope, results, errors, summary}를 반환합니다. 선택적 limit는 응답의 긴 목록 필드를 제한합니다.

유지되는 원자적 도구 7개: list_devices, list_sites, get_logs, run_ssh_commands, manage_config, logout, rollback. 쓰기 디스패처는 plan → apply → verify 수명 주기와 디바이스별 읽기 전용 가드를 유지합니다. 도메인 필드는 params 객체로 전달됩니다(각 디스패처의 docstring에 키가 문서화되어 있습니다).

레거시 원자적 도구 (CX_FLAT_TOOLSET=false). 대신 위의 전체 도구별 카탈로그가 노출되며, 아래의 세 가지 레이어로 선택적으로 형태를 지정할 수 있습니다. 이전 동작으로 즉시 롤백하려면 이 옵션을 사용하세요.

점진적 공개, 기능 접두사 및 쓰기 안전성 (레거시 모드 전용)

세 가지 선택적 레이어(CX_FLAT_TOOLSET=false일 때만 활성화, 각각 고유한 env 플래그로 제어됨 — §5 참조)는 레거시 도구가 노출되는 방식을 결정합니다:

1. 점진적 공개 (CX_DEFERRED_TOOLS) — 전체 카탈로그(100개 이상의 도구)를 광고하는 대신, 서버는 약 27개의 Tier-1 도구만 공개합니다(가장 많이 사용되는 읽기/진단 도구, 탈출구, 오케스트레이터, 메타 도구). 다른 모든 도구는 **지연됨(Tier-2)**이며 두 메타 도구를 통해 요청 시 접근됩니다:

이렇게 하면 에이전트의 도구 목록을 작고 경제적으로 유지하면서 전체 기능에 계속 접근할 수 있습니다.

2. 기능 접두사 (CX_TOOL_PREFIXES) — 노출되는 도구는 <domain>__<tool> 형식으로 이름이 바뀌어 도메인별로 그룹화됩니다. 예: routing__get_bgp_neighbors, overlay__configure_evpn, service__create_vlan_service, meta__invoke_tool. 도메인: inventory, exec, system, interface, switching, routing, overlay, redundancy, security, app, nae, config, service, meta. invoke_tool은 접두사가 붙은 이름과 붙지 않은 이름을 모두 허용합니다.

3. 쓰기 안전성 (CX_WRITE_SAFETY) — 롤백이 포함된 미리보기→적용 워크플로:

워크플로: apply=false(기본값)로 쓰기 도구를 호출하여 계획 및 dry_run_token을 얻습니다. 그런 다음 apply_plan(dry_run_token=…)을 호출하여 해당 정확한 계획을 적용합니다. 멱등성 configure_* 병합에는 자동 역방향 작업이 없으며 rollback에서 unsupported로 보고됩니다. CX_REQUIRE_DRY_RUN_TOKEN=true이면 invoke_tool을 통한 직접 적용(apply=true)은 거부됩니다 — 호출자는 미리보기→apply_plan 경로를 거쳐야 합니다.

3. 설치 (macOS / Linux / Windows)

사전 요구 사항

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

  • macOS / Windows: Docker Desktop.

  • Linux: Docker Engine + Compose 플러그인.

• Docker 호스트에서 스위치 관리 IP로의 네트워크 연결 가능성 (REST는 HTTPS/443, SSH는 TCP/22).

• REST 액세스는 대상 디바이스와 올바른 VRF에서 구성되어야 합니다: 읽기 및 쓰기 액세스에는 Read-Write 모드, 읽기 전용 액세스에는 Read-only 모드로 구성합니다.

• SSH 액세스도 SSH가 필요한 도구를 위해 대상 디바이스에 구성되어야 합니다.

구성 (최초 실행)

비밀 및 배포별 설정은 docker-compose.yml 외부에 있으며 git에서 무시되는 파일에 있으므로 커밋되지 않습니다. 템플릿 두 개가 제공됩니다 — 각각 복사하여 작성하세요:

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는 docker-compose.yml의 env_file:을 통해 컨테이너에 주입됩니다. 최소 내용 (전체 목록은 .env.example 참조):

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=

.env 또는 inventory/inventory.yaml을 절대 커밋하지 마세요 — 실제 자격 증명과 디바이스 IP가 들어 있습니다. *.example 템플릿만 git에서 추적됩니다.

빌드 및 시작 (모든 플랫폼)

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

서버는 **http://<host>:8002/mcp**에서 수신 대기합니다(호스트 포트 8002 → 컨테이너 8000, docker-compose.yml 참조). 이미지는 hpe-cx-mcp:latest로 빌드되고 컨테이너 hpe-cx-mcp로 실행됩니다.

실행 중인지 확인:

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

리스너가 준비되면 ✅ … server is up and running 줄이 출력됩니다. 반대로 시작이 실패하면 서버는 ❌ hpe-cx-mcp server failed to start 다음에 전체 traceback을 기록한 후(0이 아닌 코드로 종료됩니다).

참고: docker compose up -d --build를 실행할 때마다 이미지가 다시 빌드되고 서버가 다시 시작되어 기존 MCP 세션이 무효화됩니다. 다시 빌드한 후에는 클라이언트를 다시 연결(MCP: Disconnect → Connect)하여 현재 도구를 가져오세요.

플랫폼 참고 사항

Linux

• 바인드 마운트된 폴더는 호스트 사용자가 소유합니다. 컨테이너는 uid 1000으로 실행됩니다. 호스트 사용자가 uid 1000이 아닌 경우, 쓰기 가능한 폴더를 uid 1000이 읽기/쓰기할 수 있게 만드세요:

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

• 호스트의 로컬 L2 네트워크에 있는 스위치에 연결하려면 docker-compose.yml에서 network_mode: host를 주석 해제할 수 있습니다(Linux 전용).

macOS (Docker Desktop)

• 파일 공유는 VM이 처리합니다. 바인드 마운트는 기본적으로 작동하며 uid 재매핑은 자동입니다 — 대부분의 경우 수동 chown이 필요하지 않습니다.

• network_mode: host는 Linux에서와 같은 방식으로 지원되지 않습니다. 기본 ports: 매핑(8002:8000)을 유지하세요.

Windows (Docker Desktop + WSL2)

• WSL2 셸 또는 PowerShell에서 명령을 실행하세요. 프로젝트를 WSL2 파일 시스템 내부(예: \\wsl$\… / ~/cx-mcp)에 저장하는 것이 올바른 파일 권한과 성능을 위해 강력히 권장됩니다.

• docker-compose.yml 볼륨 경로에는 슬래시를 사용하세요(./inventory:/app/inventory:ro).

• network_mode: host는 사용할 수 없습니다. ports: 매핑을 유지하세요.

4. 볼륨

세 개의 호스트 폴더가 컨테이너에 마운트됩니다:

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

애플리케이션 코드는 이미지에 포함되어 있습니다 — 데이터 폴더만 마운트됩니다. *.py를 변경한 후에는 docker compose up -d --build로 다시 빌드하세요 (단순 재시작만으로는 충분하지 않습니다).

소유권(Linux): logs/와 secrets/는 컨테이너 uid 1000에서 쓸 수 있어야 합니다. secrets/는 0700이어야 하며, .tokens 파일은 서버가 직접 0600 권한으로 작성합니다.

5. 환경 변수

비밀 및 배포별 값(자격 증명, 외부 소스 토큰)은 git에서 무시되는 .env 파일을 통해 제공되며, docker-compose.yml이 env_file:로 로드합니다(.env.example를 .env로 복사, §3 참조). 비밀이 아닌 운영 플래그(MCP_*, CX_*, INVENTORY_FILE)는 docker-compose.yml의 environment: 아래에 직접 설정됩니다. 불리언은 true/1/yes/on을 허용합니다.

전송

장치 자격 증명 및 API(.env에 설정, 인벤토리에서 장치별로 재정의 가능)

인벤토리 및 외부 소스

Bearer 인증(선택 사항, 기본적으로 OFF)

감사 로그(선택 사항, 기본적으로 OFF)

점진적 공개, 접두사 및 쓰기 안전(선택 사항)

6. 인벤토리 관리

인벤토리 파일(inventory/inventory.yaml)은 장치와 연결 방법을 선언합니다. 이 파일은 git에서 제외됩니다(실제 IP와 자격 증명을 보관). 제공된 템플릿에서 한 번 생성하세요:

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

파일의 값이 환경 변수보다 우선합니다. 지원 형식: YAML, JSON, TOML.

최소 예시

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

장치별 옵션

host(필수), username, password, api_version, verify_ssl, timeout, tags, description, site, ssh_port, ssh_username, ssh_password, access_mode(read-only | read-write), vault(true는 Vault에서 자격 증명을 가져옴).

사이트

site 개념은 선택 사항이며 도구가 장치 그룹을 대상으로 지정할 수 있게 합니다(list_devices(site=…), run_on_site(site, …)). 장치별 site: 필드를 사용하거나 장치를 그룹화하는 최상위 sites: 블록을 사용하세요.

인벤토리 소스 옵션

장치 목록의 출처를 결정하는 방법은 여러 가지가 있습니다:

1. 로컬만(기본값) — 파일에서 장치 로드:

   source: local        # may be omitted

2. 단일 외부 소스 — 단일 정보 소스에서 가져오기:

   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. 우선순위가 있는 병합 소스 — 여러 소스에 있는 장치는 우선순위가 더 높은 소스에서 가져옵니다:

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

자격 증명 확인 우선순위(높은 순서):

1. 장치 항목에 설정된 장치별 자격 증명.

2. HashiCorp Vault(vault가 전역 또는 장치별로 활성화된 경우).

3. 환경 변수 / 인벤토리 기본값.

인벤토리를 편집한 후 다시 빌드하지 않고 refresh_inventory 도구로 변경 사항을 적용하거나 컨테이너를 재시작하세요.

시작 시 검증(빠른 실패)

인벤토리 파일은 시작 시 검증됩니다. 파일을 구문 분석할 수 없거나(YAML/JSON/TOML 구문 오류) 예상 스키마를 위반하면(예: 들여쓰기가 잘못된 source: 키, 또는 source가 문자열/목록이 아닌 값으로 설정된 경우), 서버는 빈 인벤토리나 부분 인벤토리로 조용히 실행하는 대신 특정 영어 오류를 기록하고 시작을 거부합니다:

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

컨테이너는 0이 아닌 상태 코드로 종료됩니다(docker logs / docker compose ps에서 확인 가능). 보고된 줄을 수정하고 재시작하세요. 참고:

• 누락된 인벤토리 파일은 경고일 뿐입니다(나중에 마운트 가능) — 서버는 계속 시작됩니다.

• 외부 소스 연결 가능 여부(NetBox / Nautobot / Infrahub가 다운된 경우)는 치명적이지 않습니다: 구문 분석된 로컬 인벤토리는 계속 사용할 수 있으며 동적 병합은 정상적으로 저하됩니다.

• 런타임 refresh_inventory 도구는 동일한 검증을 적용하지만 실행 중인 서버를 중단시키지 않습니다: 잘못된 파일이면 오류를 반환하고 이전에 로드된 인벤토리를 유지합니다.

7. 보안: Bearer 인증 및 감사 로그

두 기능 모두 기본적으로 비활성화되어 있으며 완전히 하위 호환됩니다.

• 인증(CX_AUTH_ENABLED=true): /mcp에 대한 모든 요청은 Authorization: Bearer <token>을 포함해야 합니다. 누락되거나 유효하지 않은 토큰은 HTTP 401을 받습니다. 토큰의 이름이 감사 로그에 기록되는 actor가 되므로 누가 무엇을 했는지 항상 알 수 있습니다. 인증이 활성화되었지만 아직 토큰이 없으면 서버는 시작은 하지만 LOCKED 모드입니다: 모든 MCP 요청은 HTTP 503(fail-closed)으로 거부되어 서비스에 연결할 수 없습니다. 첫 토큰을 만들고(§8 참조) 컨테이너를 재시작하면 잠금이 해제됩니다 — 토큰 저장소는 시작 시 한 번 로드됩니다.

• 감사(CX_AUDIT_ENABLED=true): logs/audit.jsonl에 도구 호출당 JSON 한 줄을 기록합니다. 여기에는 actor, src_ip, tool, category(읽기/쓰기), 대상 device, 마스킹된 arguments, outcome, HTTP status_code, duration_ms가 포함됩니다. 비밀번호/토큰 같은 비밀 정보는 마스킹됩니다.

둘 다 활성화하려면:

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

docker compose up -d --build

8. 토큰 관리

토큰은 secrets/.tokens(권한 0600)에 저장됩니다. 실행 중인 컨테이너 내부에서 번들 CLI로 관리하세요:

# 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

생성된 토큰은 cx_ 접두사가 붙습니다. 감사 로그에서 행위자별 귀속을 확인하려면 클라이언트/에이전트마다 고유한 토큰을 사용하세요.

첫 번째 토큰: 인증이 활성화되면 서버는 토큰이 존재할 때까지 LOCKED 상태로 시작됩니다(모든 요청에 HTTP 503). 첫 번째 토큰을 만든 후 재시작 없이 핫 리로드로 적용하세요(아래 참조):

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

(docker compose restart hpe-cx-mcp도 작동합니다).

핫 리로드(재빌드 없음 / 재시작 없음)

토큰과 인벤토리 파일은 시작 시 메모리에 로드됩니다. secrets/.tokens(위의 CLI 사용) 또는 inventory/inventory.yaml을 편집한 후 리로드 신호를 보내 실행 중인 서버에 변경 사항을 적용하세요:

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

이렇게 하면 토큰과 인벤토리가 모두 그 자리에서 리로드됩니다 — 토큰 추가/폐기 또는 장치 추가/업데이트가 다음 요청부터 적용됩니다. 이 명령은 신호만 보내며 결과(개수, 오류)는 로그에 기록됩니다:

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

리로드는 수동으로 명시적으로 수행됩니다 — 자동 파일 감시는 없습니다.

클라이언트가 공유 릴레이를 통해 연결하면 모든 호출이 릴레이의 단일 토큰 아래 표시됩니다. 에이전트별 귀속을 원하면 고유 토큰을 사용하여 hpe-cx-mcp에 직접 연결하세요.

9. MCP 클라이언트 연결

MCP 클라이언트를 streamable-HTTP 엔드포인트로 지정하세요:

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

인증이 활성화되면 헤더를 추가하세요:

Authorization: Bearer cx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

예시 (VS Code mcp.json 스타일):

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