VMware Aria Operations

VMware Aria Operations MCP Skill

Note: In VCF 9.0 and later, VMware Aria Operations has been rebranded as VCF Operations. This skill works against both names — the /suite-api/ REST endpoints are unchanged.

Author: Wei Zhou, VMware by Broadcom — wei-wz.zhou@broadcom.com This is a community-driven project by a VMware engineer, not an official VMware product. For official VMware developer tools see developer.broadcom.com.

AI-assisted monitoring and capacity planning for VMware Aria Operations (vRealize Operations) via the Model Context Protocol (MCP).

Upgrading to 2.0

2.0 renames 4 of its MCP tools so every name starts with a verb (e.g. findings_list → list_findings, fleet_certificate_list → list_fleet_certificates, fleet_domain_list → list_fleet_domains). The full old → new table is in RELEASE_NOTES.md. Nothing else changes: same tools, parameters, safety gates and CLI commands. If an agent prompt, script or ~/.vmware/rules.yaml names a tool, update it — though deny rules written with the old names keep working with vmware-policy ≥ 1.18 (vmware-audit policy lists any rule the renames widened), and vmware-pilot ≥ 1.13 translates old names in saved workflows. If an install older than 2.0 shares that rules.yaml, give it vmware-policy ≥ 1.18.2 too: it matches each rule against both the old and the new name, so one file serves both.

Overview

vmware-aria exposes 46 MCP tools for interacting with Aria Operations through natural language AI agents (Claude Code, Cursor, Goose, etc.):

Category	Tools	Type
Resources	list, get, metrics, health badge, top consumers, metric keys, properties, relationships	Read-only (8)
Alerts	list, get, investigate (alert→resource), acknowledge, cancel, definitions, notes (list / add), recommendations	Read + 3 Write (9)
Alert Definitions	symptom definitions, create, enable/disable, delete	Read + 3 Write (4)
Capacity	overview, remaining, time-remaining, rightsizing	Read-only (4)
Reports	definitions, generate, list, get, delete	Read + 2 Write (5)
Anomaly	list anomalies, risk badge	Read-only (2)
Health	platform health, collector groups, Aria node memory/swap/heap, adapter collection state	Read-only (4)
Maintenance	start / end resource maintenance, maintenance schedules	Read + 2 Write (3)
Fleet / PromQL (VCF Ops 9.1)	fleet certificates, password accounts, VCF domains, diagnostic findings, real-time PromQL query	Read-only (5)
Raw API	search the API operation index, GET one indexed path — for reads no tool above covers	Read-only (2)

Total: 46 tools — 36 read-only, 10 write

Quick Start

# Install
uv tool install vmware-aria

# Configure
mkdir -p ~/.vmware-aria
cat > ~/.vmware-aria/config.yaml << 'EOF'
targets:
  prod:
    host: aria-ops.example.com
    username: admin
    port: 443
    verify_ssl: true
    auth_source: LOCAL
default_target: prod
EOF

# Set password (never in config.yaml)
echo "VMWARE_ARIA_PROD_PASSWORD=your_password" > ~/.vmware-aria/.env
chmod 600 ~/.vmware-aria/.env

# Verify setup
vmware-aria doctor

Offline / Air-Gapped Install (from source)

This project uses the modern PEP 517 build system (hatchling), so there is no setup.py by design — that is expected, not a missing file. If you cloned the source and hit ERROR: File "setup.py" or "setup.cfg" not found ... editable mode currently requires a setuptools-based build, your pip is older than 21.3 and cannot do an editable (-e) install with a non-setuptools backend. Editable mode is a developer convenience, not needed to run the tool — do one of:

# From the source tree — a normal (non-editable) install builds a wheel:
pip install .              # NOT  pip install -e .

# ...or upgrade pip first, and editable works too:
pip install --upgrade pip && pip install -e .

For a truly air-gapped host, build the wheels on a connected machine and copy them over — the target then needs no network:

# On a connected machine, collect this package + its dependencies as wheels:
pip wheel . -w dist        # → dist/*.whl   (or: uv build, for just this package)

# Copy dist/ to the air-gapped host, then install offline:
pip install --no-index --find-links dist vmware-aria

CLI Examples

# List top CPU consumers
vmware-aria resource top --metric 'cpu|usage_average' --top 10

# Check active CRITICAL alerts
vmware-aria alert list --criticality CRITICAL

