Eigenen MCP-Server in die kagent-Referenzimplementierung einbinden

Einführung

Mit BYO-MCP-Servern (Bring Your Own Model Context Protocol) können KI-Agenten Daten aus externen Repositories in Echtzeit abfragen und verarbeiten. Dazu werden standardisierte Verbindungen über Ihre vorhandene Infrastruktur verwendet.

In diesem Dokument zur Referenzimplementierung der Lösung (SRI) wird beschrieben, wie Sie die Open-Source-Anwendung Nextcloud und ihren MCP-Server zusammen mit einem Nextcloud-Agenten auf Solo Enterprise for kagent bereitstellen. Diese Architektur verbindet Nextcloud, kagent und das Gemma 4-Modell in einem GKE-Cluster (Google Kubernetes Engine), der in Google Distributed Cloud (GDC) – nur Software bereitgestellt wird. In dieser Konfiguration verwendet kagent Nextcloud als Daten-Repository, sodass das Gemma 4-Modell über standardisierte MCP-Schnittstellen auf Dateien in Nextcloud zugreifen und diese verarbeiten kann. Informationen zum Architekturkontext finden Sie in der zugehörigen Referenzarchitektur.

Übersicht über Nextcloud

Nextcloud ist eine selbst gehostete Open-Source-Plattform für Zusammenarbeit und Cloud-Speicher, die die lokale Bereitstellung unterstützt. Durch die Bereitstellung von Nextcloud lokal können Sie die Hoheit, Sicherheit und den Datenschutz Ihrer Daten wahren.

Nextcloud bietet die folgenden Funktionen:

  • Dateisynchronisierung und -freigabe: Sie können Dateien speichern, sie über spezielle Apps auf Ihren Desktop- und Mobilgeräten synchronisieren und sie über Links für andere freigeben.
  • Produktivitätstools: Mit integrierten Kalendern, Kontakten, Aufgabenverwaltung und E‑Mail-Clients können Sie Zeitpläne und Kommunikation verwalten.
  • Zusammenarbeit: Office-Suites wie Collabora Online oder ONLYOFFICE lassen sich direkt in Nextcloud einbinden, um Dokumente, Tabellen und Präsentationen in Echtzeit gemeinsam zu bearbeiten.
  • Erweiterbarkeit: Installieren Sie Plug-ins aus dem App Store, um Funktionen wie Passwortmanager, Kanban-Boards oder Musikplayer hinzuzufügen.

Lösungsarchitektur

Für diese Lösung ist eine GDC-Umgebung mit Solo Enterprise für kagent und vLLM mit dem Gemma 4-Modell erforderlich sowie eine Workstation, auf der kubectl und helm installiert sind.

Das folgende Diagramm zeigt die Lösungsarchitektur, die GDC, kagent, Nextcloud und vLLM mit Gemma 4 verbindet:

Lösungsarchitektur: GDC, kagent, Nextcloud und vLLM mit Gemma 4.

Bereitstellungsansatz

Führen Sie die folgenden allgemeinen Schritte aus, um Nextcloud bereitzustellen und den MCP-Server in kagent einzubinden:

  1. Dedizierten Namespace für Nextcloud erstellen: Isolieren Sie die Bereitstellung, indem Sie den Namespace nextcloud mit kubectl erstellen.
  2. Helm-Repository hinzufügen und aktualisieren: Konfigurieren Sie Ihre Workstation mit dem offiziellen Nextcloud-Helm-Repository und aktualisieren Sie Ihre lokalen Diagrammmetadaten.
  3. Benutzerdefinierte Bereitstellungswerte konfigurieren: Erstellen Sie eine benutzerdefinierte values.yaml-Datei, um Nextcloud für Ihre Zielumgebung zu konfigurieren. Mit dieser Konfiguration wird die standardmäßige lokale SQLite-Datenbank deaktiviert, der nichtflüchtige MariaDB-Speicher konfiguriert, Administratoranmeldedaten definiert und das interne Routing mithilfe eines ClusterIP-Dienstes festgelegt.
  4. Helm-Installation ausführen: Stellen Sie das Diagramm mit Ihrer benutzerdefinierten Konfigurationsdatei im Ziel-Namespace bereit. Prüfen Sie, ob alle Komponenten, einschließlich der Nextcloud-Anwendung und der MariaDB-Speicher-Pods, den Status Running erreichen.
  5. Nextcloud-MCP-Server bereitstellen: Erstellen Sie ein Bereitstellungsmanifest (nextcloud-mcp.yaml) mit einem opaken Secret für Anmeldedaten, einem Deployment mit dem Image nextcloud-mcp-server:latest und einem ClusterIP-Service, der den Port 8000 bereitstellt. Wenden Sie dieses Manifest an, um die interne Kubernetes-DNS-Kommunikation mit der Nextcloud-Anwendung zuzulassen.
  6. Toolserver in kagent registrieren: Verbinden Sie den Server in der kagent-Benutzeroberfläche mit der internen Dienst-URL http://nextcloud-mcp-service.nextcloud.svc.cluster.local:8000/mcp und dem Protokoll STREAMABLE_HTTP.

