Bring your own MCP server to kagent reference implementation

Introduzione

I server Model Context Protocol (MCP) Bring Your Own (BYO) consentono agli agenti AI di eseguire query e di elaborare i dati da repository esterni in tempo reale utilizzando connessioni standardizzate nell'infrastruttura esistente.

Questo documento di implementazione di riferimento della soluzione (SRI) mostra come eseguire il deployment dell'applicazione open source Nextcloud e del relativo server MCP insieme a un agente Nextcloud su Solo Enterprise per kagent. Questa architettura connette Nextcloud, kagent e il modello Gemma 4 all'interno di un cluster Google Kubernetes Engine (GKE) di cui è stato eseguito il deployment in Distributed Cloud solo software (GDC). In questa configurazione, kagent utilizza Nextcloud come repository di dati, consentendo al modello Gemma 4 di accedere ai file in Nextcloud ed elaborarli tramite interfacce MCP standardizzate. Per il contesto dell'architettura, consulta l'architettura di riferimento associata.

Panoramica di Nextcloud

Nextcloud è una piattaforma di collaborazione e spazio di archiviazione sul cloud open source, self-hosted, che supporta il deployment on-premise. Il deployment di Nextcloud on-premise aiuta a mantenere la sovranità, la sicurezza e la privacy dei tuoi dati.

Nextcloud offre le seguenti funzionalità:

  • Sincronizzazione e condivisione dei file: archivia i file, sincronizzali su computer e dispositivi mobili tramite app dedicate e condividili con altri utenti utilizzando i link.
  • Strumenti di produttività: gestisci le pianificazioni e le comunicazioni con calendario, contatti, gestione delle attività e client di posta integrati.
  • Collaborazione: integra le suite per ufficio (come Collabora Online o ONLYOFFICE) direttamente in Nextcloud per modificare insieme documenti, fogli di lavoro e presentazioni in tempo reale.
  • Estensibilità: installa i plug-in dall'app store per aggiungere funzionalità come gestori delle password, bacheche Kanban o lettori musicali.

Architettura della soluzione

Questa soluzione richiede un ambiente GDC con Solo Enterprise per kagent e vLLM con il modello Gemma 4 di cui è stato eseguito il deployment, nonché una workstation con kubectl e helm installati.

Il seguente diagramma illustra l'architettura della soluzione che collega GDC, kagent, Nextcloud e vLLM con Gemma 4:

Architettura della soluzione: GDC, kagent, Nextcloud e vLLM con Gemma 4.

Approccio al deployment

Per eseguire il deployment di Nextcloud e integrare il suo server MCP con kagent, completa i seguenti passaggi di alto livello:

  1. Crea uno spazio dei nomi dedicato per Nextcloud: isola il deployment creando lo spazio dei nomi nextcloud utilizzando kubectl.
  2. Aggiungi e aggiorna il repository Helm: configura la tua workstation con il repository Helm Nextcloud ufficiale e aggiorna i metadati del grafico locale.
  3. Configura i valori di deployment personalizzati: crea un file values.yaml personalizzato per configurare Nextcloud per l'ambiente di destinazione. Questa configurazione disattiva il database SQLite locale predefinito, configura l'archiviazione permanente di MariaDB, definisce le credenziali di amministratore e imposta il routing interno utilizzando un servizio ClusterIP.
  4. Esegui l'installazione di Helm: esegui il deployment del grafico nello spazio dei nomi di destinazione utilizzando il file di configurazione personalizzato. Verifica che tutti i componenti, inclusi l'applicazione Nextcloud e i pod di archiviazione MariaDB, raggiungano lo stato Running.
  5. Esegui il deployment del server MCP Nextcloud: crea un manifest di deployment (nextcloud-mcp.yaml) contenente un secret opaco per le credenziali, un deployment che utilizza l'immagine nextcloud-mcp-server:latest e un servizio ClusterIP che espone la porta 8000. Applica questo manifest per consentire la comunicazione DNS interna di Kubernetes con l'applicazione Nextcloud.
  6. Registra il server degli strumenti su kagent: connetti il server nell'interfaccia utente di kagent utilizzando l'URL del servizio interno http://nextcloud-mcp-service.nextcloud.svc.cluster.local:8000/mcp e il protocollo STREAMABLE_HTTP.

