---
title: MCP 도구와 게이트
description: 호스팅 MCP 도구 목록, 안전 게이트, 에이전트 플레이북을 살펴보세요.
---

호스팅 MCP 도구는 선별된 공개 API 기능을 감쌉니다. 라이브 계약은 항상
`tools.list`와 `tools.schema`로 확인하세요. HTTP API와 같을 것이라고 가정하지
마세요.

## 도구 탐색하기

| 도구 | 용도 |
|---|---|
| `tools.list` | 이 세션에서 보이는 모든 도구를 안전 메타데이터와 함께 나열합니다. |
| `tools.schema` | `name`으로 도구 하나의 계약을 가져옵니다. |
| `mcp.health` | 엔드포인트 준비 상태, 인증 출처, 안전 설정을 알려줍니다. |

에이전트 지시 예시입니다.

```text
name을 "avatars.create"로 해서 tools.schema를 호출하고, 유료 생성을 요청하기
전에 필요한 게이트를 설명해 줘.
```

## 안전 게이트

호스팅 MCP는 기본적으로 읽기 전용으로 동작합니다. 변경 도구와 유료 도구는 도구
인자에 명시적인 플래그가 필요합니다.

| 게이트 | 필요한 곳 | 의미 |
|---|---|---|
| `allow_write=true` | 쓰기 도구와 유료 도구 | 변경을 일으키는 MCP 호출에 동의합니다. |
| `idempotency_key` | 쓰기 도구와 유료 도구 | 안전한 재시도를 위한 고정 키입니다. |
| `allow_paid=true` | 유료 생성 도구 | 과금되는 생성에 동의합니다. |
| `max_spend_usd` | 유료 생성 도구 | 접수 프리뷰와 대조해 확인하는 지출 상한입니다. |
| `dry_run=true` | 유료 생성 도구 | 접수 프리뷰만 실행하고 Job은 제출하지 않습니다. |

서버 지시문에도 같은 기본값이 적혀 있습니다. 변경 도구에는 `allow_write`와
`idempotency_key`가, 유료 도구에는 추가로 `allow_paid`와 `max_spend_usd`가
필요합니다.

### 인증과의 상호작용

| 세션 인증 | 게이트가 하는 일 |
|---|---|
| OAuth Phase 1 (`mcp:read`) | 쓰기·유료 도구를 쓸 수 없습니다. 게이트 플래그를 넘겨도 `insufficient_scope`를 반환합니다. |
| API 키 | 도구가 보입니다. 쓰기·유료 실행에는 게이트 플래그가 여전히 필요합니다. |

## 도구 목록 (호스팅)

현재 호스팅 레지스트리를 그룹으로 묶은 것입니다. 이름은 실제 도구 ID입니다.

### 메타와 헬스

- `mcp.health`
- `tools.list`
- `tools.schema`
- `health.service`
- `health.v1`

### 계정과 카탈로그

- `account.me`
- `balance.get`
- `usage.get`
- `catalog.list`
- `generation.admission_preview`

### Jobs

읽기:

- `jobs.list`
- `jobs.get`
- `jobs.status`
- `jobs.result`
- `jobs.events`
- `jobs.wait`

쓰기(`allow_write` + `idempotency_key` 필요):

- `jobs.cancel`

### 에셋

읽기:

- `assets.list`
- `assets.get`
- `assets.download_url`

쓰기(`allow_write` + `idempotency_key` 필요):

- `assets.create`
- `assets.upload_url`
- `assets.complete`

호스팅 MCP는 로컬 노트북의 파일을 읽을 수 없습니다. 업로드 플로는 업로드 URL
생성 → 클라이언트가 바이트를 PUT → `assets.complete` 순서입니다.

### 아바타

읽기:

- `avatars.list`
- `avatars.get`
- `avatars.search`

유료(`allow_write`, `allow_paid`, `max_spend_usd`, `idempotency_key` 필요):

- `avatars.create`

### 아바타 비디오

읽기:

- `avatar-videos.list`
- `avatar-videos.get`