Nextcloud und den MCP-Server bereitstellen

  1. Erstellen Sie einen Namespace für Nextcloud:

    kubectl create namespace nextcloud

    Die Ausgabe sieht etwa so aus:

    namespace/nextcloud created

  2. Fügen Sie das Nextcloud-Helm-Repository zu Ihrer Workstation hinzu und aktualisieren Sie die lokalen Diagrammmetadaten:

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

    Die Ausgabe sieht etwa so aus:

    "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. Erstellen Sie auf Ihrer Workstation eine benutzerdefinierte values.yaml-Datei, um die Standardkonfigurationsparameter des Nextcloud-Helm-Diagramms zu überschreiben:

    # 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. Stellen Sie Nextcloud mit Helm bereit:

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

    Die Ausgabe sieht etwa so aus:

    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)

    Prüfen Sie, ob die Nextcloud-Pods den Status Running haben und die Dienste im Namespace nextcloud vorhanden sind:

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

    Die Ausgabe sieht etwa so aus:

    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. Wenn Sie den Nextcloud-MCP-Server im Namespace nextcloud bereitstellen möchten, erstellen Sie auf Ihrer Workstation eine Datei mit dem Namen nextcloud-mcp.yaml:

    # 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

    Wenden Sie das nextcloud-mcp.yaml-Manifest an:

    kubectl apply -f nextcloud-mcp.yaml

    Die Ausgabe sieht etwa so aus:

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

    Prüfen Sie, ob die Pods und Dienste im Namespace nextcloud ausgeführt werden:

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

    Die Ausgabe sieht etwa so aus:

    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. Wenn Sie die Nextcloud-MCP-Tools über eine URL einbinden möchten, rufen Sie die kagent-Benutzeroberfläche auf und registrieren Sie einen Toolserver mit den folgenden Werten:

    • URL: http://nextcloud-mcp-service.nextcloud.svc.cluster.local:8000/mcp
    • Protokoll: STREAMABLE_HTTP
    • Namespace: kagent.
    • Cluster: Ihr Clustername (z. B. mgmt-cluster)

    Prüfen Sie, ob die Ressource RemoteMCPServer im Namespace kagent akzeptiert wird:

    kubectl get remotemcpserver -n kagent

    Die Ausgabe sieht etwa so aus:

    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. Wenn Sie von Ihrer Workstation aus auf Nextcloud zugreifen möchten, leiten Sie den lokalen Port 8080 an den Dienst nextcloud weiter. Überspringen Sie diesen Schritt, wenn Sie eine externe URL konfiguriert haben:

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

    Die Ausgabe sieht etwa so aus:

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

Bereitstellung überprüfen und Nextcloud-Agent konfigurieren

Öffnen Sie im Browser Ihrer Workstation http://localhost:8080, um das Nextcloud-Dashboard aufzurufen:

Dashboard-Seite der Nextcloud-Anwendung.

In der Ansicht Dateien werden die in Nextcloud gespeicherten Verzeichnisse und Dateien angezeigt:

Verzeichnis- und Dateioberfläche in der Nextcloud-Anwendung.

In der kagent-Benutzeroberfläche werden auf der Seite Dashboard verbundene Cluster und bereitgestellte Agents angezeigt:

kagent-Anwendungs-Dashboard.

Auf der Seite Tool-Server werden die Tools aufgeführt, die über MCP für die Nextcloud-Anwendung gefunden wurden:

Seite „kagent-Tool-Server“ mit den für die Nextcloud-Anwendung gefundenen Tools.

Auf der Seite Tools wird die Sammlung von Nextcloud-Tools angezeigt, die für Kundenservicemitarbeiter verfügbar sind:

kagent-Toolsammlung in Nextcloud verfügbar.

Geben Sie zum Erstellen des nextcloud-Agents in der kagent-Benutzeroberfläche unter Grundlegende Informationen den Namen des Agents, den Cluster, den Namespace und die Beschreibung ein:

Kagent-Agentenerstellung für Nextcloud.

Wählen Sie unter Verhaltens- und Modelleinstellungen das Gemma 4-Modell aus und geben Sie die Systemanweisungen für den KI-Agenten ein:

kagent-Agentenkonfiguration für die Abstimmung von Skills und Modellen.

Wählen Sie unter Tools und Agenten die Nextcloud-MCP-Tools für den Agenten aus und klicken Sie dann auf Agent erstellen:

kagent-Agentenkonfiguration für die Nextcloud-Toolauswahl.

Auf der Seite Agenten wird der Agent nextcloud mit dem Status Ready angezeigt:

KI-Agenten, die der kagent-Anwendung hinzugefügt wurden.

Sie können den Nextcloud-Agenten auffordern, Verzeichnisse und Dateien in der Nextcloud-Anwendung aufzulisten:

Nextcloud-Agent, der Verzeichnisse und Dateien auflistet.

Sie können den Nextcloud-Agenten auch auffordern, Dateiinhalte vom Englischen ins Französische zu übersetzen und zu transkribieren:

Nextcloud-Agent, der Dateiinhalte vom Englischen ins Französische übersetzt.