A GroupDocs MCP 서버를 사용하면 Claude Desktop, Claude Code, Cursor, GitHub Copilot 및 기타 MCP 클라이언트가 로컬에서 문서를 작업할 수 있습니다. 클라이언트가 서버를 자체 머신의 자식 프로세스로 시작하고, 파일은 사용자가 선택한 폴더에서 읽고 씁니다. 전체 아키텍처와 보안 모델은 각 제품의 온프레미스 페이지에 문서화되어 있으며, 예를 들어 Running GroupDocs MCP servers on-premise: architecture and security model를 참고하십시오. 이 게시물은 AI 에이전트를 문서에 연결하는 세 가지 일반적인 방법을 비교하고, 무엇이 머신을 떠나고 무엇이 떠나지 않는지 설명합니다.

AI 에이전트를 문서에 연결할 수 있는 아키텍처는 무엇인가요?

세 가지가 있습니다. 보안 검토자가 먼저 묻는 질문이 다릅니다: 문서는 어디로 가나요?

클라우드 업로드 호스티드 API 로컬 MCP 서버
작동 방식 어시스턴트 또는 플러그인이 파일을 공급업체 서비스에 업로드 코드 또는 에이전트가 파일을 포함한 공급업체 REST API를 호출 AI 클라이언트가 머신에서 서버 프로세스를 시작
문서가 이동하는 위치 제3자 클라우드 제3자 클라우드 또는 자체 테넌트 없음: 로컬 폴더에서 읽고 씀
네트워크 표면 공급업체로의 아웃바운드 공급업체로의 아웃바운드 stdio만; 라이선스 파일이 있는 경우 메터링 라이선스로는 텔레메트리(문서 내용 없음)만 전송
인바운드 포트 해당 없음 해당 없음 없음
에어갭 사용 불가능 보통 불가능; 공급업체 배포 옵션에 따라 다름 라이선스 파일이 있으면 가능
실행 주체 공급업체 공급업체 AI 클라이언트의 일부인 사용자가 직접

세 번째 열이 GroupDocs MCP 서버가 구현하는 방식입니다. 이 글의 나머지 부분에서는 작동 방식과 한계에 대해 다룹니다.

로컬 MCP 서버의 데이터 흐름은 어떻게 보이나요?

AI 클라이언트가 서버를 자식 프로세스로 실행하고 JSON‑RPC를 사용해 표준 입력·출력으로 통신합니다. 서버는 네트워크 포트를 열지 않으며, 라이선스 파일이 있는 경우 외부 연결도 하지 않습니다.

+--------------+          +--------------------+         +------------------+
|  AI client   |  stdio   | MCP server process | reads / | local filesystem |
| (Claude,     | <------> | (GroupDocs engine) | <-----> | storage / output |
|  Cursor, ..) | JSON-RPC |   child process    |  writes |     folders      |
+--------------+          +--------------------+         +------------------+
       |
       | prompts and quoted fragments only
       v
+--------------------+
|   model provider   |  (cloud, or a local model inside your network)
+--------------------+

보안 검토자는 다음 네 가지 확인 가능한 진술을 가집니다:

  • 전송: 자식 프로세스로의 표준 입력·출력. 방화벽에 열어야 할 것이 없고 노출할 것도 없습니다.
  • 인바운드 포트: 없음.
  • 텔레메트리: 없음. 문서 엔진이 프로세스 내에서 실행됩니다.
  • 네트워크 사용: 설치 시에만 nuget.org에서 패키지를 가져오거나 ghcr.io에서 이미지를 끌어옵니다. 런타임에서는 외부 호출을 하지 않으며, 아래에 설명된 라이선스 예외만 존재합니다.

신뢰 대신 직접 확인할 수 있습니다: 작업을 실행하고 리스닝 소켓 및 아웃바운드 연결을 감시하십시오.

에이전트가 문서를 처리할 때 머신을 떠나는 것은 무엇인가요?

문서는 머신을 떠나지 않습니다. 프롬프트와 인용된 조각만 떠납니다.

