nutanix-mcp

Multimandantenfähige Streamable-HTTP-Brücke über nutanix/ntnx-api-mcp-server – dem offiziellen Nutanix Prism Central v4 API MCP-Server – entwickelt, damit das WYRE-Conduit-Gateway mandantenspezifische Nutanix-Anmeldeinformationen als HTTP-Header weiterleiten kann.

Upstream-Pin: Der Nutanix-Server befindet sich in der technischen Vorschau und ist hier auf Tag v0.8 (Apache-2.0) festgelegt. Siehe Aktualisieren des Upstream-Pins.

Warum

Der Upstream-Server ist rein stdio-basiert (nutanix-mcp serve-stdio ist sein einziger Serve-Modus) und liest seine Prism-Central-Anmeldeinformationen aus Umgebungsvariablen beim Start des Prozesses – ein Mandant pro Prozess. Unser Gateway ist multimandantenfähig: Jede Anfrage trägt die Anmeldeinformationen der aufrufenden Organisation als HTTP-Header mit, und der Vendor-Container muss diese Header in etwas übersetzen, das der Upstream versteht.

Da der Upstream keinen HTTP-Modus hat, an den ein Proxy weiterleiten könnte, unterhält diese Brücke eine MCP-Client-Sitzung über stdio zu jedem Mandanten-Kindprozess und stellt sie erneut über Streamable HTTP bereit:

1. Lauscht auf :8080 mit POST /mcp und GET /health.

2. Schützt jede /mcp-Anfrage mit einem 401-Gate auf den X-Nutanix-Pc-*-Anmeldeheader (siehe unten). Fehlende oder ungültige Anmeldeinformationen gelangen niemals zu Umgebungsvariablen – das wäre ein mandantenübergreifendes Leck.

3. Startet bei Bedarf einen nutanix-mcp serve-stdio-Kindprozess pro Anmeldeinformations-Tupel (gehasht), mit den PC_*-Umgebungsvariablen des Mandanten, und verbindet einen MCP-Client über stdio damit.

4. Bedient beide Protokoll-Ären auf /mcp über die createMcpHandler(factory, { legacy: 'stateless' }) des SDK v2 – Clients mit initialize-Handshake aus dem Jahr 2025 (aktuell das Conduit-Gateway) und moderne 2026-07-28-Envelope-Clients. tools/list und tools/call delegieren an die Kind-Sitzung des Mandanten.

5. Entfernt inaktive Kindprozesse nach 60 Minuten (IDLE_EVICT_MS).

Toolnamen werden unverändert durchgereicht: die 24 Tools des Upstreams – 20 {namespace}_execute-Tools (aiops, clustermgmt, datapolicies, dataprotection, files, iam, licensing, lifecycle, microseg, monitoring, multidomain, networking, objects, opsmgmt, prism, security, storage, tenancy, vmm, volumes) plus 4 Discovery-Tools (listOperations, getOperationSchema, getCodeSample, getOperationPermissions).

Nur Lesezugriff in v1 – bewusst

Jeder Kindprozess wird mit READ_ONLY_MODE=true gestartet (auch die Upstream-Voreinstellung): Der Upstream lehnt alle Nicht-GET-Operationen ab, bevor sie Prism Central überhaupt erreichen. v1 dieser Brücke liefert standardmäßig schreibgeschützten Zugriff als bewusste Flottenentscheidung. Schreibunterstützung wäre eine geprüfte, versionierte Änderung an credentialsToChildEnv() in src/credentials.ts – kein Konfigurationsschalter.

Anmeldeinformationsvertrag

Das Gateway leitet diese Header bei jeder /mcp-Anfrage weiter; die Brücke bildet sie auf die Umgebung des Kindprozesses ab. Die Vendor-Konfiguration von Conduit muss exakt dieser Tabelle entsprechen.

Gültigkeitsregel: pcHost vorhanden UND (apiKey vorhanden ODER username+password vorhanden). Alles andere → HTTP 401 mit einem JSON-RPC-Fehlertext.

API-Spezifikationsartefakte (zur Build-Zeit eingebacken)

Der Upstream baut seine Tool-Oberfläche aus YAML-API-Spezifikationsartefakten, nicht aus der laufenden PC-Instanz. nutanix-mcp init lädt sie herunter – und ohne PC-Anmeldeinformationen läuft es im Modus latest_release gegen die öffentliche Namespace-API von developers.nutanix.com (kein PC-Zugriff erforderlich; empirisch bestätigt: 20 Namespaces). Der Docker-Build führt init einmal aus und backt die Artefakte in das Image unter /opt/nutanix-mcp/artifacts, schreibgeschützt für alle Mandanten-Kindprozesse. Folgen:

• tools/list und die Discovery-Tools funktionieren ohne erreichbare PC – nur {namespace}_execute-Aufrufe greifen auf Prism Central zu.

• Die Artefaktversionen entsprechen der neuesten öffentlichen Version zum Zeitpunkt des Image-Builds, nicht den exakten Versionen der Mandanten-PC (der pc_compatible-Modus des Upstreams würde Live-PC-Zugriff beim Start benötigen). Für die schreibgeschützte v1-Oberfläche ist dies der richtige Kompromiss: gemeinsame Artefakte, schnelle Mandantenstarts.

Konfiguration

Lokale Entwicklung

# 1. Get the upstream at the pinned tag with a venv + artifacts
git clone --branch v0.8 --depth 1 https://github.com/nutanix/ntnx-api-mcp-server ../ntnx-api-mcp-server
cd ../ntnx-api-mcp-server
uv venv .venv && uv pip install .
ARTIFACTS_DIR=$PWD/artifacts .venv/bin/nutanix-mcp init   # no PC creds needed
cd -

# 2. Build and run the bridge against it
npm ci && npm run build && npm test
NUTANIX_MCP_DIR=../ntnx-api-mcp-server node dist/index.js

# 3. Smoke it
curl -s localhost:8080/health
curl -s localhost:8080/mcp -X POST \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -H 'X-Nutanix-Pc-Host: pc.example.com' -H 'X-Nutanix-Pc-Api-Key: fake' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"dev","version":"0"}}}'

Oder erstellen Sie das Image (es backt alles ein, einschließlich eines stdio-Smoketests, der den Build fehlschlagen lässt, wenn serve-stdio nicht auf tools/list antwortet):

docker build --platform linux/amd64 -t ghcr.io/wyre-technology/nutanix-mcp:dev .
docker run --rm -p 8080:8080 ghcr.io/wyre-technology/nutanix-mcp:dev

Aktualisieren des Upstream-Pins

Der Upstream ist im Dockerfile auf den geprüften Tag v0.8 (NUTANIX_MCP_REF) festgelegt – niemals main (NSA-MCP-Richtlinie / Flotten-Sicherheitsbaseline). Zum Aktualisieren:

1. Überprüfen Sie das Upstream-Diff zwischen dem aktuellen Pin und dem neuen Tag (Tool-Oberfläche, Anmeldeinformationsbehandlung, READ_ONLY_MODE-Semantik).

2. Ändern Sie NUTANIX_MCP_REF im Dockerfile und den Tag in dieser README.

3. docker build lokal ausführen – die Build-Zeit-Smoketests prüfen, ob der Venv-Einstiegspunkt läuft und die stdio-Tool-Oberfläche noch antwortet (aktualisieren Sie die erwartete Tool-Anzahl, wenn sich die Namespaces geändert haben).

4. Als feat:/fix:-PR einreichen, damit semantic-release eine Version erstellt.

Lizenz

Apache-2.0. Der gebündelte ntnx-api-mcp-server ist Apache-2.0 von Nutanix.