소개
자체 모델 컨텍스트 프로토콜(MCP) 서버를 사용하면 AI 에이전트가 기존 인프라 전반에서 표준화된 연결을 사용하여 실시간으로 외부 저장소의 데이터를 쿼리하고 처리할 수 있습니다.
이 솔루션 참조 구현(SRI) 문서에서는 kagent용 Solo Enterprise에서 Nextcloud 에이전트와 함께 Nextcloud 오픈소스 애플리케이션과 MCP 서버를 배포하는 방법을 보여줍니다. 이 아키텍처는 Google Distributed Cloud 소프트웨어 전용(GDC)에 배포된 Google Kubernetes Engine(GKE) 클러스터 내에서 Nextcloud, kagent, Gemma 4 모델을 연결합니다. 이 구성에서 kagent는 Nextcloud를 데이터 저장소로 사용하여 Gemma 4 모델이 표준화된 MCP 인터페이스를 통해 Nextcloud의 파일에 액세스하고 처리할 수 있도록 합니다. 아키텍처 컨텍스트는 함께 제공되는 참조 아키텍처를 참조하세요.
Nextcloud 개요
Nextcloud는 온프레미스 배포를 지원하는 오픈소스 자체 호스팅 공동작업 및 클라우드 스토리지 플랫폼입니다. 온프레미스에 Nextcloud를 배포하면 데이터에 대한 주권, 보안, 개인 정보 보호를 유지하는 데 도움이 됩니다.
Nextcloud는 다음과 같은 기능을 제공합니다.
- 파일 동기화 및 공유: 파일을 저장하고 전용 앱을 통해 데스크톱과 휴대기기 간에 동기화하며 링크를 사용하여 다른 사용자와 공유합니다.
- 생산성 도구: 기본 제공되는 캘린더, 연락처, 작업 관리, 이메일 클라이언트를 사용하여 일정과 커뮤니케이션을 관리합니다.
- 공동작업: Collabora Online 또는 ONLYOFFICE와 같은 오피스 제품군을 Nextcloud에 직접 통합하여 문서, 스프레드시트, 프레젠테이션을 실시간으로 공동 수정합니다.
- 확장성: 앱 스토어에서 플러그인을 설치하여 비밀번호 관리자, Kanban 보드, 음악 플레이어와 같은 기능을 추가할 수 있습니다.
솔루션 아키텍처
이 솔루션에는 kagent용 Solo Enterprise 및 Gemma 4 모델이 포함된 vLLM이 배포된 GDC 환경과 kubectl 및 helm가 설치된 워크스테이션이 필요합니다.
다음 다이어그램은 GDC, kagent, Nextcloud, vLLM을 Gemma 4와 연결하는 솔루션 아키텍처를 보여줍니다.
배포 방식
Nextcloud를 배포하고 MCP 서버를 kagent와 통합하려면 다음 상위 수준 단계를 완료하세요.
- Nextcloud 전용 네임스페이스 만들기:
kubectl를 사용하여nextcloud네임스페이스를 만들어 배포를 격리합니다. - Helm 저장소 추가 및 업데이트: 공식 Nextcloud Helm 저장소로 워크스테이션을 구성하고 로컬 차트 메타데이터를 업데이트합니다.
- 커스텀 배포 값 구성: 커스텀
values.yaml파일을 만들어 대상 환경에 맞게 Nextcloud를 구성합니다. 이 구성은 기본 로컬 SQLite 데이터베이스를 사용 중지하고, MariaDB 영구 스토리지를 구성하고, 관리자 사용자 인증 정보를 정의하고,ClusterIP서비스를 사용하여 내부 라우팅을 설정합니다. - Helm 설치 실행: 커스텀 구성 파일을 사용하여 차트를 대상 네임스페이스에 배포합니다. Nextcloud 애플리케이션 및 MariaDB 스토리지 포드를 포함한 모든 구성요소가
Running상태에 도달하는지 확인합니다. - Nextcloud MCP 서버 배포: 사용자 인증 정보에 대한 불투명 보안 비밀,
nextcloud-mcp-server:latest이미지를 사용하는 배포,8000포트를 노출하는ClusterIP서비스를 포함하는 배포 매니페스트(nextcloud-mcp.yaml)를 만듭니다. 이 매니페스트를 적용하여 Nextcloud 애플리케이션과의 내부 Kubernetes DNS 통신을 허용합니다. - kagent에 도구 서버 등록: 내부 서비스 URL
http://nextcloud-mcp-service.nextcloud.svc.cluster.local:8000/mcp및STREAMABLE_HTTP프로토콜을 사용하여 kagent UI에서 서버를 연결합니다.
Nextcloud 및 MCP 서버 배포
Nextcloud의 네임스페이스를 만듭니다.
kubectl create namespace nextcloud출력은 다음과 비슷합니다.
namespace/nextcloud createdNextcloud Helm 저장소를 워크스테이션에 추가하고 로컬 차트 메타데이터를 업데이트합니다.
helm repo add nextcloud https://nextcloud.github.io/helm/ helm repo update출력은 다음과 비슷합니다.
"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!⎈워크스테이션에서 커스텀
values.yaml파일을 만들어 Nextcloud Helm 차트의 기본 구성 매개변수를 재정의합니다.# 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 uploadsHelm을 사용하여 Nextcloud를 배포합니다.
helm install nextcloud nextcloud/nextcloud \ --namespace nextcloud \ --values values.yaml출력은 다음과 비슷합니다.
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)Nextcloud 포드가
Running상태이고 서비스가nextcloud네임스페이스에 있는지 확인합니다.kubectl get pod -n nextcloud kubectl get svc -n nextcloud출력은 다음과 비슷합니다.
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 25mnextcloud네임스페이스에 Nextcloud MCP 서버를 배포하려면 워크스테이션에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-mcpnextcloud-mcp.yaml매니페스트를 적용합니다.kubectl apply -f nextcloud-mcp.yaml출력은 다음과 비슷합니다.
secret/nextcloud-mcp-secret created deployment.apps/nextcloud-mcp-server created service/nextcloud-mcp-service created포드와 서비스가
nextcloud네임스페이스에서 실행 중인지 확인합니다.kubectl get svc -n nextcloud kubectl get pod -n nextcloud출력은 다음과 비슷합니다.
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 4m11sURL로 Nextcloud MCP 도구를 통합하려면 kagent UI로 이동하여 다음 값으로 도구 서버를 등록합니다.
- URL:
http://nextcloud-mcp-service.nextcloud.svc.cluster.local:8000/mcp - 프로토콜:
STREAMABLE_HTTP - Namespace(네임스페이스):
kagent - 클러스터: 클러스터 이름(예:
mgmt-cluster)
RemoteMCPServer리소스가kagent네임스페이스에서 허용되는지 확인합니다.kubectl get remotemcpserver -n kagent출력은 다음과 비슷합니다.
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- URL:
워크스테이션에서 Nextcloud에 액세스하려면 로컬 포트
8080를nextcloud서비스로 전달합니다(외부 URL을 구성한 경우 이 단계 건너뛰기).kubectl port-forward -n nextcloud svc/nextcloud 8080:8080 &출력은 다음과 비슷합니다.
Forwarding from 127.0.0.1:8080 -> 80 Forwarding from [::1]:8080 -> 80
배포 확인 및 Nextcloud 에이전트 구성
워크스테이션 브라우저에서 http://localhost:8080을 열어 Nextcloud 대시보드를 확인합니다.
파일 뷰에는 Nextcloud에 저장된 디렉터리와 파일이 표시됩니다.
kagent UI에서 대시보드 페이지에는 연결된 클러스터와 배포된 에이전트가 표시됩니다.
도구 서버 페이지에는 Nextcloud 애플리케이션에 대해 MCP를 통해 검색된 도구가 나열됩니다.
도구 페이지에는 상담사가 사용할 수 있는 Nextcloud 도구 모음이 표시됩니다.
kagent UI에서 nextcloud 에이전트를 만들려면 기본 정보에 에이전트 이름, 클러스터, 네임스페이스, 설명을 입력합니다.
동작 및 모델 설정에서 Gemma 4 모델을 선택하고 에이전트의 시스템 요청 사항을 입력합니다.
도구 및 에이전트에서 에이전트의 Nextcloud MCP 도구를 선택한 후 에이전트 만들기를 클릭합니다.
에이전트 페이지에 nextcloud 에이전트가 Ready 상태로 표시됩니다.
Nextcloud 애플리케이션에서 디렉터리와 파일을 나열하도록 Nextcloud 에이전트에 프롬프트를 표시할 수 있습니다.
Nextcloud 에이전트에게 파일 콘텐츠를 영어에서 프랑스어로 번역하고 음역하도록 프롬프트를 표시할 수도 있습니다.
