afc-mcp

Aruba Fabric Composer (AFC)용 MCP 서버로, 인벤토리, 네트워크 상태, VMware vCenter/vSphere 가시성에 중점을 둡니다. 읽기 전용입니다.

포함 내용

• server.py: MCP 도구를 노출하는 FastMCP 엔트리포인트(전송 방식: streamable-http).

• afc_client.py: 인증 토큰 처리와 매핑된 읽기 전용 엔드포인트를 포함하는 AFC API 클라이언트.

• Dockerfile: MCP 서버용 컨테이너 이미지.

• docker-compose.yml: 로컬 실행 환경(호스트 포트 8010 → 컨테이너 8000).

• .env.example: 환경 변수 템플릿.

Related MCP server: Cisco RIS MCP Server

빠른 시작

1. 환경 파일을 생성합니다.

cp .env.example .env

2. 최소한 다음 항목을 입력합니다.

• AFC_BASE_URL (호스트 루트 /api 없이, 예: https://afc.example.local)

• AFC_USERNAME

• AFC_PASSWORD

• AFC_VERIFY_SSL (선택 사항, 기본값 false)

• AFC_TIMEOUT (선택 사항, 기본값 30)

3. 빌드하고 실행합니다.

docker compose up --build -d

4. 로그를 확인합니다.

docker compose logs -f

엔드포인트

서버는 streamable-HTTP를 통해 MCP를 제공합니다.

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

기본적으로 엔드포인트는 열려 있습니다. 유효한 토큰을 가진 클라이언트만 도구를 호출할 수 있도록 Bearer 토큰 인증을 활성화할 수 있습니다(아래 참조).

인증 (Bearer 토큰)

인증은 선택 사항이며 기본적으로 비활성화되어 있습니다(하위 호환 가능). 활성화하면 모든 MCP 요청에 Authorization: Bearer <token> 헤더가 포함되어야 합니다. 유효한 토큰이 없는 요청은 401로 거부됩니다.

토큰에는 이름이 지정되며(클라이언트당 하나) secrets/.tokens에 저장됩니다(git 제외, 컨테이너에 읽기/쓰기 마운트).

1. 첫 번째 토큰을 생성합니다(호스트 또는 컨테이너 내부에서 실행).

# on the host (stdlib only, no dependencies needed)
cd afc-mcp
python afc_token_manager.py generate --name "vscode-dev" --description "Laptop VSCode"

# ...or inside the running container
docker compose exec afc-mcp python afc_token_manager.py generate --name "vscode-dev"

명령은 평문 토큰을 한 번만 출력합니다. 지금 복사하세요.

2. 인증을 활성화하고 서버를 (재)시작합니다.

# in .env or the shell environment
AFC_AUTH_ENABLED=true

docker compose up -d --build

안전망: AFC_AUTH_ENABLED=true인데 아직 토큰이 없으면 서버가 LOCKED 모드로 시작되고, 토큰이 생성되고 컨테이너가 재시작될 때까지 모든 요청(503)을 거부합니다. 이는 실수로 개방된 엔드포인트가 노출되는 것을 방지합니다.

CLI에서 토큰을 관리합니다.

python afc_token_manager.py list                 # masked preview
python afc_token_manager.py show --name vscode-dev  # reveal a value
python afc_token_manager.py revoke --name vscode-dev

토큰을 취소하거나 추가하려면 컨테이너를 재시작해야 적용됩니다.

참고: MCP_HOST / MCP_PORT는 컨테이너 내부에서 서버가 수신하는 위치만 제어합니다(0.0.0.0:8000, 호스트 8010에 매핑). 이 값은 인증과 무관합니다. 서버가 어디서 수신하는지를 지정하지, 누가 호출할 수 있는지를 지정하는 것은 아닙니다.

VS Code와 연동

VS Code(GitHub Copilot / 에이전트 모드)는 mcp.json 파일에서 MCP 서버를 검색합니다.

1. 작업 영역에 .vscode/mcp.json을 생성합니다(또는 사용자 mcp.json에 추가).

{
  "servers": {
    "afc-mcp": {
      "type": "http",
      "url": "http://localhost:8010/mcp"
    }
  }
}

컨테이너가 다른 곳에서 실행되는 경우 localhost를 Docker 호스트 주소로 바꾸십시오.

인증이 활성화된 경우 Bearer 토큰을 헤더로 추가하십시오.

{
  "servers": {
    "afc-mcp": {
      "type": "http",
      "url": "http://localhost:8010/mcp",
      "headers": { "Authorization": "Bearer afc_xxxxxxxx" }
    }
  }
}

2. 명령 팔레트를 열고 → MCP: List Servers를 선택한 다음 afc-mcp를 선택하고 시작합니다.

3. 채팅 보기(에이전트 모드)의 도구 선택기에서 AFC 도구를 사용할 수 있습니다.

Claude Desktop과 연동

Claude Desktop은 기본적으로 로컬(stdio) 서버에 연결됩니다. 이 streamable-HTTP 서버에 연결하려면 mcp-remote로 브리지하세요.

claude_desktop_config.json을 편집합니다.

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "afc-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8010/mcp"]
    }
  }
}

