Membawa server MCP Anda sendiri ke implementasi referensi kagent

Pengantar

Server Model Context Protocol (MCP) bawa sendiri (BYO) memungkinkan agen AI mengkueri dan memproses data dari repositori eksternal secara real time menggunakan koneksi standar di seluruh infrastruktur yang ada.

Dokumen implementasi referensi solusi (SRI) ini menunjukkan cara men-deploy aplikasi open source Nextcloud dan server MCP-nya bersama agen Nextcloud di Solo Enterprise for kagent. Arsitektur ini menghubungkan Nextcloud, kagent, dan model Gemma 4 dalam cluster Google Kubernetes Engine (GKE) yang di-deploy di Distributed Cloud software only (GDC). Dalam konfigurasi ini, kagent menggunakan Nextcloud sebagai repositori data, sehingga model Gemma 4 dapat mengakses dan memproses file di Nextcloud melalui antarmuka MCP standar. Untuk konteks arsitektur, lihat arsitektur referensi pendamping.

Ringkasan Nextcloud

Nextcloud adalah platform kolaborasi dan penyimpanan cloud open source yang dihosting sendiri yang mendukung deployment lokal. Men-deploy Nextcloud di infrastruktur lokal membantu menjaga kedaulatan, keamanan, dan privasi data Anda.

Nextcloud menyediakan fitur berikut:

  • Sinkronisasi dan berbagi file: Simpan file, sinkronkan di seluruh perangkat desktop dan seluler Anda melalui aplikasi khusus, dan bagikan kepada orang lain menggunakan link.
  • Alat produktivitas: Kelola jadwal dan komunikasi dengan kalender, kontak, pengelolaan tugas, dan program email bawaan.
  • Kolaborasi: Integrasikan suite office (seperti Collabora Online atau ONLYOFFICE) langsung ke Nextcloud untuk mengedit dokumen, spreadsheet, dan presentasi bersama secara real time.
  • Ekstensibilitas: Instal plugin dari app store untuk menambahkan fitur seperti pengelola sandi, papan Kanban, atau pemutar musik.

Arsitektur solusi

Solusi ini memerlukan lingkungan GDC dengan Solo Enterprise untuk kagent dan vLLM dengan model Gemma 4 yang di-deploy, serta workstation dengan kubectl dan helm yang diinstal.

Diagram berikut mengilustrasikan arsitektur solusi yang menghubungkan GDC, kagent, Nextcloud, dan vLLM dengan Gemma 4:

Arsitektur solusi: GDC, kagent, Nextcloud, dan vLLM dengan Gemma 4.

Pendekatan deployment

Untuk men-deploy Nextcloud dan mengintegrasikan server MCP-nya dengan kagent, selesaikan langkah-langkah tingkat tinggi berikut:

  1. Buat namespace khusus untuk Nextcloud: Isolasi deployment dengan membuat namespace nextcloud menggunakan kubectl.
  2. Tambahkan dan perbarui repositori Helm: Konfigurasikan workstation Anda dengan repositori Helm Nextcloud resmi dan perbarui metadata diagram lokal Anda.
  3. Konfigurasikan nilai deployment kustom: Buat file values.yaml kustom untuk mengonfigurasi Nextcloud bagi lingkungan target Anda. Konfigurasi ini menonaktifkan database SQLite lokal default, mengonfigurasi penyimpanan persisten MariaDB, menentukan kredensial administrator, dan menetapkan perutean internal menggunakan layanan ClusterIP.
  4. Jalankan penginstalan Helm: Deploy chart ke namespace target menggunakan file konfigurasi kustom Anda. Pastikan semua komponen, termasuk aplikasi Nextcloud dan Pod penyimpanan MariaDB, mencapai status Running.
  5. Men-deploy server MCP Nextcloud: Buat manifes deployment (nextcloud-mcp.yaml) yang berisi Secret buram untuk kredensial, Deployment yang menggunakan image nextcloud-mcp-server:latest, dan Service ClusterIP yang mengekspos port 8000. Terapkan manifes ini untuk mengizinkan komunikasi DNS Kubernetes internal dengan aplikasi Nextcloud.
  6. Daftarkan server alat di kagent: Hubungkan server di UI kagent menggunakan URL layanan internal http://nextcloud-mcp-service.nextcloud.svc.cluster.local:8000/mcp dan protokol STREAMABLE_HTTP.

Men-deploy Nextcloud dan server MCP

  1. Buat namespace untuk Nextcloud:

    kubectl create namespace nextcloud

    Outputnya mirip dengan hal berikut ini:

    namespace/nextcloud created

  2. Tambahkan repositori Nextcloud Helm ke workstation Anda dan perbarui metadata diagram lokal Anda:

    helm repo add nextcloud https://nextcloud.github.io/helm/
helm repo update

    Outputnya mirip dengan hal berikut ini:

    "nextcloud" has been added to your repositories
Hang tight while we grab the latest from your chart repositories...
...Successfully got an update from the "nextcloud" chart repository
Update Complete. ⎈Happy Helming!⎈

  3. Buat file values.yaml kustom di workstation Anda untuk mengganti parameter konfigurasi default chart Helm Nextcloud:

    # 0. Nextcloud administrator configuration