# Acknowledge an alert
vmware-aria alert acknowledge <alert-id>

# Fetch 4-hour CPU + memory metrics for a VM ("missing" says why a key has no points)
vmware-aria resource metrics <vm-id> --metrics 'cpu|usage_average,mem|usage_average' --hours 4

# Check cluster capacity
vmware-aria capacity remaining <cluster-id>
vmware-aria capacity time-remaining <cluster-id>

# Find rightsizing opportunities (vCPU / memory now → recommended, direction, actionable)
vmware-aria capacity rightsizing

# Check Aria platform health: HEALTHY / DEGRADED / DOWN / UNKNOWN, per service, plus version
vmware-aria health status
vmware-aria health collectors

# Is the Aria node short of memory? Which adapter stopped collecting?
vmware-aria health node
vmware-aria health adapters

# Look up the metric keys a VM reports before querying them
vmware-aria resource keys <vm-id> --filter 'mem|'

# Put a host in maintenance for 2 hours before planned work, then end it (asks once; --dry-run prints the API call)
vmware-aria maintenance start <host-id> --duration 120
vmware-aria maintenance end <host-id>

# Record who is handling an alert, and read what Aria recommends
vmware-aria alert note-add <alert-id> "Taking this: rebooting esx-03"
vmware-aria alert recommendations <alert-id>

MCP Setup (Claude Code)

After uv tool install vmware-aria, add to ~/.claude.json:

{
  "mcpServers": {
    "vmware-aria": {
      "command": "vmware-aria",
      "args": ["mcp"],
      "env": {
        "VMWARE_ARIA_CONFIG": "~/.vmware-aria/config.yaml"
      }
    }
  }
}

v1.5.15+ uses the single-command form vmware-aria mcp. The legacy vmware-aria-mcp console script is still kept for backward compatibility. If you must use uvx --from vmware-aria vmware-aria mcp (no install) and hit invalid peer certificate: UnknownIssuer behind a corporate TLS proxy, set UV_NATIVE_TLS=true or use the recommended vmware-aria mcp form above.

Then use natural language:

• "Show me the top 10 CPU consumers right now"
• "List all CRITICAL alerts and acknowledge them"
• "How long until the prod cluster runs out of memory?"
• "Which VMs are over-provisioned? Show rightsizing recommendations"
• "Are there any anomalies on vm-web-01?"

Authentication

Aria Operations uses vRealizeOpsToken authentication:

POST /suite-api/api/auth/token/acquire
{"username": "admin", "password": "...", "authSource": "LOCAL"}
→ {"token": "abc123", "validity": 1765182896000}  # validity = expiry epoch ms

Subsequent requests: Authorization: vRealizeOpsToken abc123

Tokens have a 6-hour sliding validity (extended on each call, per the official spec); the client re-acquires automatically 60 seconds before expiry. The validity field is the expiry timestamp in epoch milliseconds, not a duration.

Architecture

User (natural language)
  ↓
AI Agent (Claude Code / Goose / Cursor)
  ↓  [reads SKILL.md]
vmware-aria MCP server (stdio transport)
  ↓  [HTTPS + vRealizeOpsToken]
Aria Operations Suite API
  ↓
VMs / Hosts / Clusters / Alerts / Capacity

Companion Skills

Skill	Scope	Tools	Install
vmware-aiops ⭐ entry point	VM lifecycle, deployment, guest ops, clusters	60	uv tool install vmware-aiops
vmware-monitor	Read-only monitoring, alarms, events, VM info	32	uv tool install vmware-monitor
vmware-nsx	NSX networking: segments, gateways, NAT, IPAM	33	uv tool install vmware-nsx-mgmt
vmware-nsx-security	DFW microsegmentation, security groups, Traceflow	22	uv tool install vmware-nsx-security
vmware-avi	AVI / NSX ALB load balancing, AKO K8s operations	28	uv tool install vmware-avi
vmware-storage	Datastores, iSCSI, vSAN	12	uv tool install vmware-storage
vmware-vks	Tanzu Namespaces, TKC cluster lifecycle	23	uv tool install vmware-vks
vmware-harden	Compliance baselines, drift detection	8	uv tool install vmware-harden

Security