Claude Desktop을 재시작하면 도구 메뉴에 afc-mcp가 나타납니다.

또는 최근 Claude Desktop 빌드는 동일한 URL을 사용하여 Settings → Connectors → Add custom connector 아래에서 원격 MCP 서버를 직접 지원합니다.

사용 가능한 MCP 도구

서버 및 시스템

• get_server_status — MCP 서버 연결 가능 여부/상태.

• get_system_info — AFC 시스템 정보.

스위치 및 패브릭

• list_switches, get_switch — 스위치 인벤토리 및 스위치별 상세 정보(포트, 소프트웨어, 태그).

• list_fabrics, get_fabric — 패브릭 인벤토리와 구성원.

라우팅 및 오버레이

• list_vrfs, get_vrf — VRF 인벤토리 및 상세 정보.

• get_vrf_routes — 가장 긴 프리픽스 일치와 다음 홉 조회를 지원하는 VRF IP 라우팅 테이블(RIB). VRF와 스위치를 이름 또는 UUID로 지정할 수 있습니다. destination(호스트 IP 또는 CIDR)을 지정하면 최장 프리픽스 매칭을 수행하여 일치하는 경로와 다음 홉을 반환합니다.

• get_vrf_arp — 스위치에서 학습한 VRF ARP 테이블(IP-MAC 매핑). VRF와 스위치를 이름 또는 UUID로 지정합니다. switch를 전달하면 테이블을 특정 스위치로 제한합니다. 각 항목은 IP/MAC, 인터페이스, 물리 포트, 소유 스위치 및 이웃 연결 가능한지 여부(reachable, stale, incomplete, …)를 표시합니다.

• get_vrf_ip_interfaces — VRF L3(IP) 인터페이스. VRF와 스위치를 이름 또는 UUID로 지정합니다. if_type(routed, vlan, loopback, evpn)으로 필터링합니다. include_status(기본값)를 사용하면 운영 상태(관리자 up/down, MAC, IP MTU, duplex, IPv4 주소)가 구성과 함께 반환됩니다.

• get_vrf_static_routes — VRF에 구성된 IP 정적 경로(대상 프리픽스, 다음 홉 또는 nullroute/discard, 다음 홉 인터페이스, distance, tag, type 및 적용된 스위치). VRF와 스위치를 이름 또는 UUID로 지정합니다.

• get_vrf_bgp_status, get_vrf_bgp_summary — VRF별 BGP 상태 및 요약.

• get_vrf_ospf_neighbors, get_vrf_ospf_summary — VRF별 OSPF 이웃 및 요약.

• list_evpn, list_evpn_routes — EVPN 인스턴스 및 경로.

• get_vrf_virtual_environment — VRF에 바인딩된 가상 환경.

사이트 및 개요

• list_afc_sites, get_afc_site_inventory — AFC(원격) 사이트 및 해당 인벤토리.

• get_network_overview — 통합된 네트워크 상태 스냅샷.

상태 점검

• list_health_alerts — 활성 AFC 상태 경고.

• run_health_check — 통합 상태(경고, 스위치/패브릭 상태, BGP/OSPF 인접성, 선택에 따라 HA + 라이선스 상태).

통합 및 VMware vCenter/vSphere

• list_integrations — 모든 통합 팩, 원격 서버 및 연결 상태.

• list_vmware_integrations — vSphere 전용: 구성된 각 vCenter에 대해 서버 주소, 연결 상태 및 오류 메시지를 표시합니다.

• get_vmware_inventory — 위치(vCenter, 데이터센터, 클러스터, 도메인)와 상태(물리 NIC 상태, VM 전원 현황)를 포함한 VMware 호스트와 vSwitches, 포트 그룹, VM. ESXi 호스트 이름으로 필터링할 수 있습니다.

• list_vmware_vms — 전원 상태와 배치(ESXi 호스트, 클러스터, 데이터센터, vCenter), IP 및 태그가 포함된 플랫한 VM 인벤토리. 선택 필터: power_state, host_name.

• get_vm_attachment — VM의 종단 간 네트워크 연결(vNIC → Port Group → vSwitch → 호스트 업그널 → 실제 스위치/포트)을 추적합니다.

참고 사항

• AFC_BASE_URL은 /api 없이 호스트 루트여야 합니다. 클라이언트는 /api 접두사를 자동으로 추가합니다.

• API 인증은 X-Auth-Username 및 X-Auth-Password 헤더와 함께 POST /api/auth/token을 사용합니다. 토큰은 재사용되며 401일 때 자동으로 갱신됩니다.

• vSphere 패키지는 호스트별 전원/상태 필드를 노출하지 않습니다. 호스트 상태는 물리 NIC 상태와 VM 전원 개수로 도출됩니다. vcenter는 vSphere 인스턴스 UUID입니다.