보안·권한
Microsoft Purview(MIP) 직접 연결
민감도 레이블로 보호된 문서를, 올린 사람의 권한으로만 AI 가 읽게 합니다.
대상: 회사의 Microsoft 365 관리자 · 커넥터 운영자 선행 조건: 커넥터 v0.2.19 이상 설치 완료 (Connector 설치 가이드) · 서버 사양은 커넥터 서버 권장 사양 함께 보실 문서: 문서 보안(DRM) 연동 가이드 — 사내 게이트웨이를 거쳐 여는 방식
이 기능이 하는 일
Microsoft Purview 민감도 레이블로 보호된 문서를 웍스AI 에 올리면, 문서를 올린 사람에게 그 문서를 꺼내 쓸 권한이 있을 때만 회사 안에서 풀어 AI 가 읽게 합니다. 게이트웨이 없이 Microsoft 365 테넌트에 직접 연결합니다.
웍스AI 에 문서 업로드
→ MCP Hub (지나가기만 함, 저장 안 함)
→ 회사 안의 커넥터
→ 같은 서버의 MIP 사이드카가 레이블과 권한을 확인하고 풀어 줌
→ 풀린 문서를 웍스AI 로 돌려보냄
언제 여는지 — 아래 두 가지를 모두 만족할 때만 엽니다.
- 문서의 보안 등급(레이블)이 Studio 에서 회사가 열어도 된다고 고른 등급입니다.
- 문서를 올린 사람이 그 문서에 내용을 꺼낼 수 있는 권한을 가지고 있습니다.
- 권한:
EXTRACT(복사) ·EXPORT(다른 이름으로 저장) ·OWNER(소유자) 중 하나 - 역할로 권한을 준 문서라면: 공동 작성자(Co-Author) · 공동 소유자(Co-Owner)
- 본인에게 직접 준 권한, 본인이 속한 그룹에 준 권한, 회사 전체에 준 권한 모두 인정합니다.
- 보기(View)만 가능한 사람이 올린 문서는 열지 않습니다. AI 에 올리는 일은 내용을 꺼내 쓰는 일이기 때문입니다.
- 권한:
| 하는 일 | 하지 않는 일 |
|---|---|
| 올린 사람에게 권한이 있는 보호 문서를 풀어 AI 가 읽게 하기 | 회사 문서함을 뒤져 문서를 가져오기 |
| 회사가 고른 보안 등급의 문서만 열기 | 올린 사람에게 없는 권한으로 문서 열기 |
| 누가 어떤 형식의 문서를 열었는지 기록 | 파일 이름 · 문서 내용을 MCP Hub 에 저장하기 |
- Microsoft 365 접속 정보(테넌트 ID · 클라이언트 ID · 클라이언트 암호)는 회사 서버의 사이드카에만 둡니다. MCP Hub 와 Studio 는 이 값을 받지도, 저장하지도 않습니다.
- 풀린 문서는 사이드카의 디스크에 남지 않습니다. 작업 폴더를 메모리에만 두고, 응답을 보낸 직후 지웁니다.
- MCP Hub 에는 문서 내용과 파일 이름이 저장되지 않습니다. 사용 기록에는 시각 · 사용자 · 형식 · 크기 · 보안 등급 · 결과만 남습니다.
- 풀린 문서를 웍스AI 가 얼마나 보관하는지는 웍스AI 의 업로드 문서 보관 정책을 따릅니다.
- AI 가 만든 파일을 회사 레이블로 암호화해 내려보내는 기능은 MIP 직접 연결에서 아직 지원하지 않습니다.
준비물
| 준비물 | 설명 |
|---|---|
| Microsoft 365 테넌트 | 암호화를 적용하는 민감도 레이블(레이블 설정의 "액세스 제어")을 쓰고 있어야 합니다 |
| 라이선스 | 민감도 레이블 보호가 포함된 라이선스 (예: Microsoft 365 E5 · E5 Information Protection, Azure Information Protection P1/P2) |
| 관리자 계정 | Microsoft 365 전역 관리자 — 앱 등록의 관리자 동의와 1-4 의 PowerShell 단계에 필요합니다 |
| 커넥터 서버 | 커넥터가 Docker 로 돌고 있는 Linux 서버 (x86_64 / amd64 만 지원). ARM 서버에서는 사이드카가 실행되지 않습니다 |
| Windows PC | 1-4 단계 한 번에만 필요합니다 (Windows PowerShell 5.1) |
| 기능 열기 | 문서 보안은 별도 도입이 필요합니다. Studio 문서 보안 화면의 [도입 문의] 로 신청해 주시면 회사에 MIP 직접 연결을 열어 드립니다 |
웍스AI 에 로그인하는 이메일이 Microsoft 365 계정의 이메일과 같아야 합니다. 다르면 권한을 확인할 수 없어 문서를 열지 않습니다.
네트워크 · 방화벽
커넥터와 사이드카는 밖에서 들어오는 연결을 받지 않습니다. 사이드카 포트(8080)는 서버 밖으로 열지 않습니다. 아래 나가는 길만 열어 주시면 됩니다. 모두 443 (HTTPS) 입니다.
| 출발 | 도착 | 용도 |
|---|---|---|
| 커넥터 서버 | mcp-hub.wrks.ai | 웍스AI 와의 연결 (설치 가이드와 같습니다) |
| 커넥터 서버 | ghcr.io | 커넥터 · 사이드카 이미지 받기 (설치 · 업데이트 때) |
| 사이드카 | login.microsoftonline.com | Microsoft 365 로그인 (앱 인증) |
| 사이드카 | dataservice.protection.outlook.com | 민감도 레이블 정책 받기 |
| 사이드카 | substrate.office.com | 민감도 레이블 정책 받기 |
| 사이드카 | graph.microsoft.com | 문서 권한을 받은 그룹에 올린 사람이 속하는지 확인 |
| 사이드카 | *.aadrm.com · *.azurerms.com | 보호된 문서를 열 권한 받기 (Rights Management) |
| 사이드카 | mobile.events.data.microsoft.com | Microsoft SDK 진단 정보 전송 |
- 사이드카는 커넥터 서버 안에서 돌므로, 실제로는 커넥터 서버에서 위 주소로 나가는 길을 열어 주시면 됩니다.
- 주소 단위로 막는 프록시나 방화벽을 쓰신다면 Microsoft 가 공개하는 Microsoft 365 URL 및 IP 주소 범위 의 Purview Information Protection 항목도 함께 확인해 주세요.
1. Microsoft 365 준비
1-1. 문서 암호화 서비스(Rights Management)가 켜져 있는지 확인
암호화 레이블을 이미 쓰고 계시면 대부분 켜져 있습니다. Purview 에서 암호화 레이블을 만들 때 "Rights Management is not active for the tenant" 같은 안내가 나오면 꺼져 있는 것입니다. 1-4 의 PowerShell 에서 Enable-AipService 로 켤 수 있습니다.
1-2. 앱 등록
사이드카가 Microsoft 365 에 로그인할 때 쓰는 앱을 만듭니다.
-
Microsoft Entra 관리 센터 → 애플리케이션 → 앱 등록 → 새 등록
-
이름은 알아보기 쉽게 적습니다 (예:
WRKS AI 문서 보안). -
지원되는 계정 유형: "이 조직 디렉터리의 계정만(단일 테넌트)"
-
리디렉션 URI: 비워 둡니다.
-
등록하면 나오는 개요 화면에서 두 값을 적어 둡니다.
화면에 보이는 이름 넣을 곳 애플리케이션(클라이언트) ID MIP_CLIENT_ID디렉터리(테넌트) ID MIP_TENANT_ID -
인증서 및 암호 → 클라이언트 암호 → 새 클라이언트 암호 를 만듭니다.
- 만든 직후 보이는 값(Value) 을 바로 복사해
MIP_CLIENT_SECRET에 넣습니다. 옆의 "비밀 ID(Secret ID)" 가 아닙니다. 값은 이 화면을 벗어나면 다시 볼 수 없습니다. - 만료 기간은 짧게 잡고, 만료 전에 새 암호로 바꾸도록 일정을 등록해 두시길 권합니다. 암호가 만료되면 사이드카가 Microsoft 365 에 로그인하지 못해 문서를 열 수 없고, 연결 확인의 "Microsoft 365" 항목이 로그인 실패로 표시됩니다.
- 만든 직후 보이는 값(Value) 을 바로 복사해
1-3. API 권한
앱 등록 화면의 API 권한 → 권한 추가 에서 아래 네 가지를 넣습니다. 모두 "애플리케이션 권한" 으로 넣어야 합니다 ("위임된 권한" 이 아닙니다).
| API | 권한 | 쓰는 곳 |
|---|---|---|
| Azure Rights Management Services | Content.SuperUser | 보호된 문서를 풀기 |
| Microsoft Information Protection Sync Service | UnifiedPolicy.Tenant.Read | 회사의 민감도 레이블 목록 읽기 |
| Microsoft Graph | GroupMember.Read.All | 문서 권한에 적힌 그룹 찾기 |
| Microsoft Graph | User.ReadBasic.All | 올린 사람이 그 그룹에 속하는지 확인 |
- Azure Rights Management Services 와 Microsoft Graph 는 "Microsoft API" 탭에, Microsoft Information Protection Sync Service 는 "내 조직에서 사용하는 API" 탭에서 이름으로 찾으시면 됩니다.
- 네 가지를 넣은 뒤 "<회사 이름>에 대한 관리자 동의 허용" 을 누르고, 네 줄 모두 상태에 초록색 확인 표시가 붙었는지 봅니다.
Graph 권한 두 개가 빠지면 그룹에 권한을 준 문서는 그 그룹에 속한 사람이 올려도 항상 열리지 않습니다. 사용자에게 직접 권한을 준 문서는 열리기 때문에 빠진 것을 알아채기 어렵습니다. 연결 확인의 "그룹 확인" 항목이 이것을 확인합니다.
자주 하는 실수
- 권한을 "위임된 권한" 으로 넣었습니다 → 지우고 "애플리케이션 권한" 으로 다시 넣어 주세요.
- 권한을 나중에 하나 더 넣고 관리자 동의를 다시 누르지 않았습니다 → 권한을 바꿀 때마다 관리자 동의를 다시 눌러 주세요.
1-4. 슈퍼유저 등록 (Windows PowerShell)
왜 필요한가 — 보호된 문서는 원래 권한을 받은 사람만 풀 수 있습니다. 사이드카는 회사를 대신해 문서를 풀어야 하므로, 1-2 에서 만든 앱을 회사의 "슈퍼유저" 로 등록합니다. 슈퍼유저로 등록해도 사이드카는 올린 사람에게 권한이 있고 회사가 허용한 등급일 때만 문서를 엽니다.
Windows PC 에서 Windows PowerShell 5.1 을 관리자 권한으로 엽니다. PowerShell 7 과 macOS 에서는 이 모듈이 동작하지 않습니다.
# 모듈 설치 (처음 한 번). 저장소를 믿을지 물으면 Y 로 답합니다.
Install-Module -Name AIPService -Scope CurrentUser
Import-Module AIPService
# 전역 관리자 계정으로 로그인합니다
Connect-AipService
# 문서 암호화 서비스가 켜져 있는지 확인 — Enabled 가 나와야 합니다
Get-AipService
# Disabled 라면 켭니다
Enable-AipService
# 슈퍼유저 기능을 켜고, 1-2 에서 만든 앱을 슈퍼유저로 등록합니다
Enable-AipServiceSuperUserFeature
Add-AipServiceSuperUser -ServicePrincipalId "<애플리케이션(클라이언트) ID>"
# 등록됐는지 확인 — 목록에 위 ID 가 보여야 합니다
Get-AipServiceSuperUser
Disconnect-AipService
자주 하는 실수:
-ServicePrincipalId에 개체 ID(Object ID) 를 넣었습니다. 앱 등록 개요 화면의 애플리케이션(클라이언트) ID 를 넣어야 합니다.
슈퍼유저 등록은 연결 확인에서 확인되지 않습니다. 4장의 시험 문서로 확인해 주세요.
1-5. 레이블 게시 확인
사이드카는 게시된 민감도 레이블만 읽습니다. Microsoft Purview 포털의 정보 보호 → 레이블 정책 에서 쓰시는 레이블이 정책으로 게시되어 있는지 확인해 주세요. 특정 그룹에만 게시한 정책이어도 괜찮습니다.
2. 사이드카 설치 — 설치 스크립트
사이드카는 커넥터 옆에서 도는 작은 컨테이너입니다. 커넥터만 사이드카를 부를 수 있고, 밖에서는 접속할 수 없습니다. 1장을 마친 뒤 커넥터 서버에서 아래 두 줄을 실행합니다. 같은 명령이 Studio 문서 보안 화면의 안내 상자에도 있습니다.
curl -fsSLO https://mcp-studio.wrks.ai/install/install-drm-mip.sh
sudo bash install-drm-mip.sh
묻는 것은 세 가지입니다 — 1-2 에서 적어 둔 값입니다.
| 질문 | 넣을 것 |
|---|---|
| 디렉터리(테넌트) ID | 앱 등록 개요 화면의 「디렉터리(테넌트) ID」 |
| 애플리케이션(클라이언트) ID | 앱 등록 개요 화면의 「애플리케이션(클라이언트) ID」 |
| 클라이언트 암호 값 | 1-2 에서 만든 클라이언트 암호의 값(Value). 입력하는 동안 화면에 보이지 않습니다 |
스크립트가 하는 일 — 바꾸기 전에 할 일을 보여 드리고 y 를 받은 뒤 진행합니다.
- 커넥터 서버가 x86_64 인지, 커넥터가 실행 중인지 확인합니다. 틀린 곳이 있으면 고칠 곳을 알려 드리고 아무것도 바꾸지 않습니다.
- 사이드카 이미지를 받고 설정 파일
/etc/mcp-hub/drm-mip.env를 만듭니다(관리자만 읽기). 커넥터와 사이드카가 서로 확인할 토큰은 스크립트가 만듭니다. - 사이드카를 실행하고, 커넥터를 같은 docker 네트워크에 연결합니다. 사이드카 포트는 서버 밖으로 열지 않고, 풀린 문서는 메모리에만 둡니다.
- 커넥터 secrets 폴더의
drm.env에DRM_MIP_TOKEN을 넣고 커넥터를 다시 시작합니다(몇 초 동안 웍스AI 요청이 끊깁니다). 이 파일의 다른 줄은 건드리지 않습니다. - 커넥터에서 사이드카에 닿는지 확인하고 끝냅니다.
- 커넥터가 둘 이상인 서버에서는
--connector <커넥터 컨테이너 이름>을 붙여 주세요. - 커넥터는 실행 중인 컨테이너 중 커넥터 이미지(
ghcr.io/chain-partners/mcp-hub-connector)로 찾고, secrets 폴더는 그 컨테이너의/var/secrets연결에서 읽습니다. 찾지 못하면 부록 A 의 직접 설치를 따라 주세요. - Microsoft 365 접속 정보는 이 서버의 설정 파일에만 저장됩니다. 스크립트는 회사 밖으로 아무것도 보내지 않습니다.
- 1-4 의 슈퍼유저 등록은 스크립트가 하지 않습니다. Windows PowerShell 에서 한 번 해 주세요.
3. Studio 에서 연결 만들기
- 문서 보안 → DRM 연결 만들기
- Microsoft Purview (MIP) 직접 연결 을 고릅니다.
- 연결 이름 을 적고, 커넥터 는 2장(또는 부록 A)에서 사이드카를 설치한 서버의 커넥터를 고릅니다. 응답 대기 시간은 비워 두면 기본값(120000 밀리초 = 2분)을 씁니다.
- 연결 만들고 키 발급 을 누르면 연결 주소와 키가 나옵니다. 키는 이때 한 번만 보입니다. 웍스AI 관리자 화면의 문서 보안 연결에 두 값을 넣어 주세요.
3-1. 연결 확인
화면 위의 연결 확인 을 누릅니다. 위에서부터 차례로 확인하고, 실패한 항목에서 멈춥니다. 다섯 항목이 모두 통과해야 합니다.
| 항목 | 무엇을 확인하나 |
|---|---|
| 커넥터 | 커넥터가 켜져 있고 문서 보안을 지원하는 버전인지 |
| 설정 값 | 커넥터에 DRM_MIP_TOKEN 이 들어 있는지 |
| 사이드카 | 커넥터가 사이드카에 닿고, 토큰이 맞는지 |
| Microsoft 365 | 사이드카가 Microsoft 365 에 로그인해 레이블을 읽는지 |
| 그룹 확인 | Microsoft Graph 로 그룹 소속을 확인할 수 있는지 |
실패했을 때
| 화면 안내 | 고칠 곳 |
|---|---|
| 커넥터가 연결되어 있지 않습니다 / 문서 보안을 지원하지 않습니다 | 커넥터가 실행 중인지, v0.2.19 이상인지 확인해 주세요 |
| 커넥터에 DRM_MIP_TOKEN 값이 없습니다 | 설치 스크립트를 다시 실행해 주세요. 직접 설치하셨다면 A-3 의 secrets 파일에 DRM_MIP_TOKEN 을 넣고 커넥터를 다시 시작해 주세요 |
| 사이드카 토큰이 맞지 않습니다 | 커넥터의 DRM_MIP_TOKEN 과 사이드카의 MIP_SIDECAR_TOKEN 이 같은 값인지 확인해 주세요. 사이드카 설정 파일을 고쳤다면 설치 스크립트를 다시 실행합니다(직접 설치는 사이드카를 지우고 A-2 로) |
| 커넥터가 사이드카에 연결하지 못했습니다 | docker ps 로 사이드카가 떠 있는지 확인하고 설치 스크립트를 다시 실행해 주세요(직접 설치는 A-2 의 docker network connect, 다른 이름으로 실행했다면 DRM_MIP_URL) |
| 사이드카가 응답하지 않았습니다 | docker logs drm-mip 로 사이드카 상태를 확인해 주세요 |
| 사이드카에 Microsoft 365 접속 정보가 없습니다 | /etc/mcp-hub/drm-mip.env 의 MIP_TENANT_ID · MIP_CLIENT_ID · MIP_CLIENT_SECRET 를 확인하고 설치 스크립트를 다시 실행해 주세요 |
| 사이드카가 Microsoft 365 에 로그인하지 못했습니다 | 테넌트 ID · 클라이언트 ID · 클라이언트 암호 값이 맞는지, 암호가 만료되지 않았는지 확인해 주세요 (1-2) |
| 앱 등록의 API 권한과 관리자 동의를 확인해 주세요 | 1-3 의 권한이 "애플리케이션 권한" 인지, 관리자 동의에 초록색 확인 표시가 있는지 확인해 주세요 |
| Microsoft Purview 에 게시된 민감도 레이블이 없습니다 | 레이블을 만들고 레이블 정책으로 게시해 주세요 (1-5) |
| 문서 보호 라이선스가 없습니다 | 테넌트의 라이선스를 확인해 주세요 (준비물 표) |
| Microsoft Graph 권한 … 을 확인해 주세요 (그룹 확인) | 1-3 의 GroupMember.Read.All · User.ReadBasic.All 을 애플리케이션 권한으로 넣고 관리자 동의를 다시 눌러 주세요 |
사이드카 설정 파일(
drm-mip.env)을 고친 뒤에는docker restart로는 새 값이 반영되지 않습니다. 설치 스크립트를 다시 실행해 주세요(직접 설치는docker rm -f drm-mip뒤 A-2 의docker run).
3-2. 열어도 되는 보안 등급 고르기
보안 등급 탭 에서 열어도 되는 범위를 정하고 저장합니다. 정하기 전에는 보호된 문서를 하나도 열지 않습니다.
- 지정한 등급만 열기 — Microsoft Purview 에 게시된 레이블 목록이 나옵니다. 열어도 되는 레이블에 표시합니다. "암호화 없음" 이 붙은 레이블은 보호가 걸리지 않는 레이블입니다.
- 목록에 없는 등급 — 예전에 골라 두었는데 지금 Purview 목록에서 사라진 레이블입니다. 레이블을 지웠거나 게시를 멈춘 경우입니다. 더 쓰지 않으면 표시를 빼 주세요.
- 보안 등급과 관계없이 모두 열기 — 레이블과 상관없이 엽니다. 이때도 올린 사람의 권한은 그대로 확인합니다. 회사 보안 담당자의 승인을 받은 뒤 고르고, "보안 담당자의 승인을 받았습니다" 에 표시해야 저장됩니다.
- 레이블이 없는 문서는 고른 등급과 관계없이 그대로 통과합니다.
- "암호화 없음" 레이블이 붙은 문서도 그 레이블을 골라야 웍스AI 로 보냅니다. 풀 것이 없으므로 올린 사람의 권한은 따로 확인하지 않습니다.
3-3. 켜기
화면 위의 켜기 를 누릅니다. 이때부터 웍스AI 에서 올린 보호 문서를 엽니다.
4. 운영
시험 문서로 확인하기
켠 뒤 보호 문서를 하나 올려 보세요. 연결 확인은 레이블 목록까지만 확인하고, 1-4 의 슈퍼유저 등록은 실제 문서를 열 때 처음 확인됩니다.
- 열어도 되는 등급의 레이블이 붙은 문서를, 그 문서의 복사 권한이 있는 사람이 올립니다 → 사용 기록에 열림
- 같은 문서를 보기 권한만 있는 사람이 올립니다 → 올린 사람 권한 없음
1번에서 설정 오류 가 나오면 1-4 의 슈퍼유저 등록(특히 애플리케이션(클라이언트) ID 를 넣었는지)을 확인해 주세요.
사용 기록
사용 기록 탭 에서 누가 어떤 형식의 문서를 열었는지, 왜 못 열었는지 볼 수 있습니다.
| 결과 | 뜻 |
|---|---|
| 열림 | 회사가 고른 등급의 문서를 웍스AI 로 보냈습니다 (보호 문서는 풀어서) |
| 그대로 통과 | 레이블이 없는 문서라 그대로 보냈습니다 |
| 등급 제한 | 회사가 고르지 않은 보안 등급입니다 |
| 올린 사람 권한 없음 | 올린 사람에게 내용을 꺼낼 권한이 없습니다 (보기 권한만 있거나 권한 없음) |
| 다른 회사에서 보호한 문서 | 다른 Microsoft 365 테넌트에서 보호한 문서라 우리 회사에서 풀 수 없습니다 |
| 지원하지 않는 형식 | 아래 「지원 형식」 밖의 문서이거나 문서가 손상되었습니다 |
| 전자서명 PDF 는 열 수 없음 | 서명을 깨지 않고 풀 수 없습니다 |
| 설정 오류 | 슈퍼유저 등록 · API 권한 · 클라이언트 암호 만료 등 1장의 설정 문제 |
| 사이드카 연결 실패 / 응답 없음 / 오류 | 사이드카가 꺼졌거나 네트워크에서 빠졌습니다. 연결 확인을 눌러 보세요 |
| 파일이 너무 큼 | 100MB 를 넘는 문서입니다 |
그룹에 권한을 준 문서가 그 그룹 사람에게도 올린 사람 권한 없음 으로 나온다면, 연결 확인의 "그룹 확인" 항목과 1-3 의 Graph 권한 두 개를 확인해 주세요.
크기와 지원 형식
- 한 번에 올릴 수 있는 문서는 100MB 까지입니다 (암호화된 상태의 크기 기준).
- 지원 형식:
docx·xlsx·pptx·doc·xls·ppt·pdf·txt·csv, 그리고 보호되면서 확장자가 바뀐pfile·ptxt·ppdf·pjpg·ppng - 서버 사양은 커넥터 서버 권장 사양 을 참고해 주세요. 사이드카는 문서를 메모리에서 풀기 때문에 큰 문서를 자주 여신다면 메모리를 넉넉히 잡아 주세요.
키와 클라이언트 암호
- 키를 잃어버렸거나 새 나간 것 같으면 연결 설정 탭에서 새 키 발급. 이전 키는 즉시 쓸 수 없고, 웍스AI 에 새 키를 넣기 전까지 문서를 열 수 없습니다. 연결 주소는 바뀌지 않습니다.
- 클라이언트 암호를 바꿀 때 — 1-2 에서 새 클라이언트 암호를 만들고
sudo bash install-drm-mip.sh --new-secret를 실행해 새 값을 넣습니다. 토큰 · 커넥터 설정은 그대로이고 사이드카만 새 값으로 다시 뜹니다. 연결 확인이 통과하면 예전 암호를 지웁니다. 직접 설치하셨다면/etc/mcp-hub/drm-mip.env의MIP_CLIENT_SECRET을 바꾼 뒤 사이드카를 지우고 A-2 로 다시 실행합니다.
사이드카 업데이트
새 사이드카 버전이 나오면 설치 스크립트를 새로 받아 다시 실행합니다. 스크립트에는 그때의 안내 버전이 들어 있습니다.
curl -fsSLO https://mcp-studio.wrks.ai/install/install-drm-mip.sh
sudo bash install-drm-mip.sh
- 설정 파일과 커넥터 설정은 그대로 두고 사이드카만 새 버전으로 바꿉니다. 다시 묻지 않고, 커넥터도 다시 시작하지 않습니다.
- 사이드카에 직접 붙여 두신 실행 옵션 중 사내 프록시 · DNS · 메모리 · 작업 폴더 크기(추가 호스트 포함)은 새 사이드카에 그대로 이어받습니다. 진행 전 화면에 「이어받는 실행 옵션」 으로 보여 드립니다. 그 밖의 옵션은 이어받지 않으니 다시 붙여 주세요. 프록시를 설정 파일에 넣어 두셨다면 설정 파일 값을 씁니다.
- 새 사이드카가 실행되지 않거나 90초 안에 응답하지 않으면 지금 사이드카로 되돌리고 멈춥니다.
- 사이드카를 바꾸는 몇 초 동안 올라오는 보호 문서는 열리지 않습니다. 사용이 적은 시간에 올려 주세요.
- 다 올린 뒤 Studio 문서 보안 → 연결 설정에서 연결 확인을 누르면, 사이드카 항목이 통과하고 새 버전이 보입니다.
- 사이드카를 올리지 않아도 지금 버전으로 계속 쓰실 수 있습니다. 보안 수정처럼 꼭 올려야 하는 업데이트는 따로 알려 드립니다.
- 직접 설치하신 경우는 부록 A-4 를 따라 주세요.
5. 끄기 · 정리
잠시 멈추려면 Studio 문서 보안 화면 위의 끄기. 다시 켜면 설정 그대로 이어집니다.
완전히 걷어내려면 아래 순서로 정리합니다.
-
Studio 연결 설정 탭 → 연결 지우기
-
커넥터 서버에서 사이드카를 지웁니다.
docker rm -f drm-mip docker network rm mcp-hub-drm sudo rm /etc/mcp-hub/drm-mip.envdocker network rm이 커넥터가 아직 연결되어 있다고 실패하면 먼저docker network disconnect mcp-hub-drm <커넥터 컨테이너 이름>을 실행합니다. 커넥터 secrets 폴더의drm.env에서DRM_MIP_TOKEN(넣으셨다면DRM_MIP_URL도) 줄도 지워 주세요. -
Windows PowerShell 5.1 에서 슈퍼유저 등록을 풉니다.
Import-Module AIPService Connect-AipService Remove-AipServiceSuperUser -ServicePrincipalId "<애플리케이션(클라이언트) ID>" Disconnect-AipService -
Microsoft Entra 관리 센터에서 1-2 의 앱 등록을 삭제합니다. 클라이언트 암호도 함께 무효가 됩니다.
부록 A. 직접 설치 (설치 스크립트를 쓰지 않을 때)
설치 스크립트가 하는 일을 손으로 하는 방법입니다. 1장을 마친 뒤 진행합니다.
A-1. 설정 파일 만들기
먼저 커넥터와 사이드카가 서로 확인할 때 쓰는 긴 무작위 문자열을 만듭니다.
openssl rand -hex 32
나온 값을 MIP_SIDECAR_TOKEN 에 넣고, 1-2 에서 적어 둔 값과 함께 파일로 저장합니다.
sudo mkdir -p /etc/mcp-hub
sudo tee /etc/mcp-hub/drm-mip.env > /dev/null <<'EOF'
MIP_TENANT_ID=<디렉터리(테넌트) ID>
MIP_CLIENT_ID=<애플리케이션(클라이언트) ID>
MIP_CLIENT_SECRET=<클라이언트 암호 값>
MIP_SIDECAR_TOKEN=<위에서 만든 무작위 문자열>
EOF
sudo chmod 600 /etc/mcp-hub/drm-mip.env
- 값에 따옴표를 붙이지 않습니다. 따옴표까지 값으로 읽힙니다.
- 이 파일에는 클라이언트 암호가 들어 있으므로 권한을
600으로 두고, 다른 사람이 읽을 수 없게 합니다. 이렇게 두면 아래 docker 명령은sudo로 실행해야 파일을 읽을 수 있습니다.
A-2. 사이드카 실행
docker network create mcp-hub-drm
docker run -d --name drm-mip --restart unless-stopped --network mcp-hub-drm \
--platform linux/amd64 --tmpfs /work:uid=10001 \
--env-file /etc/mcp-hub/drm-mip.env \
ghcr.io/chain-partners/mcp-hub-drm-mip:0.1.1
docker network connect mcp-hub-drm <커넥터 컨테이너 이름>
--tmpfs /work— 사이드카가 문서를 푸는 작업 폴더를 메모리에만 둡니다. 풀린 문서가 서버 디스크에 한 번도 쓰이지 않습니다. 그만큼 문서를 여는 동안 서버 메모리를 씁니다.docker network connect— 커넥터가 사이드카를drm-mip이라는 이름으로 찾을 수 있게 같은 네트워크에 넣습니다. 커넥터 컨테이너 이름은docker ps로 확인하실 수 있습니다. 커넥터를 업데이트하느라 컨테이너를 새로 만들면 이 줄을 다시 실행해야 합니다.- 포트를 열지 않습니다.
-p 8080:8080처럼 사이드카 포트를 서버 밖으로 열지 마세요. 커넥터는 docker 네트워크 안에서만 사이드카를 부릅니다. --restart unless-stopped덕분에 서버를 다시 켜도 사이드카가 따라 켜집니다.:0.1.1— 사이드카 이미지 버전입니다. 사이드카를 올릴 때는 Studio 안내 상자의 「직접 설치하기」 에 보이는 버전으로 바꿔 실행합니다.
사이드카가 떴는지 확인:
docker ps --filter name=drm-mip
A-3. 커넥터 설정
커넥터 secrets 파일에 사이드카 토큰을 넣고 커넥터를 다시 시작합니다.
sudo tee -a /etc/mcp-connector/secrets/drm.env > /dev/null <<'EOF'
DRM_MIP_TOKEN=<MIP_SIDECAR_TOKEN 과 같은 값>
EOF
sudo chmod 600 /etc/mcp-connector/secrets/drm.env
docker restart <커넥터 컨테이너 이름>
-
DRM_MIP_TOKEN은 A-1 의MIP_SIDECAR_TOKEN과 글자 하나까지 같아야 합니다. -
사이드카 컨테이너 이름을
drm-mip이 아닌 이름으로 실행하셨다면 한 줄을 더 넣습니다.DRM_MIP_URL=http://<사이드카 컨테이너 이름>:8080주소는
http://로 적습니다. 사이드카는 docker 네트워크 안에서만 불리므로https://는 받지 않습니다.
A-4. 사이드카 업데이트 (직접)
새 사이드카 버전이 나오면 아래 순서로 올립니다. 설정 파일(/etc/mcp-hub/drm-mip.env)과 커넥터 설정은 그대로 둡니다.
# 1. 새 버전 이미지 받기 — <새 버전> 은 Studio 사이드카 안내 상자의 「직접 설치하기」 에 보이는 버전입니다
docker pull ghcr.io/chain-partners/mcp-hub-drm-mip:<새 버전>
# 2. 지금 사이드카 지우기
docker rm -f drm-mip
# 3. 새 버전으로 실행 — A-2 의 docker run 명령에서 이미지 버전만 바꿉니다
docker run -d --name drm-mip --restart unless-stopped --network mcp-hub-drm \
--platform linux/amd64 --tmpfs /work:uid=10001 \
--env-file /etc/mcp-hub/drm-mip.env \
ghcr.io/chain-partners/mcp-hub-drm-mip:<새 버전>
- 2번과 3번 사이(몇 초) 동안 올라오는 보호 문서는 열리지 않습니다. 사용이 적은 시간에 올려 주세요.
- 커넥터는 다시 시작하지 않아도 됩니다. 사이드카를 같은 이름(
drm-mip)과 같은 네트워크로 다시 띄우면 커넥터가 그대로 찾습니다. - 다 올린 뒤 Studio 문서 보안 → 연결 설정에서 연결 확인을 누르면, 사이드카 항목이 통과하고 새 버전이 보입니다.
- 사이드카를 올리지 않아도 지금 버전으로 계속 쓰실 수 있습니다. 보안 수정처럼 꼭 올려야 하는 업데이트는 따로 알려 드립니다.