容器服务 Kubernetes 版 ACK：使用ack-agent-gateway构建MCP服务网关

适用范围

• ACK托管集群版本在1.32及以上。

• 已在集群中安装Gateway API组件，且版本在1.3.0及以上。

安装ack-agent-gateway

ack-agent-gateway 是一个实现了 Gateway API 标准的网关组件。它利用Gateway API 这套标准化的流量管理模型，可便捷地配置和管理MCP服务流量。

1. 在ACK集群列表页面，单击目标集群名称，在集群详情页左侧导航栏，选择应用 > Helm。

2. 在Helm页面，单击创建，在Chart区域搜索并选中ack-agent-gateway，其他设置保持默认，然后单击下一步。

   组件默认安装在ack-agent-gateway命名空间，并以组件名称发布应用。

3. 在参数页面中，选择最新的Chart版本，然后单击确定。

4. 安装完成后，可在Helm页面查看组件，状态为已部署。

步骤一：部署示例 MCP 服务

本步骤将部署一个官方提供的示例 MCP 服务，用于后续的网关功能验证。

1. 使用以下内容，创建名为 mcp-server.yaml 的文件。此 YAML 文件定义了一个 Deployment 和一个 Service，用于在 default 命名空间中部署示例服务。

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: demo-mcp
   spec:
     replicas: 1
     selector:
       matchLabels:
         app.kubernetes.io/name: demo-mcp
     template:
       metadata:
         labels:
           app.kubernetes.io/name: demo-mcp
       spec:
         containers:
           - image: registry-cn-hangzhou.ack.aliyuncs.com/dev/sample-mcp-server-fetch:v0.2.0
             imagePullPolicy: IfNotPresent
             name: mcp
             ports:
               - containerPort: 8000
                 name: server
                 protocol: TCP
   ---
   apiVersion: v1
   kind: Service
   metadata:
     name: demo-mcp-server
   spec:
     ports:
       - name: server
         port: 8000
         protocol: TCP
         targetPort: 8000
     selector:
       app.kubernetes.io/name: demo-mcp
     sessionAffinity: None
     type: ClusterIP

2. 部署示例 MCP 服务。

   kubectl apply -f mcp-server.yaml

3. 检查 Pod 状态。

   kubectl get pod -l app.kubernetes.io/name=demo-mcp

   预期输出：请确保 Pod 处于 Running 状态。

   NAME                        READY   STATUS    RESTARTS   AGE
   demo-mcp-58fddf4cd9-8jvzn   1/1     Running   0          3s

步骤二：创建 Gateway 和路由规则

本步骤将使用 Gateway、HTTPRoute 以及 ack-agent-gateway 的自定义资源 Backend，为上一步部署的 MCP 服务创建一个网关入口。

• Backend（CRD）：由于标准的 Gateway API 后端引用（backendRef）机制无法精细化描述 MCP 协议的特定属性（如流式 HTTP），ack-agent-gateway 引入了自定义资源 Backend 来进行能力扩展，实现更精确地定义后端服务的协议类型和访问路径。

• Gateway：定义了一个流量入口，指定了监听的端口和协议，并关联 ack-agent-gateway 作为其实现。

• HTTPRoute：定义了流量路由规则，将发往 Gateway 的请求转发到我们自定义的 Backend 资源。

1. 使用以下内容，创建名为mcp-gateway.yaml的文件。

   # 定义 MCP 后端服务的详细信息
   apiVersion: agentgateway.alibabacloud.com/v1alpha1
   kind: Backend
   metadata:
     name: test-mcp
   spec:
     type: MCP # 定义后端类型为 MCP
     mcp:
       targets:
         - name: mcp-target # Target 的唯一标识
           static:
             # 后端服务的 K8s Service FQDN 地址
             host: demo-mcp-server.default.svc.cluster.local 
             # MCP 服务的协议路径
             path: /mcp 
             port: 8000
             # 定义 MCP 使用的传输协议，此处为流式 HTTP
             protocol: StreamableHTTP 
   ---
   # 定义网关实例，作为流量入口
   apiVersion: gateway.networking.k8s.io/v1
   kind: Gateway
   metadata:
     name: test-mcp-gateway
   spec:
     gatewayClassName: ack-agent-gateway # 指定 ack-agent-gateway 作为网关控制器
     listeners:
       - name: http
         port: 80
         protocol: HTTP
         allowedRoutes:
           namespaces:
             from: Same # 仅允许在相同命名空间下创建的路由规则关联此网关
   ---
   # 定义路由规则，将流量导向 MCP 后端
   apiVersion: gateway.networking.k8s.io/v1
   kind: HTTPRoute
   metadata:
     name: route-for-mcp-backend
   spec:
     parentRefs:
       - group: gateway.networking.k8s.io
         kind: Gateway
         name: test-mcp-gateway # 关联到上述创建的 Gateway
     rules:
       - backendRefs:
           # 注意：此处引用的 backend 是我们自定义的 Backend CRD
           - group: agentgateway.alibabacloud.com
             kind: Backend
             name: test-mcp