nextcloud:
  # Use the internal CoreDNS record
  host: "nextcloud.nextcloud.svc.cluster.local"  # Application access through CoreDNS rather than external DNS
  username: "admin"  # Application Login Credentials
  password: "SuperSecretPassword123"

# You can use a standard ClusterIP service since
# you are relying on internal routing, not an External LB.
service:
  type: ClusterIP

# 1. Configure RWO Storage for Nextcloud
persistence:
  enabled: true
  storageClass: "local-shared"
  accessMode: ReadWriteOnce
  size: 50Gi # Adjust based on your file storage needs

# 2. Explicitly disable the default local SQLite database
internalDatabase:
  enabled: false

# 3. Configure RWO Storage for the Database
mariadb:
  enabled: true
  auth:
    database: "nextcloud"
    username: "nextcloud"
    password: "NextcloudDBPassword123"
    rootPassword: "RootDBPassword123"
  primary:
    persistence:
      enabled: true
      storageClass: "local-shared"
      accessModes:
        - ReadWriteOnce
      size: 10Gi

# 4. Force Nextcloud to connect through the TCP Network
externalDatabase:
  enabled: true
  type: mysql
  host: "nextcloud-mariadb" # The internal Kubernetes service name for the DB
  database: "nextcloud"
  user: "nextcloud"
  password: "NextcloudDBPassword123" # MUST match mariadb.auth.password above

# Optional: Enable Ingress to route external traffic to Nextcloud
ingress:
  enabled: false # Set to true if you are using an Ingress Controller (like NGINX)
  className: "nginx"
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: 4G # Required to allow large file uploads

  4. Deploy Nextcloud menggunakan Helm:

    helm install nextcloud nextcloud/nextcloud \
    --namespace nextcloud \
    --values values.yaml

    Outputnya mirip dengan hal berikut ini:

    NAME: nextcloud
LAST DEPLOYED: Thu Jul  9 17:14:03 2026
NAMESPACE: nextcloud
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
1. Get the nextcloud URL by running:

  export POD_NAME=$(kubectl get pods --namespace nextcloud -l "app.kubernetes.io/name=nextcloud" -o jsonpath="{.items[0].metadata.name}")
  echo http://127.0.0.1:8080/
  kubectl port-forward --namespace nextcloud $POD_NAME 8080:80

2. Get your nextcloud login credentials by running:

  echo User:     admin
  echo Password: $(kubectl get secret --namespace nextcloud nextcloud -o jsonpath="{.data.nextcloud-password}" | base64 --decode)

    Pastikan Pod Nextcloud berada dalam status Running dan Service ada di namespace nextcloud:

    kubectl get pod -n nextcloud
kubectl get svc -n nextcloud

    Outputnya mirip dengan hal berikut ini:

    NAME                                    READY   STATUS    RESTARTS   AGE
nextcloud-558cbccb4c-q6zqq              1/1     Running   0          25m
nextcloud-mariadb-0                     1/1     Running   0          25m

NAME                         TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)    AGE
nextcloud                    ClusterIP   10.255.224.187   <none>        8080/TCP   25m
nextcloud-mariadb            ClusterIP   10.255.226.235   <none>        3306/TCP   25m
nextcloud-mariadb-headless   ClusterIP   None             <none>        3306/TCP   25m

  5. Untuk men-deploy server MCP Nextcloud di namespace nextcloud, buat file bernama nextcloud-mcp.yaml di workstation Anda:

    # Secret Creation
apiVersion: v1
kind: Secret
metadata:
  name: nextcloud-mcp-secret
  namespace: nextcloud
type: Opaque
stringData:
  # Use your dedicated App Password here, NEVER your primary administrator password
  NEXTCLOUD_USERNAME: "admin"
  NEXTCLOUD_PASSWORD: "SuperSecretPassword123"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nextcloud-mcp-server
  namespace: nextcloud
  labels:
    app: nextcloud-mcp
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nextcloud-mcp
  template:
    metadata:
      labels:
        app: nextcloud-mcp
    spec:
      containers:
        - name: mcp-server
          # The official Docker image provided by the project
          image: ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
          imagePullPolicy: Always
          ports:
            - containerPort: 8000
              name: http-mcp
          env:
            - name: NEXTCLOUD_HOST
              # Since the MCP server is in the same namespace, it can securely
              # talk to Nextcloud through the internal Kubernetes DNS, completely bypassing the internet.
              value: "http://nextcloud.nextcloud.svc.cluster.local:8080"
            - name: NEXTCLOUD_USERNAME
              valueFrom:
                secretKeyRef:
                  name: nextcloud-mcp-secret
                  key: NEXTCLOUD_USERNAME
            - name: NEXTCLOUD_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: nextcloud-mcp-secret
                  key: NEXTCLOUD_PASSWORD
          resources:
            requests:
              cpu: "100m"
              memory: "128Mi"
            limits:
              cpu: "500m"
              memory: "512Mi"
