在 IDE 中将 Hyperflux 用作 MCP Server

Alauda Hyperflux 可以将自身暴露为一个 MCP（Model Context Protocol）server，因此 AI 编码 assistant——Claude Code、Cursor、VS Code Copilot，或任何兼容 MCP 的智能体——都可以向它提问 Alauda 产品问题，并直接从 IDE 中检查（或者在获得批准后操作）ACP 集群。

该 MCP server 暴露一个单一工具 hyperflux_agent，它会委托给完整的 Hyperflux 智能体：知识库检索加上集群工具（clusters、projects、namespaces、nodes、pods、 resources、events、pod logs、metrics、alerts）。它会返回带引用的有据可查的答案。

启用 MCP server

在 Administrator / Marketplace / Cluster Plugins 中，安装或更新 Alauda Hyperflux 插件：

Expose as MCP Server：开启（默认关闭）。
MCP Write-Approval Timeout (s)：在 IDE 中等待你批准变更操作的时长，超过后将视为拒绝。默认值为 300。请将其设置为低于 ingress 的空闲超时，否则在等待批准时连接可能会被中断。

端点

MCP 端点使用 streamable HTTP 传输，地址为：

https://<platform-address>/smart-doc/mcp/

NOTE: 末尾斜杠很重要。对 /smart-doc/mcp（不带斜杠）的请求会返回 HTTP 307 重定向，而某些 MCP client 不会跟随该重定向。

认证

未认证请求会被 HTTP 403 拒绝。

请将你的 ACP identity token 作为 bearer header 发送：Authorization: Bearer <token>。你可以从已登录的 ACP Web Console 会话中获取该 token：打开浏览器开发者 tools，并复制 cpaas_id_token cookie 的值（去掉两侧引号以及前导的 Bearer 前缀）。

这会将你标识为真实用户：在支持 elicitation 的 MCP client 中，变更操作会在交互式批准后可用（见下文）。该 token 会随你的 ACP session 过期，因此当你开始收到 403 响应时，请重新获取。

配置你的 IDE

Claude Code：

claude mcp add --transport http hyperflux \
  "https://<platform-address>/smart-doc/mcp/" \
  --header "Authorization: Bearer <your-acp-token>"

通用 mcp.json（Cursor、VS Code 以及大多数其他 MCP client）：

{
  "mcpServers": {
    "hyperflux": {
      "type": "http",
      "url": "https://<platform-address>/smart-doc/mcp/",
      "headers": {
        "Authorization": "Bearer <your-acp-token>"
      }
    }
  }
}

然后可以像这样向你的 assistant 提问：“Using the hyperflux tool, check why pods in namespace foo are not ready”。该工具接受一个 question，以及可选的 session_id（用于继续之前的会话）、cluster、namespace 和 project 提示。

只读与写入操作

智能体通过 IDE 能执行哪些操作，取决于插件的 Tool Approval Strategy 和你的 MCP client：

使用默认策略 disabled 时，MCP tool 对所有人都是只读的——写入工具会从智能体中完全移除。
使用其他策略时，变更操作（创建 / 更新 / 删除 / 扩缩资源）仅在你的 MCP client 支持 elicitation 时可用。在执行写入之前，Hyperflux 会发送一个批准请求，IDE 会将其显示为确认提示；在配置的超时时间内未响应会被视为拒绝，而被拒绝的操作在同一 session 中不会再次发起。
不支持 elicitation 的 client 将获得只读行为：写入尝试会被拒绝并返回 "read-only MCP session" 消息，而读取操作仍可正常工作。

故障排查

使用 curl 端到端验证端点：

curl -sk -X POST "https://<platform-address>/smart-doc/mcp/" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "Authorization: Bearer <your-acp-token>" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}'

健康的 server 会返回 "serverInfo":{"name":"hyperflux",...}。

症状	原因
HTTP 403	认证失败：ACP token 缺失或已过期。
HTTP 404	Expose as MCP Server 已关闭，或者在 pods 重启前修改了该设置。
HTTP 307	缺少末尾斜杠——请使用 `/smart-doc/mcp/`。
Writes always declined	你的 client 不支持 elicitation，或者批准策略为 `disabled`。
Approval prompt disappears / connection drops during approval	ingress 的空闲超时时间短于 MCP Write-Approval Timeout——请降低该超时值或提高 ingress 限制。

服务端日志（kubectl -n cpaas-system logs -l app=smart-doc -c serve）会在功能启用时，在启动期间显示 Outbound MCP server mounted at /mcp，并在由于只读 session 导致写入被拒绝时显示 MCP read-only session — blocked write tool <name>。

#在 IDE 中将 Hyperflux 用作 MCP Server

#目录

#启用 MCP server

#端点

#认证

#配置你的 IDE

#只读与写入操作

#故障排查

在 IDE 中将 Hyperflux 用作 MCP Server

目录

启用 MCP server

端点

认证

配置你的 IDE

只读与写入操作

故障排查