2. 部署网关和路由规则。

   kubectl apply -f mcp-gateway.yaml

3. 获取网关的公网 IP 地址。

   kubectl get gateway test-mcp-gateway

   请记录下 ADDRESS 字段显示的网关 IP 地址，后续测试将使用此地址。

   NAME               CLASS               ADDRESS        PROGRAMMED   AGE
   test-mcp-gateway   ack-agent-gateway   114.55.xx.xx   True         13m

步骤三：测试服务连通性

请确保本地已安装Node.js环境。本步骤将使用 MCP Inspector工具来模拟客户端，测试通过网关访问 MCP 服务。

1. 在本地命令行终端中，执行以下命令安装并启动 MCP Inspector。

   npx @modelcontextprotocol/inspector@v0.17.5

2. 命令执行后，终端会输出一个本地访问地址（通常为 http://localhost:xxxx）。在浏览器中打开此地址。

3. 在打开的 MCP Inspector 页面中，填充以下信息。

   • Transport Type：选择Streamable HTTP。

   • URL：填入http://<GATEWAY_IP>:80/mcp，<GATEWAY_IP>替换为上一步获取的网关地址（ADDRESS）。

4. 单击Connect按钮。如果连接成功，页面会显示已连接状态。

5. （可选）单击Tools > List Tools按钮，可以获取并查看 MCP 服务提供的工具列表，进一步验证服务可用性。

步骤四：增加 API Key 认证（可选）

本步骤将演示如何在不修改任何业务代码的前提下，通过 TrafficPolicy 资源为 MCP 服务增加 API Key 认证能力。

• TrafficPolicy （CRD）：这是 ack-agent-gateway 提供的一个自定义资源，用于为路由规则附加高级功能。这是一种策略附着（Policy Attachment）的实现，可以将认证、限流等策略与 HTTPRoute 解耦。

• Secret：用于安全地存储 API Key 凭证。

API Key 认证是一种简单的认证方式。凭证若被泄露，可能被滥用，请注意凭证的管理与保护。

1. 使用以下内容，创建名为mcp-api-key.yaml 的文件。 此 YAML 文件定义了一个包含两个 API Key 的 Secret，以及一个将 API Key 认证策略附加到 HTTPRoute 的 TrafficPolicy。

   apiVersion: v1
   kind: Secret
   metadata:
     name: mcp-api-key
   stringData:
     # key（如 key1）仅作标识；value（如 key-value-foo）是客户端需提供的实际凭证
     key1: 'key-value-foo'
     key2: 'key-value-bar'
   ---
   apiVersion: agentgateway.alibabacloud.com/v1alpha1
   kind: TrafficPolicy
   metadata:
     name: test-mcp-apikey-auth
   spec:
     targetRefs: # 策略附加的目标
       - group: gateway.networking.k8s.io
         kind: HTTPRoute
         name: route-for-mcp-backend # 附加到之前创建的 HTTPRoute
     traffic:
       authentication:
         apiKeyAuth:
           secretRef:
             name: mcp-api-key # 引用存储凭证的 Secret

2. 应用 API Key 认证策略。

   kubectl apply -f mcp-api-key.yaml

3. 返回 MCP Inspector 页面，验证认证效果。

   1. 刷新页面，然后再次单击Connect按钮。

   2. 此时连接会失败，页面提示Connection Error。同时，运行 MCP Inspector 的命令行终端会输出类似 api key authentication failure 的错误日志。这表明网关的认证策略已生效。

   3. 单击页面Authentication按钮，填入 Secret 中定义的任意一个凭证（例如key-value-foo）。 然后单击Connect按钮，成功连接表明 API Key 认证通过。

      

清理资源

为避免产生不必要的费用，请在完成实验后删除本教程创建的所有 Kubernetes 资源和云资源。

1. 删除本教程中创建的所有 Kubernetes 资源。

   # 如果执行了可选的步骤四，请先删除认证相关的资源
   kubectl delete -f mcp-api-key.yaml
   
   # 删除网关和路由规则
   kubectl delete -f mcp-gateway.yaml
   
   # 删除后端的示例服务
   kubectl delete -f mcp-server.yaml

2. 确认 CLB 实例已释放。 删除 Gateway 资源后，会自动删除其关联的 CLB 实例。可登录到负载均衡控制台，确认对应的实例已被删除。