nutanix-mcp

멀티테넌트 Streamable HTTP 브리지 over nutanix/ntnx-api-mcp-server — Nutanix의 공식 Prism Central v4 API MCP 서버 — WYRE conduit 게이트웨이가 테넌트별 Nutanix 자격 증명을 HTTP 헤더로 전달할 수 있도록 구축되었습니다.

업스트림 고정: Nutanix의 서버는 기술 미리보기이며, 여기서는 태그 v0.8 (Apache-2.0)로 고정되어 있습니다. 업스트림 고정 업데이트를 참조하세요.

이유

업스트림 서버는 stdio 전용입니다 (nutanix-mcp serve-stdio가 유일한 서브 모드). 프로세스 시작 시 환경 변수에서 Prism Central 자격 증명을 읽습니다 — 프로세스당 단일 테넌트. 우리 게이트웨이는 멀티테넌트입니다: 모든 요청은 호출 조직의 자격 증명을 HTTP 헤더로 전달하며, 벤더 컨테이너는 해당 헤더를 업스트림이 이해할 수 있는 것으로 변환해야 합니다.

업스트림에 프록시할 HTTP 모드가 없기 때문에, 이 브리지는 각 테넌트 자식에 대해 stdio를 통한 MCP 클라이언트 세션을 유지하고 Streamable HTTP를 통해 다시 제공합니다:

1. :8080에서 POST /mcp 및 GET /health로 수신합니다.

2. 모든 /mcp 요청을 X-Nutanix-Pc-* 자격 증명 헤더(아래 참조)로 401 게이트합니다. 누락되거나 유효하지 않은 자격 증명은 환경 자격 증명으로 넘어가지 않습니다 — 이는 교차 테넌트 누출이 될 것입니다.

3. 자격 증명 튜플(해시로 키 지정)당 하나의 nutanix-mcp serve-stdio 자식을 느리게 생성하고, 테넌트의 PC_* 환경 변수를 설정한 후 stdio를 통해 MCP 클라이언트를 연결합니다.

4. v2 SDK의 createMcpHandler(factory, { legacy: 'stateless' })를 통해 /mcp에서 두 프로토콜 시대를 모두 제공합니다 — 2025년 시대의 initialize 핸드셰이크 클라이언트(현재의 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은 의도적인 플릿 결정으로 읽기 전용으로 제공됩니다. 쓰기 지원은 src/credentials.ts의 credentialsToChildEnv()에 대한 검토되고 버전 관리된 변경 사항이 될 것입니다 — 구성 전환이 아닙니다.

자격 증명 계약

게이트웨이는 모든 /mcp 요청에 대해 이러한 헤더를 전달합니다; 브리지는 이를 업스트림 자식의 환경에 매핑합니다. conduit의 벤더 구성은 이 표와 정확히 일치해야 합니다.

유효성 규칙: pcHost가 존재하고 (apiKey가 존재하거나 username+password가 존재). 그 외의 경우 → HTTP 401과 JSON-RPC 오류 본문.

READ_ONLY_MODE=true가 모든 자식에 추가로 강제됩니다 (위 참조).

API 사양 아티팩트 (빌드 시 포함)

업스트림은 라이브 PC가 아닌 YAML API 사양 아티팩트에서 도구 표면을 구축합니다. nutanix-mcp init이 이를 다운로드합니다 — PC 자격 증명 없이 공개 developers.nutanix.com 네임스페이스 API에 대해 latest_release 모드로 실행됩니다 (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

업스트림 고정 업데이트

업스트림은 Dockerfile의 검토된 태그 v0.8 (NUTANIX_MCP_REF)로 고정되어 있습니다 — 절대 main이 아닙니다 (NSA MCP 지침 / 플릿 보안 기준). 업데이트하려면:

1. 현재 고정과 새 태그 간의 업스트림 차이를 검토합니다 (도구 표면, 자격 증명 처리, READ_ONLY_MODE 의미론).

2. Dockerfile의 NUTANIX_MCP_REF와 이 README의 태그를 변경합니다.

3. 로컬에서 docker build를 실행합니다 — 빌드 타임 스모크 테스트는 venv 진입점이 실행되고 stdio 도구 표면이 여전히 응답하는지 확인합니다 (네임스페이스가 변경된 경우 예상 도구 수를 업데이트).

4. feat:/fix: PR로 병합하여 semantic-release가 버전을 생성하도록 합니다.

라이선스

Apache-2.0. 번들된 ntnx-api-mcp-server는 Nutanix의 Apache-2.0입니다.