OfficeAgent.NET은 AI 에이전트가 유형화되고 검증된 변경 계획을 통해 실제 Word 문서를 편집할 수 있는 도구를 제공하는 MCP 서버를 제공합니다. 몇 가지 명령어로 로컬에서 시작할 수 있습니다:

dotnet tool install --global OfficeAgent.Mcp
officeagent-mcp --stdio

이는 Claude Code 또는 Codex와 같이 로컬에서 실행되는 에이전트와 함께 사용하려는 경우에 완벽합니다. 하지만 로컬 환경만으로는 항상 충분하지는 않습니다. 다음과 같은 경우에는 호스팅이 필요합니다:

• 호스팅된 에이전트 (Hosted agents). Copilot Studio 및 Microsoft 365 Copilot은 공개 HTTPS 엔드포인트를 통한 스트리밍 가능한 HTTP를 통해서만 MCP를 소비할 수 있습니다.
• 무인 자동화 (Unattended automation). 일정 또는 이벤트에 따라 실행되는 문서 워크플로에는 노트북이 아닌 어딘가에서 실행되는 서버가 필요합니다.
• 팀을 위한 공유 서버 (Shared server for a team). 모든 사용자가 로컬 설정에 SharePoint 자격 증명을 보유하는 대신, 하나의 호스팅된 인스턴스가 이를 한 번만 보유하고 클라이언트는 URL을 받게 됩니다.

이 기사는 해당 엔드포인트를 Azure Container Apps에 배포하고, 이를 SharePoint 문서 저장소에 연결하며, 내장된 인증(Easy Auth)으로 보안을 강화하는 방법을 보여줍니다.

시작하기 전에 필요한 사항

배포를 시작하기 전에 다음 사항을 준비해야 합니다:

1. 컨테이너 이미지 (The container image). 이 기사에서는 GitHub Container Registry에서 사용할 수 있는 사전 빌드된 이미지를 사용합니다:

ghcr.io/ilia-sokolov/officeagent-mcp:latest

자유롭게 사용하십시오. 정책상 자체 레지스트리가 필요한 경우, 저장소의 Dockerfile에서 이미지를 빌드하여 레지스트리에 푸시한 후 참조를 교체하면 됩니다. 단계는 동일합니다.

2. 테넌트 ID (Your tenant id). Entra admin center의 개요 (Overview) 페이지에서 확인할 수 있습니다.

3. SharePoint 액세스를 위한 앱 등록 (An app registration for SharePoint access). OfficeAgent은 프로바이더 (providers)를 통해 작동합니다. 즉, 에이전트가 접근할 수 있는 문서 저장소를 정의합니다. 파일 시스템 프로바이더와 SharePoint 프로바이더를 제공하며, 호스팅된 서버의 경우 SharePoint가 가장 좋은 옵션입니다. 서버가 문서에 접근하려면 자체적인 ID가 필요합니다:

1. Entra 관리 센터(Entra admin center)에서 **앱 등록 (App registrations)**을 열고 새 등록을 생성합니다. 이름을 지정하고(예: officeagent-sharepoint), 기본 설정을 유지한 채 등록합니다. **애플리케이션(클라이언트) ID (Application (client) ID)**를 복사합니다.
2. 앱의 인증서 및 비밀 값 (Certificates & secrets) 페이지에서 새 클라이언트 비밀 값(client secret)을 생성합니다. 생성 즉시 **값 (Value)**을 복사하세요. 이 값은 한 번만 표시됩니다.
3. API 권한 (API permissions) 아래에서 권한을 추가합니다: Microsoft Graph를 선택한 다음, **애플리케이션 권한 (Application permissions)**을 선택합니다. Sites.Selected (최소 권한 원칙 - 앱이 명시적으로 허용된 사이트에만 접근 가능) 또는 Sites.ReadWrite.All (더 간단하지만 테넌트 내의 모든 사이트에 접근 가능)를 추가합니다. 그 다음 관리자 동의(admin consent)를 부여합니다.
4. Sites.Selected를 선택한 경우, PnP PowerShell 등을 사용하여 특정 사이트 또는 사이트들에 대해 앱에 Write 권한을 부여합니다:

