Utiliser votre propre serveur MCP pour l'implémentation de référence kagent

Introduction

Les serveurs MCP (Model Context Protocol) BYO (Bring Your Own) permettent aux agents IA d'interroger et de traiter des données provenant de dépôts externes en temps réel à l'aide de connexions standardisées sur votre infrastructure existante.

Ce document d'implémentation de référence de solution (SRI) vous explique comment déployer l'application Open Source Nextcloud et son serveur MCP avec un agent Nextcloud sur Solo Enterprise pour kagent. Cette architecture connecte Nextcloud, kagent et le modèle Gemma 4 au sein d'un cluster Google Kubernetes Engine (GKE) déployé dans Distributed Cloud – Logiciel uniquement (GDC). Dans cette configuration, kagent utilise Nextcloud comme dépôt de données, ce qui permet au modèle Gemma 4 d'accéder aux fichiers de Nextcloud et de les traiter via des interfaces MCP standardisées. Pour en savoir plus sur le contexte architectural, consultez l'architecture de référence associée.

Présentation de Nextcloud

Nextcloud est une plate-forme Open Source d'hébergement de fichiers et de collaboration qui accepte le déploiement sur site. Le déploiement de Nextcloud sur site permet de maintenir la souveraineté, la sécurité et la confidentialité de vos données.

Nextcloud propose les fonctionnalités suivantes :

  • Synchronisation et partage de fichiers : stockez des fichiers, synchronisez-les sur vos ordinateurs et appareils mobiles via des applications dédiées, et partagez-les avec d'autres personnes à l'aide de liens.
  • Outils de productivité : gérez les plannings et les communications grâce à des clients de messagerie, des agendas, des contacts et des outils de gestion des tâches intégrés.
  • Collaboration : intégrez des suites bureautiques (telles que Collabora Online ou ONLYOFFICE) directement dans Nextcloud pour coéditer des documents, des feuilles de calcul et des présentations en temps réel.
  • Extensibilité : installez des plug-ins depuis le magasin d'applications pour ajouter des fonctionnalités telles que des gestionnaires de mots de passe, des tableaux Kanban ou des lecteurs de musique.

Architecture de la solution

Cette solution nécessite un environnement GDC avec Solo Enterprise pour kagent et vLLM avec le modèle Gemma 4 déployés, ainsi qu'un poste de travail sur lequel kubectl et helm sont installés.

Le schéma suivant illustre l'architecture de la solution connectant GDC, kagent, Nextcloud et vLLM à Gemma 4 :

Architecture de la solution : GDC, kagent, Nextcloud et vLLM avec Gemma 4.

Approche de déploiement

Pour déployer Nextcloud et intégrer son serveur MCP à kagent, procédez comme suit :

  1. Créer un espace de noms dédié pour Nextcloud : isolez le déploiement en créant l'espace de noms nextcloud à l'aide de kubectl.
  2. Ajouter et mettre à jour le dépôt Helm : configurez votre poste de travail avec le dépôt Helm Nextcloud officiel et mettez à jour les métadonnées de votre chart local.
  3. Configurer des valeurs de déploiement personnalisées : créez un fichier values.yaml personnalisé pour configurer Nextcloud pour votre environnement cible. Cette configuration désactive la base de données SQLite locale par défaut, configure le stockage persistant MariaDB, définit les identifiants d'administrateur et configure le routage interne à l'aide d'un service ClusterIP.
  4. Exécutez l'installation Helm : déployez le chart dans l'espace de noms cible à l'aide de votre fichier de configuration personnalisé. Vérifiez que tous les composants, y compris l'application Nextcloud et les pods de stockage MariaDB, atteignent l'état Running.
  5. Déployer le serveur MCP Nextcloud : créez un fichier manifeste de déploiement (nextcloud-mcp.yaml) contenant un secret opaque pour les identifiants, un déploiement utilisant l'image nextcloud-mcp-server:latest et un service ClusterIP exposant le port 8000. Appliquez ce fichier manifeste pour autoriser la communication DNS Kubernetes interne avec l'application Nextcloud.
  6. Enregistrer le serveur d'outils sur kagent : connectez le serveur dans l'interface utilisateur de kagent à l'aide de l'URL du service interne http://nextcloud-mcp-service.nextcloud.svc.cluster.local:8000/mcp et du protocole STREAMABLE_HTTP.

