AriaOps MCP 服务器

AriaOps MCP Server

A Model Context Protocol (MCP) server for VMware Aria Operations (on-prem). Exposes Aria Ops REST API capabilities as MCP tools so AI assistants can query infrastructure health, alerts, metrics, capacity, and reports — and optionally perform write operations when explicitly enabled.

Features

• Resources — list, search, query VMs/hosts/clusters and their properties
• Alerts — active alerts, definitions, notes, contributing symptoms
• Metrics — stats over time, latest values, bulk queries, Top-N
• Capacity — remaining capacity per cluster, time-to-full, policy thresholds
• Reports — list templates, generated reports, download (PDF/CSV)
• Discovery — version info, collectors, symptom definitions, recommendations
• Write operations (opt-in) — modify alerts, maintenance mode, schedules, report generation, resource lifecycle

Supports both stdio (local/testing) and streamable HTTP (production) transports.

Requirements

• Python 3.11+
• Access to an on-prem VMware Aria Operations 8.x instance
• Podman (optional, for containerized deployment)

Quick Start

Install

git clone https://github.com/asnd/ariaops-mcp.git
cd ariaops-mcp
pip install -e .

For development (includes linting and test tools):

pip install -e ".[dev]"

Configure

cp .env.example .env
# Edit .env with your Aria Ops credentials

ARIAOPS_HOST=vrops.example.com
ARIAOPS_USERNAME=admin
ARIAOPS_PASSWORD=secret
ARIAOPS_AUTH_SOURCE=local     # or your LDAP source name
ARIAOPS_VERIFY_SSL=true

Run (stdio — for MCP clients)

python -m ariaops_mcp

Run (HTTP — production)

ARIAOPS_TRANSPORT=http ARIAOPS_PORT=8080 python -m ariaops_mcp

To require OAuth 2.x bearer tokens on the HTTP transport, enable the flag and provide the resource-server settings:

ARIAOPS_TRANSPORT=http \
ARIAOPS_HTTP_OAUTH_ENABLED=true \
ARIAOPS_HTTP_OAUTH_ISSUER_URL=https://issuer.example.com \
ARIAOPS_HTTP_OAUTH_RESOURCE_SERVER_URL=https://mcp.example.com \
ARIAOPS_HTTP_OAUTH_JWT_KEY="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')" \
ARIAOPS_HTTP_OAUTH_REQUIRED_SCOPES=mcp:read \
python -m ariaops_mcp

OAuth knobs

Discovery: With OAuth enabled, the server publishes GET /.well-known/oauth-protected-resource per RFC 9728 so MCP clients auto-discover the authorization server and required scopes.

Health: GET /health is intentionally unauthenticated so probes and load balancers keep working with OAuth turned on.

Keycloak setup

Keycloak is a supported IdP. Use JWKS — Keycloak rotates RS256 keys.

1. Create a client in your realm (Clients → Create client):

   • Client type: OpenID Connect
   • Client authentication: on (confidential) for the MCP client
   • Valid redirect URIs: whatever your MCP client uses

2. Add an Audience mapper (Client scopes → <client>-dedicated → Add mapper → Audience):

   • Included Client Audience: the client ID you want as aud (e.g. mcp-client).
   • This is required because Keycloak does not put the resource URL in aud by default.

3. Add scope(s) (Client scopes → Create) and assign to the client (Default or Optional).

4. Configure ariaops-mcp:

   复制

   ARIAOPS_TRANSPORT=http \
   ARIAOPS_HTTP_OAUTH_ENABLED=true \
   ARIAOPS_HTTP_OAUTH_PROVIDER=keycloak \
   ARIAOPS_HTTP_OAUTH_ISSUER_URL=https://kc.example.com/realms/myrealm \
   ARIAOPS_HTTP_OAUTH_RESOURCE_SERVER_URL=https://mcp.example.com \
   ARIAOPS_HTTP_OAUTH_AUDIENCE=mcp-client \
   ARIAOPS_HTTP_OAUTH_REQUIRED_SCOPES=mcp:read \
   python -m ariaops_mcp
   