Grant-PnPAzureADAppSitePermission `
    -AppId "<app-client-id>" `
    -DisplayName "<app-name>" `
...

Azure 포털에 MCP 배포하기

앱 생성:

1. Azure 포털에서 새 Container App 리소스를 생성합니다. 리소스 그룹을 선택하고, 앱 이름(예: officeagent-mcp)을 지정한 뒤, 새로운 Container Apps 환경을 생성하도록 합니다.
2. 컨테이너 (Container) 탭에서: Quickstart 이미지 사용 (Use quickstart image) 체크를 해제합니다. 컨테이너 이름을 지정하고(예: officeagent-mcp), **이미지 소스 (Image source)**를 _Docker Hub 또는 기타 레지스트리 (Docker Hub or other registries)_로, **이미지 유형 (Image type)**을 _공개 (Public)_로 설정합니다. **레지스트리 로그인 서버 (Registry login server)**를 ghcr.io로 설정하고, **이미지 및 태그 (Image and tag)**를 ilia-sokolov/officeagent-mcp:latest로 설정합니다.
3. 환경 변수 (Environment variables) 그리드는 동일한 탭의 하단에 있습니다. 아래 표에 있는 6개의 변수를 추가합니다.

이 값들은 서버의 SharePoint 연결을 구성합니다:

이 문서에서는 appOnly 방식을 설정합니다. 즉, 서버가 모든 호출자에 대해 하나의 애플리케이션 ID (application identity)로 동작합니다. 또한 이 프로바이더(provider)는 서버가 로그인한 사용자를 대신하여 동작하고 사용자별로 SharePoint 권한이 적용되는 on-behalf-of 흐름도 지원합니다. 해당 방식이 필요한 경우 배포 가이드 (deployment guide)를 참조하세요.

1. Ingress 탭에서: ingress를 활성화하고, accept traffic from anywhere를 선택하며, 대상 포트(target port)를 8080으로 설정합니다.
2. 앱을 생성합니다. 확인을 위해 생성된 컨테이너 앱의 URL인 https://<app-url>/healthz를 엽니다. 여기서 <app-url>은 생성된 컨테이너 앱의 URL입니다. {"status":"ok",...}가 반환되어야 합니다.

엔드포인트(endpoint)를 이제 사용할 수 있지만, 누구나 호출할 수 있는 상태입니다. 인증(authentication)을 활성화하여 이 문제를 해결해 보겠습니다.

Easy Auth 켜기:

1. 생성된 Container App에서 Authentication 페이지(Security 항목 아래에 있습니다)를 열고 Add identity provider를 클릭합니다. Microsoft를 선택합니다.
2. 양식을 통해 앱 등록(app registration)이 자동으로 생성되도록 합니다. App registration type을 _Create new app registration_로 유지하고, 이름(예: officeagent-easyauth)을 지정합니다. Additional checks 항목에서 Client application requirement를 _Allow requests from any application_로 설정합니다. 마법사가 등록, 시크릿(secret), 그리고 연결 설정을 한 번에 완료합니다.
3. Restrict access를 _Require authentication_로, Unauthenticated requests를 _HTTP 401 Unauthorized_로 설정합니다. 이것은 웹사이트가 아니라 API이므로, 로그인 리다이렉트(login redirect)가 발생하면 MCP 클라이언트가 혼란을 겪을 수 있습니다.
4. 저장합니다. 이제 https://<app-url>/healthz는 401을 반환합니다. 클라이언트는 Easy Auth 앱을 위한 Entra 베어러 토큰(bearer token)을 전송해야 합니다. 다음 스크립트를 사용하여 이를 확인할 수 있습니다:

TOKEN=$(az account get-access-token --resource api://<easyauth-client-id> --query accessToken -o tsv)
curl -H "Authorization: Bearer $TOKEN" https://<app-url>/healthz

다음 단계

이제 클라이언트와 함께 MCP 서버를 사용할 수 있습니다. 다음 기사에서는 이를 Copilot Studio 에이전트에 연결하는 방법을 설명하겠습니다.

이 기사가 유용했다면 댓글로 알려주세요. GitHub에서 별(star)을 눌러주시면 다른 개발자들이 이 프로젝트를 찾는 데 큰 도움이 됩니다.