nutanix-mcp

多租户流式HTTP桥接，基于 nutanix/ntnx-api-mcp-server——Nutanix 官方的 Prism Central v4 API MCP 服务器——构建，使得 WYRE 通道网关能够将每个租户的 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 握手客户端（今天的通道网关）和现代 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 请求中转发这些头；桥接器将它们映射到上游子进程的环境变量中。通道的供应商配置必须与此表完全匹配。

有效性规则： 必须提供 pcHost 并且（提供 apiKey 或提供 username+password）。否则 → HTTP 401 并附带 JSON-RPC 错误体。

READ_ONLY_MODE=true 额外强制应用于每个子进程（见上文）。

API 规范工件（构建时烘焙）

上游从 YAML API 规范工件中构建其工具表面，而非从实时 PC 中。nutanix-mcp init 下载它们——并且无需 PC 凭证，它就会以 latest_release 模式针对公共的 developers.nutanix.com 命名空间 API 运行（无需 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 提交，以便语义发布切出版本。

许可证

Apache-2.0。捆绑的 ntnx-api-mcp-server 由 Nutanix 提供，采用 Apache-2.0 许可。