Alauda Hyperflux
  • 简体中文

    • 配置外部 MCP 服务器

    Alauda Hyperflux 内置了一个 MCP server，提供具备集群感知能力的工具。
    你可以通过自己的（外部）MCP server 扩展 Agent 的工具集——例如内部 wiki 搜索、CMDB 查询服务，或任何其他兼容 MCP 的端点。

    外部 MCP server 在 ConfigMap 中声明，并通过安装表单进行注册。
    启动时，Alauda Hyperflux 会连接到每个 server，列出其工具，并将这些工具与内置工具一起提供给 Agent。

    目录

    在 ConfigMap 中声明 MCP server注册 ConfigMap工具命名和审批验证

    在 ConfigMap 中声明 MCP server

    在 安装了 Alauda Hyperflux 的命名空间 中创建一个 ConfigMap（cpaas-system）。
    每个带有 .yaml、.yml 或 .json 扩展名的数据键都会被解析；每个文件的内容必须是一个 server 条目列表：

    apiVersion: v1
kind: ConfigMap
metadata:
  name: my-org-mcp-servers
  namespace: cpaas-system
data:
  servers.yaml: |
    - name: corp-wiki
      url: https://wiki-mcp.example.com/mcp
      transport: streamable_http
      headers:
        Authorization: "Bearer <your-token>"
    - name: cmdb
      url: https://cmdb-mcp.example.com/sse
      transport: sse
      tls_verify: false

    每个 server 条目的字段：

    字段必填描述
    name是与 ^[a-z][a-z0-9_-]*$ 匹配的唯一 server 名称。名称 acp_mcp_server 为保留名称。
    url是MCP 端点 URL。
    transport否streamable_http（默认）或 sse。
    headers否每次请求都会发送的静态 HTTP header，例如用于 token 认证。如果变量存在，会从容器环境中替换 ${VAR} 占位符。
    tls_verify否是否验证 server 的 TLS 证书。默认值为 true。对于使用内部 CA 的端点，建议保持此项为 true，并通过 Extra CA ConfigMaps 添加 CA（参见 Configure TLS）。

    无效条目（名称不合法、缺少 url、未知 transport、名称重复）会被跳过，并记录 ERROR 日志；它们不会阻止其他 server 或服务本身启动。

    注意： ConfigMap 值以明文形式存储。避免直接在 headers 中放置长期有效的密钥；对于你放在其中的任何 token，请像处理任何共享凭证一样进行轮换。

    注册 ConfigMap

    在 管理员 / Marketplace / 集群插件 中，安装或更新 Alauda Hyperflux 插件，并在 Extra MCP Servers ConfigMaps 下添加 ConfigMap 名称。

    每个列出的 ConfigMap 都会以只读方式挂载到 /opt/extra-mcp/<configmap-name>/，并在启动时仅扫描一次：

    • 在表单中添加或移除 ConfigMap 名称会自动触发滚动重启。

    • 编辑已注册 ConfigMap 的内容不会触发重启——请手动重启：

      kubectl -n cpaas-system rollout restart deploy/smart-doc

    工具命名和审批

    来自外部 server 的工具会以前缀形式向 Agent 暴露 server 名称，例如 corp-wiki__search_pages，因此它们不会与内置工具名称发生冲突。

    外部工具与内置工具一样，受相同的 Tool Approval Strategy 约束：

    • 在默认策略 disabled 下，任何未由其 MCP server 标注 readOnlyHint: true 的工具，都会被完全从 Agent 的工具集中过滤掉。许多 MCP server 不会为工具添加标注——在这种情况下，只有当你将策略切换为 tool_annotations（此时写入工具需要交互式审批）或让 MCP server 为其只读工具添加标注后，这些工具才会可见。
    • 使用 tool_annotations 时，只读工具可直接运行；其他所有工具在每次调用前都会提示用户审批。

    验证

    检查启动日志：

    kubectl -n cpaas-system logs -l app=smart-doc -c serve | grep -i "extra mcp\|MCP tools"

    预期输出：

    Loading extra MCP servers from file /opt/extra-mcp/my-org-mcp-servers/servers.yaml
Loading extra MCP server name=corp-wiki url=https://wiki-mcp.example.com/mcp transport=streamable_http headers={'Authorization': '<redacted>'}
Extra MCP corp-wiki loaded 3 tools: ['corp-wiki__search_pages', ...]
Loaded 15 MCP tools (acp=12, extra=3)

    常见失败模式：

    日志消息原因
    Extra MCP <name> timed out after 10.0s; skipped端点不可达或响应缓慢；每个 server 的连接预算为 10 秒，超时后会被跳过，不影响其他 server。
    Extra MCP <name> failed to load: ...; skipped连接或协议错误——检查 URL、transport 和 TLS 信任。
    <file> is not valid YAML / must be a listConfigMap 文件内容格式错误。
    extra MCP header placeholder ${VAR} not in environment; leaving as-isheaders 中引用了一个环境变量 ${VAR}，但该变量在容器中不存在。
    AGENT_APPROVAL_STRATEGY=disabled — filtered out N write/unannotated tools在默认审批策略下，没有 readOnlyHint: true 的工具已被移除（见上文）。

    敏感的 header 值（Authorization、X-API-Key、cookies，以及任何长度超过 16 个字符的值）始终会在日志中被脱敏。