nutanix-mcp

Мультитенантный мост Streamable HTTP поверх nutanix/ntnx-api-mcp-server — официального MCP-сервера Nutanix для API Prism Central v4 — создан для того, чтобы шлюз WYRE conduit мог передавать учетные данные Nutanix для каждого арендатора в виде HTTP-заголовков.

Фиксация исходной версии: Сервер Nutanix является технической предварительной версией, зафиксированной здесь на теге v0.8 (Apache-2.0). См. Обновление фиксации исходной версии.

Зачем

Вышестоящий сервер работает только через stdio (nutanix-mcp serve-stdio — единственный режим обслуживания) и считывает учетные данные Prism Central из переменных окружения при запуске процесса — один арендатор на процесс. Наш шлюз является мультитенантным: каждый запрос содержит учетные данные вызывающей организации в виде HTTP-заголовков, и контейнер поставщика должен преобразовать эти заголовки в формат, понятный вышестоящему серверу.

Поскольку у вышестоящего сервера нет HTTP-режима для проксирования, этот мост удерживает сессию MCP-клиента через stdio для каждого дочернего процесса арендатора и повторно обслуживает её через Streamable HTTP:

1. Слушает порт :8080 с POST /mcp и GET /health.

2. Каждый запрос /mcp проверяется на наличие заголовков учетных данных X-Nutanix-Pc-* и при их отсутствии возвращает 401. Отсутствующие/недействительные учетные данные никогда не передаются в окружение — это привело бы к утечке между арендаторами.

3. Лениво порождает один дочерний процесс nutanix-mcp serve-stdio на каждый набор учетных данных (ключом является хеш), устанавливая соответствующие переменные окружения PC_*, и подключает к нему MCP-клиента через stdio.

4. Обслуживает обе эры протокола на /mcp через createMcpHandler(factory, { legacy: 'stateless' }) из SDK v2 — клиенты с рукопожатием initialize 2025-го года (текущий шлюз conduit) и современные клиенты с конвертом 2026-07-28. tools/list и tools/call делегируются дочерней сессии арендатора.

5. Удаляет бездействующие дочерние процессы через 60 минут (IDLE_EVICT_MS).

Имена инструментов передаются без изменений: 24 инструмента вышестоящего сервера — 20 инструментов {namespace}_execute (aiops, clustermgmt, datapolicies, dataprotection, files, iam, licensing, lifecycle, microseg, monitoring, multidomain, networking, objects, opsmgmt, prism, security, storage, tenancy, vmm, volumes) плюс 4 инструмента обнаружения (listOperations, getOperationSchema, getCodeSample, getOperationPermissions).

Только чтение в v1 — осознанное решение

Каждый дочерний процесс запускается с READ_ONLY_MODE=true (также значение по умолчанию вышестоящего сервера): вышестоящий сервер отклоняет все операции, не являющиеся GET, до того, как они достигнут Prism Central. Версия v1 этого моста поставляется в режиме только чтения как осознанное решение для всего парка. Поддержка записи будет представлять собой проверенное, версионированное изменение credentialsToChildEnv() в src/credentials.ts, а не переключение конфигурации.

Контракт учетных данных

Шлюз передает следующие заголовки в каждом запросе /mcp; мост отображает их в окружение дочернего процесса вышестоящего сервера. Конфигурация поставщика conduit должна точно соответствовать этой таблице.

Правило валидности: присутствует pcHost И (присутствует apiKey ИЛИ присутствуют username+password). В противном случае → HTTP 401 с телом ошибки JSON-RPC.

READ_ONLY_MODE=true дополнительно принудительно устанавливается для каждого дочернего процесса (см. выше).

Артефакты спецификации API (встроены во время сборки)

Вышестоящий сервер строит свою поверхность инструментов на основе YAML-артефактов спецификации API, а не на живом PC. nutanix-mcp init загружает их — и без учетных данных PC он работает в режиме latest_release через публичный API пространства имен developers.nutanix.com (доступ к PC не требуется; подтверждено эмпирически: 20 пространств имен). Сборка Docker запускает init один раз и встраивает артефакты в образ по пути /opt/nutanix-mcp/artifacts, доступный только для чтения всем дочерним процессам арендаторов. Последствия:

• tools/list и инструменты обнаружения работают без доступного PC — только вызовы {namespace}_execute обращаются к Prism Central.

• Версии артефактов — это последняя публичная версия на момент сборки образа, а не точные версии PC арендатора (режим pc_compatible вышестоящего сервера потребовал бы доступа к живому PC при порождении). Для поверхности только чтения v1 это правильный компромисс: общие артефакты, быстрое порождение арендаторов.

Конфигурация

Локальная разработка

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

Или создайте образ (он встраивает всё, включая тест stdio, который завершает сборку ошибкой, если serve-stdio не может ответить на 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

Обновление фиксации исходной версии

Исходная версия зафиксирована на проверенном теге v0.8 в Dockerfile (NUTANIX_MCP_REF) — никогда не main (рекомендации NSA по MCP / базовый уровень безопасности парка). Чтобы обновить:

1. Проверьте различия исходной версии между текущей фиксацией и новым тегом (поверхность инструментов, обработка учетных данных, семантика READ_ONLY_MODE).

2. Измените NUTANIX_MCP_REF в Dockerfile и тег в этом README.

3. Выполните docker build локально — тесты на этапе сборки проверяют, что точка входа venv запускается и поверхность инструментов stdio всё ещё отвечает (обновите ожидаемое количество инструментов, если изменились пространства имен).

4. Оформите как PR с типом feat:/fix:, чтобы semantic-release создал версию.

Лицензия

Apache-2.0. Включенный ntnx-api-mcp-server распространяется под лицензией Apache-2.0 от Nutanix.