Traga seu próprio servidor MCP para a implementação de referência do kagent

Introdução

Os servidores do Protocolo de Contexto de Modelo (MCP, na sigla em inglês) personalizados (BYO, na sigla em inglês) permitem que os agentes de IA consultem e processem dados de repositórios externos em tempo real usando conexões padronizadas na infraestrutura atual.

Este documento de implementação de referência de solução (SRI, na sigla em inglês) mostra como implantar o aplicativo de código aberto Nextcloud e o servidor MCP dele com um agente do Nextcloud no Solo Enterprise para kagent. Essa arquitetura conecta o Nextcloud, o kagent e o modelo Gemma 4 em um cluster do Google Kubernetes Engine (GKE) implantado no Distributed Cloud somente software (GDC). Nessa configuração, o kagent usa o Nextcloud como um repositório de dados, permitindo que o modelo Gemma 4 acesse e processe arquivos no Nextcloud por meio de interfaces MCP padronizadas. Para contexto arquitetônico, consulte a arquitetura de referência complementar.

Visão geral do Nextcloud

O Nextcloud é uma plataforma de colaboração e armazenamento em nuvem de código aberto e auto-hospedada que oferece suporte à implantação no local. A implantação do Nextcloud no local ajuda a manter a soberania, a segurança e a privacidade dos seus dados.

O Nextcloud oferece os seguintes recursos:

  • Sincronização e compartilhamento de arquivos: armazene arquivos, sincronize-os entre computadores e dispositivos móveis usando apps dedicados e compartilhe-os com outras pessoas usando links.
  • Ferramentas de produtividade: gerencie agendas e comunicações com clientes de e-mail, gerenciamento de tarefas, contatos e agenda integrados.
  • Colaboração: integre pacotes de escritório (como o Collabora Online ou o ONLYOFFICE) diretamente ao Nextcloud para coeditar documentos, planilhas e apresentações em tempo real.
  • Extensibilidade: instale plug-ins da app store para adicionar recursos como gerenciadores de senhas, quadros Kanban ou players de música.

Arquitetura da solução

Essa solução requer um ambiente do GDC com o Solo Enterprise para kagent e o vLLM com o modelo Gemma 4 implantados, além de uma estação de trabalho com o kubectl e o helm instalados.

O diagrama a seguir ilustra a arquitetura da solução que conecta o GDC, o kagent, o Nextcloud e o vLLM ao Gemma 4:

Arquitetura da solução: GDC, kagent, Nextcloud e vLLM com Gemma 4.

Abordagem de implantação

Para implantar o Nextcloud e integrar o servidor MCP dele ao kagent, siga estas etapas gerais:

  1. Crie um namespace dedicado para o Nextcloud: isole a implantação criando o namespace nextcloud usando kubectl.
  2. Adicione e atualize o repositório do Helm: configure sua estação de trabalho com o repositório oficial do Nextcloud Helm e atualize os metadados do gráfico local.
  3. Configurar valores de implantação personalizados: crie um arquivo values.yaml personalizado para configurar o Nextcloud para seu ambiente de destino. Essa configuração desativa o banco de dados SQLite local padrão, configura o armazenamento persistente do MariaDB, define as credenciais de administrador e define o roteamento interno usando um serviço ClusterIP.
  4. Execute a instalação do Helm: implante o gráfico no namespace de destino usando o arquivo de configuração personalizado. Verifique se todos os componentes, incluindo o aplicativo Nextcloud e os pods de armazenamento do MariaDB, alcançam o status Running.
  5. Implante o servidor MCP do Nextcloud: crie um manifesto de implantação (nextcloud-mcp.yaml) que contenha um Secret opaco para credenciais, uma implantação que use a imagem nextcloud-mcp-server:latest e um serviço ClusterIP que exponha a porta 8000. Aplique esse manifesto para permitir a comunicação interna do DNS do Kubernetes com o aplicativo Nextcloud.
  6. Registre o servidor de ferramentas no kagent: conecte o servidor na UI do kagent usando o URL do serviço interno http://nextcloud-mcp-service.nextcloud.svc.cluster.local:8000/mcp e o protocolo STREAMABLE_HTTP.

