Container Service for Kubernetes：使用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 執行個體。可登入到負載平衡控制台，確認對應的執行個體已被刪除。