유료(`allow_write`, `allow_paid`, `max_spend_usd`, `idempotency_key` 필요):

- `avatar-videos.create`

## 호스팅 MCP에 없는 것

다음은 오늘 호스팅 MCP 도구가 **아닙니다**.

- 이미지 생성 MCP 도구
- Avatar Video 외의 일반 비디오 생성 MCP 도구
- 음악 생성 MCP 도구
- STT MCP 도구
- Video Router MCP 도구

이 계열들은 [Developer API](/public-api)를 사용하세요. `catalog.list`에는
아직 대응하는 MCP 도구가 없는 HTTP 기능이 나타날 수 있습니다.

## 플레이북

### 플레이북 A — OAuth 읽기 전용 탐색 (Cursor / Claude)

1. OAuth로 `https://mcp.sume.com/mcp`에 연결합니다.
2. `mcp.health`를 호출해 `auth_source`가 OAuth인지 확인합니다.
3. `tools.list`를 호출하고 `read_only` 도구만 염두에 둡니다.
4. 필요에 따라 `catalog.list`, `balance.get`, `jobs.list`를 호출합니다.
5. 쓰기·유료 도구 앞에서 멈춥니다. OAuth Phase 1은 이를 거부합니다.

### 플레이북 B — 결제 전에 도구 하나 확인하기

1. `name: "avatars.create"`(또는 `avatar-videos.create`)로 `tools.schema`를
   호출합니다.
2. `generation.admission_preview`를 호출하거나 유료 도구를 `dry_run=true`로
   호출합니다.
3. 추정치, 잔액, 큐 동작을 확인합니다.
4. 그런 다음에만 `allow_write=true`, `allow_paid=true`, `max_spend_usd`,
   새 `idempotency_key`로 제출합니다. OAuth 쓰기·유료 스코프가 나오기 전까지는
   API 키 세션에서만 가능합니다.

### 플레이북 C — 유료 아바타 생성 (API 키 원격 MCP)

사용자가 지출을 명시적으로 확인했을 때만 사용하세요.

필요한 인자 패턴입니다.

```json
{
  "allow_write": true,
  "allow_paid": true,
  "max_spend_usd": 2,
  "idempotency_key": "avatar-create-2026-07-21-001",
  "dry_run": true,
  "payload": {
    "avatar_handle": "studio_presenter",
    "type": "prompt",
    "prompt": "A friendly studio presenter in neutral lighting"
  }
}
```

1. 먼저 `dry_run=true`로 호출해 프리뷰를 확인합니다.
2. `dry_run`을 빼거나 `false`로 두고 다시 호출해 제출합니다.
3. `jobs.status` / `jobs.wait`로 폴링한 뒤 `jobs.result`를 읽습니다.
4. 에이전트 리포트에는 Sume 공개 ID와 `media.sume.com` URL을 쓰세요. 서명된
   URL, OAuth 토큰, API 키를 채팅 로그에 붙여 넣지 마세요.

### 플레이북 D — 호스팅 MCP 대신 로컬 CLI

```bash
sume login
sume mcp doctor --json
sume tools list --json
```

에이전트가 이미 로컬 셸 명령어를 실행하고 있을 때 사용하세요. Avatar 워크플로는
`sume avatars` / `sume avatar-videos` / `sume jobs`로, Image/Video/Music은
[Developer API](/public-api)로 처리합니다. 로컬 `sume mcp`는 현재 CLI
릴리스에서 여전히 `coming_soon`이므로 동작하는 stdio 서버로 다루지 마세요.

호스팅 OAuth와 로컬 CLI 로그인은 서로 다른 플로입니다. `sume login`이 호스팅
MCP OAuth 토큰을 발급해 줄 것이라고 기대하지 마세요.

## 관련 문서

- [MCP 빠른 시작](/mcp/quickstart)
- [OAuth와 API 키](/mcp/oauth)
- [생성 접수](/workflows/generation-admission)
- [Job과 결과](/workflows/jobs-and-results)