AI 클라이언트 뒤의 모델은 대화를 봅니다. 모델이 클라우드에 호스팅된 경우, 사용자의 지시 텍스트가 모델 제공자에게 전달되고, 에이전트가 인용하는 모든 내용도 전달됩니다. 두 가지 예시:

  • 비교 후, 에이전트가 결제 조건이 30일에서 45일로 변경되었다고 보고합니다. 해당 문장은 대화의 일부이며 제공자에게 전송됩니다.
  • 추출 후, 에이전트가 청구서 총액을 보고합니다. 파일 자체는 이동하지 않았지만 그 값은 전송되었습니다.

유용한 습관은 프롬프트를 답변이 적은 내용을 담도록 구성하는 것입니다. 예를 들어 총액을 묻는 대신 “총액이 임계값을 초과하는 파일은 어떤 것이 있나요?”라고 물어보세요. 민감한 데이터셋의 경우 서버를 로컬에 호스팅된 모델과 짝지어 사용하십시오. 그러면 전체 루프(클라이언트, 모델, 서버, 파일)가 네트워크 내부에 머무릅니다.

로컬 서버에 인터넷 접속이 필요할까요?

처리 자체에는 필요하지 않습니다. 라이선스 모드에 따라 다릅니다:

  • 라이선스 파일: 로컬 프로세스가 로컬 디스크에서 읽습니다. 완전히 오프라인으로 동작하며, 에어갭 네트워크에 적합한 선택입니다.
  • 메터링(사용량 기반): 서버가 사용량을 GroupDocs에 보고하므로 아웃바운드 트래픽이 필요합니다. 보고서에는 문서 내용이 포함되지 않지만, 연결 자체는 방화벽에서 허용되어야 합니다.

메터링 키와 라이선스 파일을 모두 설정하면 메터링 키가 우선합니다. 키는 커밋된 설정보다 환경 변수에 보관하십시오. 각 제품의 라이선스 페이지에 설정 방법이 설명되어 있으며, get_license_status 도구가 현재 모드를 보고합니다.

Docker로 경계 내부에서 서버를 실행하려면 어떻게 해야 하나요?

Docker 이미지가 플랫폼 팀에게 더 쉬운 옵션인 경우가 많습니다: 네이티브 종속성을 포함한 하나의 이미지, 호스트에 SDK가 필요 없으며, 마운트한 폴더만 접근하도록 경계를 제한합니다. 각 제품마다 ghcr.io/groupdocs-<product>/<product>-net-mcp라는 이름의 이미지가 있습니다. 아래 명령은 하나의 제품에 대한 형태를 보여주며, 자리표시자를 교체하면 됩니다.

docker run --rm -i \
  -v /srv/documents:/data \
  -v /srv/licenses:/license:ro \
  -e GROUPDOCS_MCP_STORAGE_PATH=/data \
  -e GROUPDOCS_LICENSE_PATH=/license/GroupDocs.<Product>.lic \
  ghcr.io/groupdocs-<product>/<product>-net-mcp:<tag>
  • 태그 고정. 빠른 시작 명령은 :latest를 사용하지만, 프로덕션에서는 테스트한 버전에 태그를 고정해 재빌드가 실행 중인 워크플로우의 동작을 바꾸지 못하도록 합니다.
  • 마운트를 의도적으로. 컨테이너는 제공한 폴더만 볼 수 있어, 사용자로 실행되는 프로세스보다 더 엄격한 경계를 제공합니다.
  • 라이선스를 읽기 전용으로 마운트.
  • 에어갭 구간: 이미지를 미리 풀하거나 NuGet 패키지를 미리 캐시하고, 버전을 고정합니다.

AI 클라이언트는 이 docker run 명령을 MCP 구성의 서버 명령으로 실행하므로, 컨테이너가 위 다이어그램의 자식 프로세스가 됩니다. 문서에서는 이미지가 멀티 아키( linux/amd64 및 linux/arm64)라고 설명합니다.

로컬 MCP 서버가 규제 산업에 적합한가요?