---
apiVersion: v1
kind: Service
metadata:
  name: nextcloud-mcp-service
  namespace: nextcloud
spec:
  type: ClusterIP
  ports:
    - port: 8000
      targetPort: 8000
      protocol: TCP
      name: http-mcp
  selector:
    app: nextcloud-mcp

    Terapkan manifes nextcloud-mcp.yaml:

    kubectl apply -f nextcloud-mcp.yaml

    Outputnya mirip dengan hal berikut ini:

    secret/nextcloud-mcp-secret created
deployment.apps/nextcloud-mcp-server created
service/nextcloud-mcp-service created

    Pastikan Pod dan Service berjalan di namespace nextcloud:

    kubectl get svc -n nextcloud
kubectl get pod -n nextcloud

    Outputnya mirip dengan hal berikut ini:

    NAME                         TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)    AGE
nextcloud                    ClusterIP   10.255.224.187   <none>        8080/TCP   26m
nextcloud-mariadb            ClusterIP   10.255.226.235   <none>        3306/TCP   26m
nextcloud-mariadb-headless   ClusterIP   None             <none>        3306/TCP   26m
nextcloud-mcp-service        ClusterIP   10.255.226.105   <none>        8000/TCP   55s

NAME                                    READY   STATUS    RESTARTS   AGE
nextcloud-558cbccb4c-q6zqq              1/1     Running   0          29m
nextcloud-mariadb-0                     1/1     Running   0          29m
nextcloud-mcp-server-58484d5799-mfvct   1/1     Running   0          4m11s

  6. Untuk mengintegrasikan alat MCP Nextcloud berdasarkan URL, buka UI kagent dan daftarkan server alat dengan nilai berikut:

    • URL: http://nextcloud-mcp-service.nextcloud.svc.cluster.local:8000/mcp
    • Protokol: STREAMABLE_HTTP
    • Namespace: kagent
    • Cluster: nama cluster Anda (misalnya, mgmt-cluster)

    Pastikan resource RemoteMCPServer diterima di namespace kagent:

    kubectl get remotemcpserver -n kagent

    Outputnya mirip dengan hal berikut ini:

    NAME                 PROTOCOL          URL                                                                 ACCEPTED
kagent-grafana-mcp   STREAMABLE_HTTP   http://kagent-grafana-mcp.kagent:8000/mcp                           True
kagent-tool-server   STREAMABLE_HTTP   http://kagent-tools.kagent:8084/mcp                                 True
nextcloud            STREAMABLE_HTTP   http://nextcloud-mcp-service.nextcloud.svc.cluster.local:8000/mcp   True

  7. Untuk mengakses Nextcloud dari workstation Anda, teruskan port lokal 8080 ke layanan nextcloud (lewati langkah ini jika Anda mengonfigurasi URL eksternal):

    kubectl port-forward -n nextcloud svc/nextcloud 8080:8080 &

    Outputnya mirip dengan hal berikut ini:

    Forwarding from 127.0.0.1:8080 -> 80
Forwarding from [::1]:8080 -> 80

Memverifikasi deployment dan mengonfigurasi agen Nextcloud

Dari browser workstation, buka http://localhost:8080 untuk melihat dasbor Nextcloud:

Halaman dasbor aplikasi Nextcloud.

Tampilan Files menampilkan direktori dan file yang disimpan di Nextcloud:

Antarmuka Direktori dan File dalam aplikasi Nextcloud.

Di UI kagent, halaman Dashboard menampilkan cluster yang terhubung dan agen yang di-deploy:

Dasbor aplikasi kagent.

Halaman Tool Servers mencantumkan alat yang ditemukan melalui MCP untuk aplikasi Nextcloud:

Halaman kagent Tool Servers yang menampilkan alat yang ditemukan untuk aplikasi Nextcloud.

Halaman Tools menampilkan kumpulan alat Nextcloud yang tersedia untuk agen:

Koleksi kagent Tools tersedia di Nextcloud.

Untuk membuat agen nextcloud di UI kagent, masukkan nama agen, cluster, namespace, dan deskripsi di bagian Basic Information:

Pembuatan agen kagent untuk Nextcloud.

Di bagian Behavior & Model Settings, pilih model Gemma 4 dan masukkan petunjuk sistem untuk agen:

Konfigurasi agen kagent untuk penyelarasan keterampilan dan model.

Di bagian Tools and Agents, pilih alat MCP Nextcloud untuk agen, lalu klik Create Agent:

Konfigurasi agen kagent untuk pemilihan alat Nextcloud.

Halaman Agents menampilkan agen nextcloud dengan status Ready:

Agen ditambahkan ke aplikasi kagent.

Anda dapat meminta agen Nextcloud untuk mencantumkan direktori dan file di aplikasi Nextcloud:

Agen Nextcloud mencantumkan direktori dan file.

Anda juga dapat meminta agen Nextcloud untuk menerjemahkan dan mentransliterasi konten file dari bahasa Inggris ke bahasa Prancis:

Agen Nextcloud menerjemahkan konten file dari bahasa Inggris ke bahasa Prancis.