5. Test from the CLI with a client-credentials grant:

   复制

   TOKEN=$(curl -s -X POST \
     "https://kc.example.com/realms/myrealm/protocol/openid-connect/token" \
     -d grant_type=client_credentials \
     -d client_id=mcp-client \
     -d client_secret=$KC_SECRET \
     -d scope="mcp:read" | jq -r .access_token)
   
   curl -H "Authorization: Bearer $TOKEN" https://mcp.example.com/
   

Notes:

• iss in Keycloak tokens is exactly https://<host>/realms/<realm> (no trailing slash). The verifier strips trailing slashes on both sides, so either form works in config.
• ARIAOPS_HTTP_OAUTH_PROVIDER=keycloak derives ARIAOPS_HTTP_OAUTH_JWKS_URL as <issuer>/protocol/openid-connect/certs and defaults ARIAOPS_HTTP_OAUTH_JWT_ALGORITHMS to RS256 unless you explicitly set algorithms or ARIAOPS_HTTP_OAUTH_JWT_KEY.
• Roles (realm_access.roles, resource_access.<client>.roles) are not enforced — only OAuth scope. Map roles to scopes in Keycloak if you need RBAC.
• The verifier wraps PyJWKClient in asyncio.to_thread, so a JWKS cache miss does not block the event loop.

LDAP / Active Directory authentication

As an alternative to OAuth, the HTTP transport can authenticate MCP clients with HTTP Basic credentials verified against LDAPS. The server binds directly with the user's credentials (no service account), reads their memberOf groups, and maps them to the same role/country/instance claims the OAuth path uses — so role-based access works identically.

ARIAOPS_TRANSPORT=http \
ARIAOPS_HTTP_AUTH_MODE=ldap \
ARIAOPS_LDAP_SERVER_URI="ldaps://dc1.corp.example.com:636" \
ARIAOPS_LDAP_USER_DN_TEMPLATE="{username}@corp.example.com" \
ARIAOPS_LDAP_USER_SEARCH_BASE="dc=corp,dc=example,dc=com" \
ARIAOPS_LDAP_GROUP_ROLE_MAP='{"vrops-ops":{"role":"ops"},"vrops-se":{"role":"country","country":"SE"}}' \
python -m ariaops_mcp

/health stays unauthenticated, and instance authorization is enforced by the same principal layer as OAuth — LDAP only decides the caller's role/instance.

Security notes:

• Group lookup reads memberOf, which contains direct group memberships only — a user who is in a mapped group via a nested group will not receive its role. Map the groups users belong to directly (resolving nested membership via the AD matching-rule-in-chain OID 1.2.840.113556.1.4.1941 is a possible future extension).
• Failed binds are never cached, so every bad-password request reaches the directory. Put a rate limit on the MCP endpoint at your reverse proxy to protect against password spraying and AD account-lockout abuse.
• ARIAOPS_HTTP_OAUTH_REQUIRED_SCOPES is ignored in LDAP mode (Basic-auth requests carry no OAuth scopes); a warning is logged if it is set.

See AUTH_FLOW.md for a detailed message-flow walkthrough of both OAuth and LDAP modes, including middleware stack, token verification steps, cache behaviour, and principal resolution.

Run with Podman

podman build --format docker -t ariaops-mcp .
podman run --env-file .env -p 8080:8080 ariaops-mcp

Multiple Aria Operations instances

A single MCP server can front several Aria Operations instances. Define them with ARIAOPS_INSTANCES (a JSON array); when set, the legacy single-host variables (ARIAOPS_HOST/ARIAOPS_USERNAME/ARIAOPS_PASSWORD) are optional.

ARIAOPS_INSTANCES=[
  {"id":"us","host":"us.vrops.example.com","username":"svc","password":"secret","country":"US"},
  {"id":"de","host":"de.vrops.example.com","username":"svc","password":"secret","country":"DE"}
]

Each entry needs a unique id. Optional per-instance fields: auth_source (default local), verify_ssl (default true), and country (used to pin country-role users).

Role-based access

Access is scoped by the caller's role:

On the HTTP transport the role/country/instance are read from the validated JWT claims (claim names are configurable). On stdio (local) they fall back to the ARIAOPS_DEFAULT_* settings.