Implantar o Nextcloud e o servidor MCP

  1. Crie um namespace para o Nextcloud:

    kubectl create namespace nextcloud

    O resultado será o seguinte:

    namespace/nextcloud created

  2. Adicione o repositório do Helm do Nextcloud à estação de trabalho e atualize os metadados do gráfico local:

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

    O resultado será o seguinte:

    "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. Crie um arquivo values.yaml personalizado na estação de trabalho para substituir os parâmetros de configuração padrão do gráfico do Helm do 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. Implante o Nextcloud usando o Helm:

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

    O resultado será o seguinte:

    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)

    Verifique se os pods do Nextcloud estão no status Running e se os serviços existem no namespace nextcloud:

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

    O resultado será o seguinte:

    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 implantar o servidor MCP do Nextcloud no namespace nextcloud, crie um arquivo chamado nextcloud-mcp.yaml na estação de trabalho:

    # 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

    Aplique o manifesto nextcloud-mcp.yaml:

    kubectl apply -f nextcloud-mcp.yaml

    O resultado será o seguinte:

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

    Verifique se os pods e serviços estão em execução no namespace nextcloud:

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

    O resultado será o seguinte:

    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 as ferramentas MCP do Nextcloud por URL, acesse a UI do kagent e registre um servidor de ferramentas com os seguintes valores:

    • URL: http://nextcloud-mcp-service.nextcloud.svc.cluster.local:8000/mcp
    • Protocolo: STREAMABLE_HTTP
    • Namespace: kagent
    • Cluster: o nome do cluster (por exemplo, mgmt-cluster)

    Verifique se o recurso RemoteMCPServer foi aceito no namespace kagent:

    kubectl get remotemcpserver -n kagent

    O resultado será o seguinte:

    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 acessar o Nextcloud na estação de trabalho, encaminhe a porta local 8080 para o serviço nextcloud (pule esta etapa se você tiver configurado um URL externo):

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

    O resultado será o seguinte:

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

Verificar a implantação e configurar o agente do Nextcloud

No navegador da estação de trabalho, abra http://localhost:8080 para ver o painel do Nextcloud:

Página do painel do aplicativo Nextcloud.

A visualização Arquivos mostra os diretórios e arquivos armazenados no Nextcloud:

Interface de diretórios e arquivos no aplicativo Nextcloud.

Na UI do kagent, a página Painel mostra os clusters conectados e os agentes implantados:

Painel do aplicativo kagent.

A página Servidores de ferramentas lista as ferramentas descobertas pelo MCP para o aplicativo Nextcloud:

Página &quot;Servidores de ferramentas&quot; do kagent mostrando as ferramentas descobertas para o aplicativo Nextcloud.

A página Ferramentas mostra a coleção de ferramentas do Nextcloud disponíveis para os agentes:

Coleção de ferramentas kagent disponível no Nextcloud.

Para criar o agente nextcloud na UI do kagent, insira o nome, o cluster, o namespace e a descrição do agente em Informações básicas:

Criação de agente kagent para o Nextcloud.

Em Configurações de comportamento e modelo, selecione o modelo Gemma 4 e insira as instruções do sistema para o agente:

Configuração do agente kagent para alinhamento de habilidades e modelos.

Em Ferramentas e agentes, selecione as ferramentas do MCP do Nextcloud para o agente e clique em Criar agente:

Configuração do agente kagent para seleção da ferramenta Nextcloud.

A página Agentes mostra o agente nextcloud com o status Ready:

Agentes adicionados ao aplicativo kagent.

Você pode pedir ao agente do Nextcloud para listar diretórios e arquivos no aplicativo Nextcloud:

Agente do Nextcloud listando diretórios e arquivos.

Também é possível pedir ao agente do Nextcloud para traduzir e transliterar o conteúdo do arquivo do inglês para o francês:

Agente do Nextcloud traduzindo o conteúdo de um arquivo do inglês para o francês.