> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloosphere.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 마켓플레이스

> PPT·Word·Excel·HTML 문서 생성기와 Google Workspace·Microsoft 365 연동을 위한 서비스 컨테이너를 연결합니다.

<Info>관리자 › 설정 › 마켓플레이스</Info>

마켓플레이스 애드온이 사용하는 **Cloosphere 자체(1st-party) 서비스 컨테이너**를 Cloosphere에 연결하는 관리자 화면입니다.
문서 생성기(코드 실행 엔진)와 외부 연동(Google Workspace·Microsoft 365 MCP)의 URL을 지정하고, 테스트한 뒤 활성화합니다.

<Warning>
  마켓플레이스는 **별도 유상 애드온**입니다. **관리자 › 설정 › 마켓플레이스** 탭은 라이선스에 `marketplace` 기능 키가 등록되어 있어야 표시됩니다. 먼저 [라이선스](/ko/admin/settings/license)에서 애드온 키를 등록하세요.
</Warning>

***

## 전체 구조

마켓플레이스는 **카탈로그 메타데이터와 연결 설정만** 저장합니다. 실제 작업을 수행하는 컨테이너(사이드카)는 관리자가 별도로 배포하며, 이 화면은 그 컨테이너의 URL을 가리키기만 합니다.

```mermaid theme={null}
flowchart LR
    A[Cloosphere 백엔드] -->|URL + 토큰| J[(Jupyter 사이드카<br/>문서 생성)]
    A -->|URL| G[(Google Workspace MCP)]
    A -->|URL| M[(Microsoft 365 MCP)]
    subgraph 별도 배포 컨테이너
      J
      G
      M
    end
```

| 사이드카                       | ACR 이미지    | 컨테이너       | 포트            | 역할                         |
| -------------------------- | ---------- | ---------- | ------------- | -------------------------- |
| Code Interpreter (Jupyter) | `mkp-code` | `jupyter`  | 8888          | 문서 생성 스킬 + 코드 인터프리터 실행     |
| Google Workspace MCP       | `mkp-gws`  | `gws-mcp`  | 8000 (`/mcp`) | Gmail·Calendar·Drive 등     |
| Microsoft 365 MCP          | `mkp-m365` | `m365-mcp` | 8001 (`/mcp`) | Outlook·Teams·SharePoint 등 |

<Note>
  이미지는 사설 ACR `acrcloosphere.azurecr.io`에서 배포됩니다. 고객 VM 배포는 `docker compose` + `.env`(ACR 토큰 필수, `JUPYTER_TOKEN` 권장)로 진행합니다. 문서 생성만 사용한다면 Jupyter 사이드카만 있으면 됩니다.
</Note>

***

## 문서 생성기 (코드 실행)

PPT·Word·Excel·HTML 문서 생성 스킬은 **Jupyter 코드 실행 엔진**에서 번들 스크립트를 실행해 파일을 만듭니다.

<Steps>
  <Step title="Jupyter URL · 토큰 입력">
    문서 생성기 카드에 Jupyter 서비스 URL(예: `http://jupyter:8888`)과 인증 토큰(`JUPYTER_TOKEN`)을 입력합니다.
  </Step>

  <Step title="연결 테스트">
    **연결 테스트**를 눌러 Jupyter가 응답하는지 확인합니다. 성공해야 활성화할 수 있습니다.
  </Step>

  <Step title="활성화 · 저장">
    **활성화** 스위치를 켜고 저장하면 코드 실행 엔진이 켜집니다. 내부적으로 `ENABLE_CODE_EXECUTION`, `CODE_EXECUTION_ENGINE=jupyter`, URL·토큰이 기록됩니다.
  </Step>
</Steps>

<Note>
  이 설정은 [코드 실행](/ko/admin/settings/code-execution) 설정과 동일한 엔진을 공유합니다. 한쪽에서 Jupyter를 켜면 문서 생성 스킬과 사용자 코드 인터프리터가 함께 사용합니다.
</Note>

