nutanix-mcp

Puente HTTP Streamable Multitenant sobre nutanix/ntnx-api-mcp-server — el servidor MCP oficial de la API v4 de Prism Central de Nutanix — construido para que la puerta de enlace WYRE conduit pueda reenviar credenciales de Nutanix por inquilino como cabeceras HTTP.

Pin ascendente: El servidor de Nutanix es una vista previa técnica, anclado aquí en la etiqueta v0.8 (Apache-2.0). Consulte Actualizando el pin ascendente.

Por qué

El servidor ascendente es solo stdio (nutanix-mcp serve-stdio es su único modo de servicio) y lee sus credenciales de Prism Central de variables de entorno al inicio del proceso — monoinquilino por proceso. Nuestra puerta de enlace es multiinquilino: cada solicitud lleva las credenciales de la organización que llama como cabeceras HTTP, y el contenedor del proveedor debe traducir esas cabeceras a algo que el ascendente entienda.

Debido a que el ascendente no tiene un modo HTTP al que hacer proxy, este puente mantiene una sesión de cliente MCP sobre stdio para cada hijo inquilino y la vuelve a servir sobre Streamable HTTP:

1. Escucha en :8080 con POST /mcp y GET /health.

2. Protege con 401 cada solicitud /mcp en las cabeceras de credenciales X-Nutanix-Pc-* (abajo). Las credenciales faltantes o inválidas nunca pasan a las credenciales de entorno — eso sería una fuga entre inquilinos.

3. Lanza perezosamente un hijo nutanix-mcp serve-stdio por tupla de credenciales (clave por un hash), con las variables de entorno PC_* del inquilino establecidas, y conecta un cliente MCP a él sobre stdio.

4. Sirve ambas eras de protocolo en /mcp a través del createMcpHandler(factory, { legacy: 'stateless' }) del SDK v2 — clientes de apretón de manos initialize de la era 2025 (la puerta de enlace conduit hoy) y clientes modernos de sobre 2026-07-28. tools/list y tools/call delegan a la sesión hija del inquilino.

5. Desaloja hijos inactivos después de 60 minutos (IDLE_EVICT_MS).

Los nombres de las herramientas pasan sin cambios: las 24 herramientas del ascendente — 20 herramientas {namespace}_execute (aiops, clustermgmt, datapolicies, dataprotection, files, iam, licensing, lifecycle, microseg, monitoring, multidomain, networking, objects, opsmgmt, prism, security, storage, tenancy, vmm, volumes) más 4 herramientas de descubrimiento (listOperations, getOperationSchema, getCodeSample, getOperationPermissions).

Solo lectura en v1 — deliberado

Cada hijo se lanza con READ_ONLY_MODE=true (también el valor predeterminado del ascendente): el ascendente rechaza todas las operaciones que no sean GET antes de que lleguen a Prism Central. v1 de este puente se envía como solo lectura como una decisión de flota deliberada. El soporte de escritura sería un cambio revisado y versionado en credentialsToChildEnv() en src/credentials.ts — no un cambio de configuración.

Contrato de credenciales

La puerta de enlace reenvía estas cabeceras en cada solicitud /mcp; el puente las asigna al entorno del hijo ascendente. La configuración del proveedor de conduit debe coincidir exactamente con esta tabla.

Regla de validez: pcHost presente Y (apiKey presente O username+password presente). Cualquier otra cosa → HTTP 401 con un cuerpo de error JSON-RPC.

READ_ONLY_MODE=true se fuerza adicionalmente en cada hijo (ver arriba).

Artefactos de especificación de API (horneados en tiempo de compilación)

El ascendente construye su superficie de herramientas a partir de artefactos de especificación de API YAML, no de la PC en vivo. nutanix-mcp init los descarga — y sin credenciales de PC se ejecuta en modo latest_release contra la API de espacio de nombres pública developers.nutanix.com (sin acceso a PC requerido; verificado empíricamente: 20 espacios de nombres). La compilación de Docker ejecuta init una vez y hornea los artefactos en la imagen en /opt/nutanix-mcp/artifacts, compartidos como solo lectura por todos los hijos inquilinos. Consecuencias:

• tools/list y las herramientas de descubrimiento funcionan sin una PC accesible — solo las llamadas {namespace}_execute tocan Prism Central.

• Las versiones de los artefactos son la última versión pública en el momento de la compilación de la imagen, no las versiones exactas de la PC del inquilino (el modo pc_compatible del ascendente necesitaría acceso a PC en vivo al lanzar). Para la superficie de solo lectura v1 esta es la compensación correcta: artefactos compartidos, lanzamientos rápidos de inquilinos.

Configuración

Desarrollo local

# 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"}}}'

O construya la imagen (hornea todo, incluyendo una prueba de humo stdio que falla la compilación si serve-stdio no puede responder tools/list):

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

Actualizando el pin ascendente

El ascendente está anclado a la etiqueta revisada v0.8 en el Dockerfile (NUTANIX_MCP_REF) — nunca main (guía MCP de la NSA / línea base de seguridad de la flota). Para actualizar:

1. Revise el diff ascendente entre el pin actual y la nueva etiqueta (superficie de herramientas, manejo de credenciales, semántica de READ_ONLY_MODE).

2. Cambie NUTANIX_MCP_REF en el Dockerfile y la etiqueta en este README.

3. docker build localmente — las pruebas de humo en tiempo de compilación afirman que el punto de entrada del venv se ejecuta y la superficie de herramientas stdio todavía responde (actualice el recuento de herramientas esperado si los espacios de nombres cambiaron).

4. Entregue como un PR feat:/fix: para que semantic-release corte una versión.

Licencia

Apache-2.0. El ntnx-api-mcp-server incluido es Apache-2.0 de Nutanix.