Bagaimana cara membangun gerbang layanan MCP di ACK? - Container Service for Kubernetes

Untuk mengekspos layanan Model Context Protocol (MCP) dalam kluster ACK agar dapat dipanggil oleh Large Language Model (LLM) eksternal, Anda dapat menginstal ekstensi ack-agent-gateway. Ekstensi ini berbasis Gateway API dan memungkinkan pengarahan trafik MCP secara cepat dan aman.

Skenario

Kluster ACK yang dikelola yang menjalankan versi 1.32 atau lebih baru.
Komponen Gateway API versi 1.3.0 atau lebih baru telah diinstal di kluster.

Instal ack-agent-gateway

ack-agent-gateway adalah komponen gerbang yang mengimplementasikan standar Gateway API. Komponen ini menggunakan model manajemen trafik terstandarisasi dari Gateway API untuk membantu Anda mengonfigurasi dan mengelola trafik layanan MCP dengan mudah.

Pada halaman ACK Clusters, klik nama kluster target. Di panel navigasi kiri, pilih Applications > Helm.
Pada halaman Helm, klik Create. Di bagian Chart, cari dan pilih ack-agent-gateway. Pertahankan pengaturan default, lalu klik Next.
Secara default, komponen diinstal di namespace ack-agent-gateway. Aplikasi dipublikasikan menggunakan nama komponen tersebut.
Pada halaman Parameters, pilih versi Chart terbaru, lalu klik OK.
Setelah instalasi selesai, Anda dapat melihat komponen tersebut pada halaman Helm dengan status Deployed.

Langkah 1: Deploy layanan MCP contoh

Pada langkah ini, Anda mendeploy layanan MCP contoh resmi yang dapat digunakan nanti untuk memverifikasi fitur gerbang.

Buat file bernama mcp-server.yaml dengan konten berikut. File YAML ini mendefinisikan Deployment dan Service untuk mendeploy layanan contoh di namespace 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

Deploy layanan MCP contoh.
```
kubectl apply -f mcp-server.yaml
```

Periksa status pod.

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

Output yang diharapkan: Pastikan pod berada dalam status Running.

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

Langkah 2: Buat Gateway dan aturan routing

Pada langkah ini, Anda membuat entri gerbang untuk layanan MCP yang telah dideploy menggunakan Gateway, HTTPRoute, dan CustomResourceDefinition (CRD) ack-agent-gateway Backend.

Backend (CRD): Referensi backend standar Gateway API (backendRef) tidak dapat menggambarkan properti protokol MCP tertentu, seperti streaming HTTP, secara detail halus. Untuk mengatasi hal ini, ack-agent-gateway memperkenalkan CRD Backend yang memperluas kemampuan Gateway API sehingga Anda dapat mendefinisikan tipe protokol dan jalur akses layanan backend secara lebih tepat.
Gateway: Mendefinisikan titik masuk trafik dengan menentukan port dan protokol pendengar serta mengaitkan ack-agent-gateway sebagai implementasinya.
HTTPRoute: Mendefinisikan aturan routing trafik yang meneruskan permintaan dari Gateway ke resource Backend kustom Anda.

Buat file bernama mcp-gateway.yaml dengan konten berikut.

# Mendefinisikan detail layanan backend MCP
apiVersion: agentgateway.alibabacloud.com/v1alpha1
kind: Backend
metadata:
  name: test-mcp
spec:
  type: MCP # Mendefinisikan tipe backend sebagai MCP
  mcp:
    targets:
      - name: mcp-target # Pengidentifikasi unik untuk Target
        static:
          # FQDN dari layanan Kubernetes backend
          host: demo-mcp-server.default.svc.cluster.local 
          # Jalur protokol layanan MCP
          path: /mcp 
          port: 8000
          # Mendefinisikan protokol transport yang digunakan oleh MCP, yaitu Streamable HTTP di sini
          protocol: StreamableHTTP 
---
# Mendefinisikan instans gateway sebagai titik masuk trafik
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: test-mcp-gateway
spec:
  gatewayClassName: ack-agent-gateway # Menentukan ack-agent-gateway sebagai pengontrol gateway
  listeners:
    - name: http
      port: 80
      protocol: HTTP
      allowedRoutes:
        namespaces:
          from: Same # Hanya mengizinkan aturan routing yang dibuat di namespace yang sama untuk dikaitkan dengan gateway ini
---
# Mendefinisikan aturan routing untuk mengarahkan trafik ke backend 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 # Mengaitkan dengan Gateway yang dibuat di atas
  rules:
    - backendRefs:
        # Catatan: Backend yang direferensikan di sini adalah CRD Backend kustom kita
        - group: agentgateway.alibabacloud.com
          kind: Backend
          name: test-mcp

Deploy gateway dan aturan routing.
```
kubectl apply -f mcp-gateway.yaml
```

Dapatkan alamat IP publik gateway.

kubectl get gateway test-mcp-gateway