<Warning>
  코드 실행 엔진이 준비되지 않으면 워크스페이스 카탈로그에서 문서 생성기 카드가 **비활성**으로 표시되고, 인스턴스 생성도 차단됩니다. 채팅에서는 파일이 생성되지 않고 에이전트가 지침만 따르게 됩니다.
</Warning>

***

## 외부 연동 (MCP 서비스)

Google Workspace·Microsoft 365를 에이전트 도구로 노출합니다.

<Steps>
  <Step title="서비스 URL 입력">
    각 MCP 서비스 카드에 컨테이너 URL을 입력합니다(예: `http://gws-mcp:8000/mcp`, `http://m365-mcp:8001/mcp`). 끝에 슬래시를 붙이지 마세요.
  </Step>

  <Step title="연결 테스트">
    **연결 테스트**로 서비스 도달 여부를 확인합니다. 인증이 필요한 MCP 서버는 토큰 없는 프로브에서 401/403이 정상이며 "도달 가능"으로 처리됩니다.
  </Step>

  <Step title="활성화">
    **활성화**하면 해당 서비스의 마켓플레이스 연결이 생성되어, 워크스페이스 ▸ 마켓플레이스와 에이전트의 마켓플레이스 도구 섹션에 나타납니다.
  </Step>
</Steps>

<Note>
  MCP 사이드카는 **passthrough 인증**을 사용합니다 — 자체 OAuth를 돌리지 않고 각 사용자의 SSO 토큰을 그대로 신뢰합니다. 따라서 Google OAuth 클라이언트는 Cloosphere 로그인과 **동일**해야 하며, 서비스별 카테고리는 사용자에게 부여된 OAuth 스코프에 따라 사용 가능 여부가 결정됩니다.
</Note>

<Warning>
  기본 URL은 하드코딩되어 있지 않습니다. 관리자가 URL을 설정하고 연결하기 전까지 MCP 서비스는 카탈로그에 "연결 안 됨"으로 나타나지 않습니다. 에이전트가 사용 중인 서비스는 비활성화할 수 없습니다(사용 중 오류).
</Warning>

***

## 상태 배지

각 서비스 카드는 실시간 상태를 표시합니다.

| 배지                      | 의미                        |
| ----------------------- | ------------------------- |
| **연결 가능 (Reachable)**   | URL이 응답함 — 활성화 가능         |
| **연결 불가 (Unreachable)** | URL이 응답하지 않음 — 배포·네트워크 확인 |
| **준비 안 됨 (Not Ready)**  | 코드 실행 엔진 미설정 등 전제 조건 미충족  |

<Note>
  MCP "연결됨" 배지는 연결 행이 존재한다는 의미일 뿐, 서버가 실제로 살아 있다는 보장은 아닙니다. 실제 상태는 워크스페이스 ▸ 도구에서 도구 목록을 조회할 때 확인됩니다.
</Note>

***

## 권한 부여

관리자가 서비스를 연결한 뒤, 사용자가 마켓플레이스를 쓰려면 그룹 권한이 필요합니다.

* **관리자 설정 > 사용자 > 그룹**에서 그룹에 **마켓플레이스 접근**(없음/읽기/쓰기)을 부여합니다. 기본값은 잠금입니다.
* 연결·기능을 **생성**하려면 쓰기 권한이 필요합니다.
* 문서 생성기(스킬)를 쓰는 사용자에게는 필요 시 **스킬 접근** 권한도 부여하세요.

***

## 관련 문서

<Columns cols={2}>
  <Card title="마켓플레이스 (사용자)" icon="store" href="/ko/workspace/marketplace">
    사용자가 문서 생성 기능과 MCP 연동을 만들고 에이전트에 붙이는 방법
  </Card>

  <Card title="코드 실행" icon="terminal" href="/ko/admin/settings/code-execution">
    문서 생성기가 공유하는 코드 실행 엔진(Jupyter) 설정
  </Card>

  <Card title="라이선스" icon="key" href="/ko/admin/settings/license">
    마켓플레이스 애드온 기능 키 등록
  </Card>

  <Card title="스킬 (사용자)" icon="wand-magic-sparkles" href="/ko/workspace/skills">
    재사용 지침서와 실행형 스킬 개념
  </Card>
</Columns>