Esegui il deployment di Nextcloud e del server MCP

  1. Crea uno spazio dei nomi per Nextcloud:

    kubectl create namespace nextcloud

    L'output è simile al seguente:

    namespace/nextcloud created

  2. Aggiungi il repository Helm di Nextcloud alla tua workstation e aggiorna i metadati del grafico locale:

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

    L'output è simile al seguente:

    "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. Crea un file values.yaml personalizzato sulla tua workstation per eseguire l'override dei parametri di configurazione predefiniti del grafico Helm di 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. Esegui il deployment di Nextcloud utilizzando Helm:

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

    L'output è simile al seguente:

    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)

    Verifica che i pod Nextcloud siano nello stato Running e che i servizi esistano nello spazio dei nomi nextcloud:

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

    L'output è simile al seguente:

    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. Per eseguire il deployment del server MCP Nextcloud nello spazio dei nomi nextcloud, crea un file denominato nextcloud-mcp.yaml sulla tua workstation:

    # 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

    Applica il manifest nextcloud-mcp.yaml:

    kubectl apply -f nextcloud-mcp.yaml

    L'output è simile al seguente:

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

    Verifica che i pod e i servizi siano in esecuzione nello spazio dei nomi nextcloud:

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

    L'output è simile al seguente:

    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. Per integrare gli strumenti MCP di Nextcloud tramite URL, vai alla UI di kagent e registra un server di strumenti con i seguenti valori:

    • URL: http://nextcloud-mcp-service.nextcloud.svc.cluster.local:8000/mcp
    • Protocollo: STREAMABLE_HTTP
    • Namespace: kagent
    • Cluster: il nome del tuo cluster (ad esempio, mgmt-cluster)

    Verifica che la risorsa RemoteMCPServer sia accettata nello spazio dei nomi kagent:

    kubectl get remotemcpserver -n kagent

    L'output è simile al seguente:

    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. Per accedere a Nextcloud dalla tua workstation, inoltra la porta locale 8080 al servizio nextcloud (salta questo passaggio se hai configurato un URL esterno):

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

    L'output è simile al seguente:

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

Verifica il deployment e configura l'agente Nextcloud

Dal browser della tua workstation, apri http://localhost:8080 per visualizzare la dashboard di Nextcloud:

Pagina della dashboard dell'applicazione Nextcloud.

La visualizzazione File mostra le directory e i file archiviati in Nextcloud:

Interfaccia di directory e file all'interno dell'applicazione Nextcloud.

Nella UI di kagent, la pagina Dashboard mostra i cluster connessi e gli agenti di cui è stato eseguito il deployment:

Dashboard dell'applicazione kagent.

La pagina Server degli strumenti elenca gli strumenti rilevati tramite MCP per l'applicazione Nextcloud:

Pagina Server degli strumenti di kagent che mostra gli strumenti rilevati per l'applicazione Nextcloud.

La pagina Strumenti mostra la raccolta di strumenti Nextcloud disponibili per gli agenti:

Raccolta di strumenti kagent disponibile in Nextcloud.

Per creare l'agente nextcloud nella UI di kagent, inserisci il nome, il cluster, lo spazio dei nomi e la descrizione dell'agente in Informazioni di base:

Creazione dell'agente kagent per Nextcloud.

In Impostazioni di comportamento e modello, seleziona il modello Gemma 4 e inserisci le istruzioni di sistema per l'agente:

Configurazione dell'agente kagent per l'allineamento di competenze e modelli.

In Strumenti e agenti, seleziona gli strumenti MCP di Nextcloud per l'agente, quindi fai clic su Crea agente:

Configurazione dell'agente kagent per la selezione dello strumento Nextcloud.

Nella pagina Agenti viene visualizzato l'agente nextcloud con lo stato Ready:

Agenti aggiunti all'applicazione kagent.

Puoi chiedere all'agente Nextcloud di elencare directory e file nell'applicazione Nextcloud:

Agente Nextcloud che elenca directory e file.

Puoi anche chiedere all'agente Nextcloud di tradurre e traslitterare i contenuti dei file dall'inglese al francese:

Agente Nextcloud che traduce i contenuti dei file dall'inglese al francese.