Catat alamat IP gateway dari kolom ADDRESS. Anda akan menggunakan alamat ini untuk pengujian.

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

Langkah 3: Uji konektivitas layanan

Pastikan lingkungan Node.js telah diinstal di mesin lokal Anda. Pada langkah ini, Anda menggunakan tool MCP Inspector untuk mensimulasikan klien dan menguji akses ke layanan MCP melalui gateway.

Di terminal command-line lokal Anda, jalankan perintah berikut untuk menginstal dan menjalankan MCP Inspector.
```
npx @modelcontextprotocol/inspector@v0.17.5
```
Setelah perintah dijalankan, terminal menampilkan titik akhir lokal, biasanya dalam format http://localhost:xxxx. Buka titik akhir tersebut di browser.
Pada halaman MCP Inspector yang terbuka, isi informasi berikut.
- Transport Type: Pilih Streamable HTTP.
- URL: Masukkan http://<GATEWAY_IP>:80/mcp. Ganti <GATEWAY_IP> dengan alamat gateway (ADDRESS) yang Anda peroleh pada langkah sebelumnya.
Klik tombol Connect. Jika koneksi berhasil, halaman akan menampilkan status terhubung.
(Opsional) Klik Tools > List Tools untuk mengambil dan melihat daftar tool yang disediakan oleh layanan MCP. Langkah ini lebih lanjut memverifikasi ketersediaan layanan.

Langkah 4: Tambahkan autentikasi kunci API (Opsional)

Langkah ini menunjukkan cara menambahkan autentikasi kunci API ke layanan MCP menggunakan resource TrafficPolicy tanpa mengubah kode aplikasi apa pun.

TrafficPolicy (CRD): CRD yang disediakan oleh ack-agent-gateway untuk menambahkan fitur lanjutan ke aturan routing. Ini merupakan implementasi Policy Attachment yang memisahkan kebijakan—seperti autentikasi dan pembatasan laju—dari HTTPRoute.
Secret: Digunakan untuk menyimpan kredensial kunci API secara aman.

Autentikasi kunci API adalah metode autentikasi yang sederhana. Jika kredensial bocor, kredensial tersebut dapat disalahgunakan. Anda harus mengelola dan melindungi kredensial Anda dengan hati-hati.

Buat file bernama mcp-api-key.yaml dengan konten berikut. File YAML ini mendefinisikan Secret yang berisi dua kunci API dan TrafficPolicy yang mengaitkan kebijakan autentikasi kunci API ke HTTPRoute.

apiVersion: v1
kind: Secret
metadata:
  name: mcp-api-key
stringData:
  # Kunci (misalnya key1) hanya berupa pengidentifikasi. Nilai (misalnya key-value-foo) adalah kredensial aktual yang harus disediakan oleh klien.
  key1: 'key-value-foo'
  key2: 'key-value-bar'
---
apiVersion: agentgateway.alibabacloud.com/v1alpha1
kind: TrafficPolicy
metadata:
  name: test-mcp-apikey-auth
spec:
  targetRefs: # Target untuk pelampiran kebijakan
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: route-for-mcp-backend # Mengaitkan ke HTTPRoute yang dibuat sebelumnya
  traffic:
    authentication:
      apiKeyAuth:
        secretRef:
          name: mcp-api-key # Merujuk ke Secret yang menyimpan kredensial

Terapkan kebijakan autentikasi kunci API.
```
kubectl apply -f mcp-api-key.yaml
```
Kembali ke halaman MCP Inspector untuk memverifikasi autentikasi.
1. Muat ulang halaman, lalu klik tombol Connect lagi.
2. Koneksi gagal, dan halaman menampilkan Connection Error. Terminal command-line yang menjalankan MCP Inspector mengeluarkan log error serupa dengan api key authentication failure, menunjukkan bahwa kebijakan autentikasi gateway sedang berlaku.
3. Klik tombol Authentication pada halaman. Masukkan salah satu kredensial yang didefinisikan dalam Secret, misalnya key-value-foo, lalu klik tombol Connect. Koneksi yang berhasil menunjukkan bahwa autentikasi kunci API berhasil.

Bersihkan resource

Untuk menghindari biaya yang tidak perlu, hapus semua resource Kubernetes dan resource cloud yang Anda buat dalam tutorial ini setelah menyelesaikan eksperimen.

Hapus semua resource Kubernetes yang Anda buat dalam tutorial ini.

# Jika Anda melakukan Langkah 4 opsional, hapus terlebih dahulu resource terkait autentikasi
kubectl delete -f mcp-api-key.yaml

# Hapus gateway dan aturan routing
kubectl delete -f mcp-gateway.yaml

# Hapus layanan contoh backend
kubectl delete -f mcp-server.yaml

Konfirmasi bahwa instans Server Load Balancer (SLB) telah dilepas. Saat Anda menghapus resource Gateway, instans SLB terkaitnya akan dihapus secara otomatis. Masuk ke Konsol Server Load Balancer untuk memastikan instans tersebut telah dihapus.