• Passwords loaded from env vars or .env file, never from config.yaml
• Every MCP tool call and every CLI command that reaches Aria audit-logged to ~/.vmware/audit.db (via vmware-policy); CLI write operations (alert acknowledge/cancel, alert notes, alert definition management, report generate/delete, resource maintenance start/end) also append to ~/.vmware-aria/audit.log
• API responses sanitized (control chars stripped, 500-char limit) to prevent prompt injection
• MCP destructive writes (alert acknowledge/cancel, alert definition and report delete, maintenance start/end) take confirm (default false): without confirm=true they return a blast_radius of what would change and change nothing; confirm=true is refused on a blocker (e.g. a resource already in maintenance) or an unreadable field. confirmed is a deprecated alias
• TLS verification is on by default; for a private CA set SSL_CERT_FILE to a bundle with your CA (see setup guide). verify_ssl: false is for isolated self-signed labs only

Official Broadcom References

• REST APIs: https://developer.broadcom.com/xapis — VCF Operations API (formerly Aria Operations suite-api)
• SDKs: https://developer.broadcom.com/sdks — VCF Python SDK
• CLI Tools: https://developer.broadcom.com/tools — PowerCLI 9.1 includes "VCF Operations (formerly vRealize Operations Manager)" cmdlets

Remote access (HTTPS) and limiting tools

By default vmware-aria mcp speaks stdio to one local client and offers every tool. Two options change that (vmware-policy ≥ 1.21.0).

Serve over HTTPS so clients on other machines can connect. Every caller needs a bearer token:

vmware-audit token create alice          # prints the token once; give it to alice
vmware-audit token list                  # names only
vmware-audit token revoke alice          # refused from its next request, no restart
vmware-aria mcp --transport https --host 0.0.0.0 --port 8443 \
    --cert /etc/vmware-mcp/server.pem --key /etc/vmware-mcp/server-key.pem \
    --public-name mcp.example.com

Connect a client (Claude Code shown; any MCP client that supports streamable HTTP and custom headers works):

claude mcp add --transport http vmware-aria https://mcp.example.com:8443/mcp \
    --header "Authorization: Bearer $VMWARE_MCP_TOKEN"

{
  "mcpServers": {
    "vmware-aria": {
      "type": "http",
      "url": "https://mcp.example.com:8443/mcp",
      "headers": { "Authorization": "Bearer ${VMWARE_MCP_TOKEN}" }
    }
  }
}

• The server will not start without a token, refuses Host/Origin values outside --public-name, and checks before it binds that unauthenticated requests get 401. Use a certificate your clients trust for those names.
• Behind a TLS-terminating reverse proxy on the same machine use --transport http --host 127.0.0.1 --public-name mcp.example.com and pass the Authorization header through.
• Behind a load balancer or gateway on another machine, keep --transport https (a self-signed certificate is fine), list in --public-name the host name the balancer sends as Host, and have it forward Authorization. Its health probe can use GET /healthz, which needs no token and returns only {"status": "ok"} (vmware-policy ≥ 1.23.0).
• Send traceparent or X-Request-ID with each request to have it stored on the audit row; vmware-audit log --correlation-id ID then finds the calls behind one platform request.
• The audit log records each caller as token:<name>. Calls run side by side: each holds its own session to a target, up to VMWARE_MCP_POOL_SIZE (default 2) sessions per target. Each session is a login on the target; a call waits at most 300 s for a free one.
• Everyone who can reach the endpoint acts with this server's account. Tokens identify callers; they grant nothing on the platform. Run one endpoint per privilege level.
• Several people or roles on one endpoint: run vmware-audit roles enable once, then give each token a role (vmware-audit token create NAME --role reader, or a role in roles.yaml naming tools and targets; vmware-policy ≥ 1.24.0). A role limits what the token may call on this endpoint; it cannot grant more than the account has. See vmware-policy's README, "Roles for network callers".

Offer only read tools, plus the writes you choose:

vmware-aria mcp --expose read --allow-write acknowledge_alert
# or: VMWARE_ARIA_MCP_EXPOSE=read VMWARE_ARIA_MCP_ALLOW_WRITE=acknowledge_alert vmware-aria mcp

Tools not offered do not appear in the client's tool list. A bad value or an unknown write tool stops the server (exit 2). This limits what clients are offered; it is not authorization, so the account itself should be least-privilege.

Details: skills/vmware-aria/references/setup-guide.md ("Serving MCP over HTTPS", "Limiting which tools are offered").

License

MIT — see LICENSE