Usa tu propio servidor de MCP para la implementación de referencia de kagent

Introducción

Los servidores de Protocolo de contexto del modelo (MCP) de tipo Bring Your Own (BYO) permiten que los agentes de IA consulten y procesen datos de repositorios externos en tiempo real con conexiones estandarizadas en tu infraestructura existente.

En este documento de implementación de referencia de la solución (SRI), se muestra cómo implementar la aplicación de código abierto Nextcloud y su servidor de MCP junto con un agente de Nextcloud en Solo Enterprise para kagent. Esta arquitectura conecta Nextcloud, kagent y el modelo Gemma 4 dentro de un clúster de Google Kubernetes Engine (GKE) implementado en Distributed Cloud, versión Solo Software (GDC). En esta configuración, kagent usa Nextcloud como repositorio de datos, lo que permite que el modelo Gemma 4 acceda a los archivos de Nextcloud y los procese a través de interfaces de MCP estandarizadas. Para obtener contexto de la arquitectura, consulta la arquitectura de referencia complementaria.

Descripción general de Nextcloud

Nextcloud es una plataforma de código abierto, de colaboración y almacenamiento en la nube autohospedada que admite la implementación local. Implementar Nextcloud de forma local ayuda a mantener la soberanía, la seguridad y la privacidad de tus datos.

Nextcloud proporciona las siguientes funciones:

  • Sincronización y uso compartido de archivos: Almacena archivos, sincronízalos en tus dispositivos móviles y de escritorio a través de apps dedicadas, y compártelos con otras personas mediante vínculos.
  • Herramientas de productividad: Administra las agendas y la comunicación con clientes de correo electrónico, administración de tareas, contactos y calendario integrados.
  • Colaboración: Integra paquetes de oficina (como Collabora Online o ONLYOFFICE) directamente en Nextcloud para coeditar documentos, hojas de cálculo y presentaciones en tiempo real.
  • Extensibilidad: Instala complementos desde la tienda de aplicaciones para agregar funciones, como administradores de contraseñas, tableros Kanban o reproductores de música.

Arquitectura de soluciones

Esta solución requiere un entorno de GDC con Solo Enterprise para kagent y vLLM con el modelo Gemma 4 implementados, y una estación de trabajo con kubectl y helm instalados.

En el siguiente diagrama, se ilustra la arquitectura de la solución que conecta GDC, kagent, Nextcloud y vLLM con Gemma 4:

Arquitectura de la solución: GDC, kagent, Nextcloud y vLLM con Gemma 4.

Enfoque de Deployment

Para implementar Nextcloud y, luego, integrar su servidor de MCP con kagent, completa los siguientes pasos de alto nivel:

  1. Crea un espacio de nombres dedicado para Nextcloud: Aísla la implementación creando el espacio de nombres nextcloud con kubectl.
  2. Agrega y actualiza el repositorio de Helm: Configura tu estación de trabajo con el repositorio oficial de Helm de Nextcloud y actualiza los metadatos de tu gráfico local.
  3. Configura valores de implementación personalizados: Crea un archivo values.yaml personalizado para configurar Nextcloud para tu entorno de destino. Esta configuración inhabilita la base de datos de SQLite local predeterminada, configura el almacenamiento persistente de MariaDB, define las credenciales de administrador y establece el enrutamiento interno con un servicio de ClusterIP.
  4. Ejecuta la instalación de Helm: Implementa el gráfico en el espacio de nombres de destino con tu archivo de configuración personalizado. Verifica que todos los componentes, incluidos la aplicación de Nextcloud y los Pods de almacenamiento de MariaDB, alcancen el estado Running.
  5. Implementa el servidor de MCP de Nextcloud: Crea un manifiesto de implementación (nextcloud-mcp.yaml) que contenga un Secret opaco para las credenciales, un Deployment que use la imagen nextcloud-mcp-server:latest y un Service ClusterIP que exponga el puerto 8000. Aplica este manifiesto para permitir la comunicación interna del DNS de Kubernetes con la aplicación de Nextcloud.
  6. Registra el servidor de herramientas en kagent: Conecta el servidor en la IU de kagent con la URL del servicio interno http://nextcloud-mcp-service.nextcloud.svc.cluster.local:8000/mcp y el protocolo STREAMABLE_HTTP.