Déployer Nextcloud et le serveur MCP

  1. Créez un espace de noms pour Nextcloud :

    kubectl create namespace nextcloud

    Le résultat ressemble à ce qui suit :

    namespace/nextcloud created

  2. Ajoutez le dépôt Helm Nextcloud à votre poste de travail et mettez à jour les métadonnées de votre chart local :

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

    Le résultat ressemble à ce qui suit :

    "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. Créez un fichier values.yaml personnalisé sur votre poste de travail pour remplacer les paramètres de configuration par défaut du 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. Déployez Nextcloud à l'aide de Helm :

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

    Le résultat ressemble à ce qui suit :

    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)

    Vérifiez que les pods Nextcloud sont à l'état Running et que les services existent dans l'espace de noms nextcloud :

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

    Le résultat ressemble à ce qui suit :

    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. Pour déployer le serveur MCP Nextcloud dans l'espace de noms nextcloud, créez un fichier nommé nextcloud-mcp.yaml sur votre station de travail :

    # 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

    Appliquez le fichier manifeste nextcloud-mcp.yaml :

    kubectl apply -f nextcloud-mcp.yaml

    Le résultat ressemble à ce qui suit :

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

    Vérifiez que les pods et les services sont en cours d'exécution dans l'espace de noms nextcloud :

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

    Le résultat ressemble à ce qui suit :

    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. Pour intégrer les outils MCP Nextcloud par URL, accédez à l'interface utilisateur de kagent et enregistrez un serveur d'outils avec les valeurs suivantes :

    • URL : http://nextcloud-mcp-service.nextcloud.svc.cluster.local:8000/mcp
    • Protocole : STREAMABLE_HTTP
    • Namespace (Espace de noms) : kagent
    • Cluster : nom de votre cluster (par exemple, mgmt-cluster)

    Vérifiez que la ressource RemoteMCPServer est acceptée dans l'espace de noms kagent :

    kubectl get remotemcpserver -n kagent

    Le résultat ressemble à ce qui suit :

    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. Pour accéder à Nextcloud depuis votre poste de travail, transférez le port local 8080 vers le service nextcloud (ignorez cette étape si vous avez configuré une URL externe) :

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

    Le résultat ressemble à ce qui suit :

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

Vérifier le déploiement et configurer l'agent Nextcloud

Dans le navigateur de votre poste de travail, ouvrez http://localhost:8080 pour afficher le tableau de bord Nextcloud :

Page du tableau de bord de l'application Nextcloud.

La vue Files (Fichiers) affiche les répertoires et les fichiers stockés dans Nextcloud :

Interface &quot;Directory and Files&quot; (Répertoire et fichiers) dans l'application Nextcloud.

Dans l'interface utilisateur de kagent, la page Tableau de bord affiche les clusters connectés et les agents déployés :

Tableau de bord de l'application kagent.

La page Serveurs d'outils liste les outils découverts via MCP pour l'application Nextcloud :

Page &quot;Serveurs d'outils&quot; de kagent affichant les outils détectés pour l'application Nextcloud.

La page Outils affiche la collection d'outils Nextcloud disponibles pour les agents :

Collection d'outils kagent disponible dans Nextcloud.

Pour créer l'agent nextcloud dans l'interface utilisateur de kagent, saisissez le nom de l'agent, le cluster, l'espace de noms et la description sous Informations de base :

Création d'un agent kagent pour Nextcloud.

Sous Paramètres de comportement et de modèle, sélectionnez le modèle Gemma 4 et saisissez les instructions système pour l'agent :

Configuration de l'agent kagent pour l'alignement des compétences et des modèles.

Sous Outils et agents, sélectionnez les outils MCP Nextcloud pour l'agent, puis cliquez sur Créer un agent :

Configuration de l'agent kagent pour la sélection de l'outil Nextcloud.

La page Agents affiche l'agent nextcloud avec l'état Ready :

Agents ajoutés à l'application kagent.

Vous pouvez demander à l'agent Nextcloud de lister les répertoires et les fichiers de l'application Nextcloud :

Agent Nextcloud listant les répertoires et les fichiers.

Vous pouvez également demander à l'agent Nextcloud de traduire et de translittérer le contenu d'un fichier de l'anglais vers le français :

Agent Nextcloud traduisant le contenu d'un fichier de l'anglais vers le français.