ArubaOS-CX MCP Server (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、ポート認証、virtual-MAC、ARC — それぞれに verify_* 読み戻しツールが付属しています。

• 安全対策:

  • デバイスごとの access_mode(デフォルトは read-only。デバイスが明示的に read-write に設定されていない限り、書き込みは拒否されます)。

  • デバイスのグループに対して操作を行うためのサイト単位の操作(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 に設定してください。

ツール公開: フラットツールセット(デフォルト)と従来のアトミックツール

サーバーはその機能を、CX_FLAT_TOOLSET フラグによって選択される 相互排他的な 2 つの方法で公開できます(§5 を参照):

フラットツールセット (CX_FLAT_TOOLSET=true — デフォルト)。 上記の ~101 個のアトミックツールは、scope(書き込みの場合は action)引数によって駆動される ~23 個のフラットディスパッチャーに集約されます。基盤となる REST クライアントコードは変更されていません — ディスパッチャーはそこへのルーティングのみを行うため、動作の回帰はありません。すべての読み取りディスパッチャーは、device: str | list、site、または source(外部のソース・オブ・トゥルースのクエリ)も受け付け、呼び出しを並列にファンアウトして、1 つのエンベロープ {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)。 上記の完全なツール別カタログが代わりに公開され、必要に応じて以下の3つのレイヤーで整形されます。以前の動作に即座にロールバックするにはこれを使用します。

プログレッシブディスクロージャー、機能プレフィックス、書き込み安全性(レガシーモードのみ)

3つのオプションレイヤー(CX_FLAT_TOOLSET=falseの場合のみ有効、それぞれ独自の環境フラグで制御 — §5を参照)が、レガシーツールの公開方法を形作ります:

1. プログレッシブディスクロージャー(CX_DEFERRED_TOOLS) — 完全なカタログ(100以上のツール)を公開する代わりに、サーバーは約~27のTier-1ツール(最も使用される読み取り/診断ツール、エスケープハッチ、オーケストレーター、メタツール)のみを公開します。その他のツールはすべて**遅延(Tier-2)**となり、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アクセスも設定されている必要があります。それを必要とするツールのために、対象デバイスで。

設定(初回実行)

シークレットとデプロイメント固有の設定はdocker-compose.ymlの外部、git-ignoredされたファイルに置かれ、コミットされることはありません。2つのテンプレートが同梱されています — それぞれをコピーして記入してください:

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が含まれています。gitで追跡されるのは*.exampleテンプレートのみです。

ビルドと起動(全プラットフォーム)

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に続いて完全なトレースバックをログに記録します(その後、非ゼロで終了します)。

注: 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. ボリューム

3つのホストフォルダーがコンテナにマウントされます:

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-ignoredされた**.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（Vaultから認証情報を取得する場合は true）。

サイト

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.

コンテナは非ゼロのステータスコードで終了します（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で拒否されます（フェイルクローズ）ので、サービスには到達できません。 最初のトークンを作成し（§8を参照）、コンテナを再起動してロックを解除してください — トークンストアは起動時に一度だけ読み込まれます。

• 監査（CX_AUDIT_ENABLED=true）：logs/audit.jsonl にツール呼び出しごとに1つの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_ プレフィックスが付きます。クライアント/エージェントごとに 1つの異なるトークンを使用して、監査ログでアクターごとの属性を取得します。

最初のトークン： 認証が有効な場合、サーバーはトークンが存在するまで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" }
    }
  }
}