Every instance-bound tool accepts an optional instance argument, and the list_instances tool returns the instances the current caller may use. Backward compatibility is preserved: with only the legacy single-host variables set, a single default instance is synthesized and existing behavior is unchanged.

MCP Architecture

+---------------------------+     MCP (stdio / streamable HTTP)     +---------------------------+
| MCP Client / AI Assistant | <-----------------------------------> | ariaops-mcp server        |
| Claude Desktop, IDE, etc. |                                       |                           |
+-------------+-------------+                                       |  read tools: always on    |
              |                                                     |  write tools: opt-in      |
              |                                                     +-------------+-------------+
              |                                                                   |
              |                                                                   | HTTPS REST
              |                                                                   v
              |                                                     +---------------------------+
              +---------------------------------------------------> | VMware Aria Operations   |
                                                                    | /suite-api/api/...       |
                                                                    +---------------------------+

+-----------------------+      chat / tool plans      +-----------------------+
| Browser               | <-------------------------> | test-ui/app.py        |
| Gradio test UI        |                             | Gradio + tool bridge  |
+-----------+-----------+                             +-----+-----------+-----+
            |                                               |           |
            |                                               |           |
            |                                    LLM Gateway |           | in-process MCP tools
            v                                               v           v
  +-------------------+                           +----------------+  +----------------------+
  | Human operator    |                           | OpenAI-compat  |  | ariaops_mcp modules  |
  +-------------------+                           | model gateway  |  | + AriaOpsClient      |
                                                  +----------------+  +----------+-----------+
                                                                                  |
                                                                                  v
                                                                       +----------------------+
                                                                       | VMware Aria Ops      |
                                                                       +----------------------+

MCP Client Integration

Add to your MCP config (e.g. ~/.claude/mcp_settings.json for AI code assistants):

{
  "mcpServers": {
    "ariaops": {
      "command": "python",
      "args": ["-m", "ariaops_mcp"],
      "env": {
        "ARIAOPS_HOST": "vrops.example.com",
        "ARIAOPS_USERNAME": "admin",
        "ARIAOPS_PASSWORD": "secret"
      }
    }
  }
}

Available Tools

Write Tools (requires ARIAOPS_ENABLE_WRITE_OPERATIONS=true)

Full tool catalog: TOOLS.md

Full spec: REQUIREMENTS.md

Test UI App

The repo includes a Gradio-based test UI in test-ui/ for exercising the same tool handlers in-process while routing chat through an LLM gateway.

Create a local env file first so no tenant IDs, client IDs, or tokens need to be hardcoded in the repo:

cp .env.example .env

Set LITELLM_BASE_URL for the gateway. If you want to use the Get Token via Azure SSO button, also set:

AZURE_TENANT_ID=your-azure-tenant-id
AZURE_CLIENT_ID=your-azure-client-id

python -m pip install -r test-ui/requirements.txt
python test-ui/app.py --port 7860

To run its automated tests:

cd test-ui
pytest tests

Chainlit auth test harness

test-ui/chainlit/ is a minimal Chainlit frontend that tests both auth modes end-to-end. It proves the LDAP (Basic) and OAuth (Bearer) wiring without coupling the demo UI to Gradio.

cp test-ui/chainlit/.env.example test-ui/chainlit/.env
# edit .env: set ARIAOPS_MCP_URL + optional LITELLM_* vars
pip install chainlit httpx python-dotenv
chainlit run test-ui/chainlit/app.py -w

See CHAINLIT_AUTH.md for full configuration details.

OAuth2 end-to-end scenario

test-e2e/oauth/ contains a self-contained Podman scenario that spins up a real Keycloak IdP with two simulated users (alice=ops, bob=country/SE) and verifies token validation, role-based instance access, and instance enforcement over the streamable HTTP transport.

./test-e2e/oauth/run.sh        # build image, start stack, run 8 tests, leave running
./test-e2e/oauth/run.sh down   # tear down

See test-e2e/oauth/README.md for topology, user table, and proxy notes.

Development

pip install -e ".[dev]"
pytest                  # run tests
ruff check src/ tests/  # lint
pyright                 # type-check
cd test-ui && pytest tests

Configuration Reference

License

MIT