Implementa Nextcloud y el servidor de MCP

  1. Crea un espacio de nombres para Nextcloud:

    kubectl create namespace nextcloud

    El resultado es similar a lo siguiente:

    namespace/nextcloud created

  2. Agrega el repositorio de Helm de Nextcloud a tu estación de trabajo y actualiza los metadatos del gráfico local:

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

    El resultado es similar a lo siguiente:

    "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 archivo values.yaml personalizado en tu estación de trabajo para anular los parámetros de configuración predeterminados del gráfico de Helm de 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. Implementa Nextcloud con Helm:

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

    El resultado es similar a lo siguiente:

    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 que los Pods de Nextcloud estén en el estado Running y que los Services existan en el espacio de nombres nextcloud:

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

    El resultado es similar a lo siguiente:

    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. Para implementar el servidor de MCP de Nextcloud en el espacio de nombres nextcloud, crea un archivo llamado nextcloud-mcp.yaml en tu estación de trabajo:

    # 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

    Aplica el manifiesto nextcloud-mcp.yaml:

    kubectl apply -f nextcloud-mcp.yaml

    El resultado es similar a lo siguiente:

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

    Verifica que los Pods y los Services se estén ejecutando en el espacio de nombres nextcloud:

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

    El resultado es similar a lo siguiente:

    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. Para integrar las herramientas de MCP de Nextcloud por URL, ve a la IU de kagent y registra un servidor de herramientas con los siguientes valores:

    • URL: http://nextcloud-mcp-service.nextcloud.svc.cluster.local:8000/mcp
    • Protocolo: STREAMABLE_HTTP
    • Espacio de nombres: kagent
    • Clúster: Es el nombre de tu clúster (por ejemplo, mgmt-cluster).

    Verifica que se acepte el recurso RemoteMCPServer en el espacio de nombres kagent:

    kubectl get remotemcpserver -n kagent

    El resultado es similar a lo siguiente:

    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. Para acceder a Nextcloud desde tu estación de trabajo, reenvía el puerto local 8080 al servicio nextcloud (omite este paso si configuraste una URL externa):

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

    El resultado es similar a lo siguiente:

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

Verifica la implementación y configura el agente de Nextcloud

En el navegador de tu estación de trabajo, abre http://localhost:8080 para ver el panel de Nextcloud:

Página del panel de la aplicación de Nextcloud.

En la vista Archivos, se muestran los directorios y archivos almacenados en Nextcloud:

Interfaz de directorio y archivos dentro de la aplicación de Nextcloud.

En la IU de kagent, la página Panel muestra los clústeres conectados y los agentes implementados:

Panel de la aplicación kagent.

En la página Servidores de herramientas, se enumeran las herramientas descubiertas a través de MCP para la aplicación de Nextcloud:

Página Servidores de herramientas de kagent en la que se muestran las herramientas detectadas para la aplicación de Nextcloud.

En la página Herramientas, se muestra la colección de herramientas de Nextcloud disponibles para los agentes:

Colección de herramientas de kagent disponible en Nextcloud.

Para crear el agente nextcloud en la IU de kagent, ingresa el nombre del agente, el clúster, el espacio de nombres y la descripción en Información básica:

Creación del agente kagent para Nextcloud.

En Configuración de comportamiento y modelo, selecciona el modelo Gemma 4 y, luego, ingresa las instrucciones del sistema para el agente:

Configuración del agente kagent para la alineación de habilidades y modelos.

En Herramientas y agentes, selecciona las herramientas de MCP de Nextcloud para el agente y, luego, haz clic en Crear agente:

Configuración del agente kagent para la selección de la herramienta Nextcloud.

En la página Agentes, se muestra el agente nextcloud con el estado Ready:

Se agregaron agentes a la aplicación kagent.

Puedes pedirle al agente de Nextcloud que enumere los directorios y archivos de la aplicación de Nextcloud:

Agente de Nextcloud que enumera directorios y archivos.

También puedes pedirle al agente de Nextcloud que traduzca y translitere el contenido de los archivos del inglés al francés:

Agente de Nextcloud que traduce el contenido de un archivo del inglés al francés.