문서를 제3자 프로세서에 전송한다는 가장 큰 프라이버시 검토 질문을 제거합니다. 문서 업로드를 금지하는 정책을 가진 법무, 금융, 의료 및 공공 부문의 팀은 HIPAA 또는 GDPR 중심 워크플로우의 빌딩 블록으로 사용할 수 있습니다. 이는 아키텍처 적합성만을 설명합니다. GroupDocs MCP 서버는 어떤 규제에도 인증되지 않았으며, 귀하의 의무는 함께 사용하는 모델, 라이선스 모드 및 자체 제어에 따라 달라집니다.

이 모델의 한계는 무엇인가요?

  • 하나의 서버는 하나의 클라이언트 프로세스만 서비스합니다. stdio 서버는 한 클라이언트가 한 머신에서 시작합니다. 다중 사용자 서비스가 아닙니다. 공유 서비스를 원한다면 여러 MCP 서버를 실행하는 대신 GroupDocs 라이브러리 앞에 자체 서비스를 두세요.
  • 메터링 라이선스는 아웃바운드가 필요합니다. 사용량 보고서는 위에서 설명한 대로 외부로 전송됩니다. 네트워크를 차단해야 한다면 라이선스 파일을 선택하십시오.
  • 프롬프트는 로컬 모델을 사용하지 않는 한 모델 제공자에게 전달됩니다.
  • 평가 모드에는 제한이 있습니다. 라이선스가 없으면 서버는 제품별 제한이 있는 평가 모드로 실행됩니다. 예를 들어 Comparison 서버는 처음 2페이지만 비교하고 결과에 워터마크를 삽입합니다. 먼저 get_license_status를 호출하고 제품의 라이선스 페이지를 읽으세요.
  • Parser와 Search는 Docker 이미지로만 제공됩니다. GroupDocs.Parser.Mcp와 GroupDocs.Search.Mcp는 NuGet 패키지가 없으므로 위 Docker 경로가 유일한 방법입니다. Linux 호스트에서는 --user "$(id -u):$(id -g)" 옵션으로 컨테이너를 실행해 마운트한 폴더에 쓸 수 있게 하세요.
  • 플랫폼 예외. 현재 Linux(및 Docker 이미지)에서는 두 가지 PDF 전용 작업이 실패합니다. 이는 PDF 엔진의 이미지 처리가 System.Drawing.Common에 의존하고, .NET이 Windows에서만 지원하기 때문입니다: GroupDocs.Annotation.Mcp의 generate_pages_preview(PDF 파일, Word 문서는 정상 렌더링)와 GroupDocs.Redaction.Mcp의 redact_image_area, erase_metadata(PDF 파일, redact_text는 PDF에서, 세 가지 모두는 Word 문서에서 정상 작동). Windows에서 dnx로 실행하십시오; 제품 게시물을 참고하세요.

FAQ

MCP가 민감한 문서에 안전한가요?
GroupDocs MCP 서버를 사용하면 문서는 stdio를 통해 로컬 머신 내 프로세스에서 처리되며, 리스닝 포트와 텔레메트리가 없습니다. 남은 평가 대상은 AI 클라이언트가 사용하는 모델이며, 프롬프트와 인용된 조각이 그곳으로 전송됩니다.

Claude 도구를 클라우드에 데이터를 보내지 않고 실행할 수 있나요?
문서는 어느 경우든 로컬에 남습니다. 프롬프트도 로컬에 유지하려면 로컬에 호스팅된 모델을 지원하는 클라이언트를 사용하면 대화의 어느 부분도 네트워크를 떠나지 않습니다.

MCP 서버가 보내는 데이터는 무엇인가요?
라이선스 파일을 사용할 경우 런타임에 GroupDocs MCP 서버는 네트워크를 통해 아무것도 전송하지 않습니다. 메터링 라이선스에서는 사용량 보고서만 GroupDocs에 전송하며, 문서 내용은 절대 전송되지 않습니다.

제품별: 문서의 온프레미스 페이지

각 페이지는 해당 제품에 대한 명령과 함께 동일한 아키텍처를 다룹니다. 이는 보안 검토를 위한 정식 참고 자료입니다.

제품별: 블로그에서 시작하기

각 제품마다 일련의 게시물이 있습니다—대부분 4개, Search는 6개. 첫 번째 게시물이 패턴을 설명하고, 나머지는 이를 적용합니다.