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

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

라이브 도구 ID는 `packages/mcp-server/src/mcp.ts`(`remoteMcpTools`)의
**밑줄** 이름입니다. 서버는 호출 시 `.` → `_`로 canonicalize하므로
`tools.list` 같은 점 별칭도 동작합니다. 폐기 별칭:
`image-generations_create` → `generate_image`, `video-router_create` →
`generate_video`.

## 도구 탐색하기

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

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

```text
name을 "generate_image"로 해서 tools_schema를 호출하고, 유료 생성을 요청하기
전에 idempotency_key와 dry_run을 설명해 줘.
```

## 안전 게이트

호스팅 MCP는 OAuth `mcp:read`에서 기본적으로 읽기 전용 **가시성**입니다.
변경·유료 도구는 세션에 `mcp:write`(또는 API 키)가 있을 때까지 숨겨집니다.
지출은 지갑/접수입니다. `mcp:paid` 스코프는 없습니다.

| 게이트 | 필수? | 의미 |
|---|---|---|
| `idempotency_key` | 쓰기·유료 도구에 **필수** | 전송/중복 제거용 고정 키입니다. 사람 승인이 아닙니다. |
| `dry_run=true` | 선택 | 접수/비용 프리뷰만 실행하고 Job은 제출하지 않습니다. |
| `max_spend_usd` | 선택 | 넘긴 경우에만 강제됩니다. |
| `allow_write` / `allow_paid` | 선택(레거시) | 하위 호환으로 받으며 **필수가 아닙니다**. 빠진 `mcp:write`를 우회하지 못합니다. |

비싼 버스트 전에는 `generation_admission_preview` 또는 `dry_run`을 권장합니다.
평범한 단일 생성에는 접수 연극이 필요 없습니다.

### 인증과의 상호작용

| 세션 인증 | 보이는 것 / 호출할 수 있는 것 |
|---|---|
| OAuth `mcp:read`만 | 읽기 전용 도구. 변경·유료 호출은 `insufficient_scope`를 반환합니다. |
| OAuth `mcp:read` + `mcp:write` | 전체 호스팅 도구 세트. 유료 제출에는 여전히 `idempotency_key`와 지갑/접수가 필요합니다. |
| API 키 | 전체 호스팅 도구 세트. 같은 `idempotency_key` / 접수 규칙입니다. |

## 프로그래밍 방식 도구 호출 (`script_run`)

`script_run`은 Sume 쪽에서 짧은 JavaScript 프로그램을 실행해 아래 도구들을
반복, 병렬, 조건부로 호출하고 값 하나를 돌려줍니다. 한 턴에 같은 모양의
독립 호출이 세 번 이상 필요할 때(문장마다 `tts_create`, 장면마다
`generate_image`) 사용하세요. 스크립트 안의 `await sume.call(name, arguments)`는
직접 호출과 같은 게이트, 마스킹, 오류로 나열된 도구를 실행하며, 유료 생성은
여전히 각자의 `idempotency_key`가 필요합니다. 실행은 `timeout_seconds`(5–55),
`max_calls`, `max_paid_calls`로 제한되고, 응답에는 반환값, `calls[]` 저널,
`jobs_wait`할 자식 `jobs[]`가 담깁니다. 탐색 도구와 `script_run` 자신은
스크립트 안에서 호출할 수 없습니다.

## 도구 목록 (호스팅)

현재 호스팅 레지스트리를 그룹으로 묶은 것입니다. 이름은 실제 도구 ID입니다.
세션에 보이는 부분집합은 `tools_list`로 확인하세요.

### 메타와 헬스

- `mcp_health`
- `tools_list`
- `tools_schema`
- `script_run` (프로그래밍 방식 도구 호출, 위 참고)
- `health_service`
- `health_v1`

### 계정과 카탈로그

- `account_me`
- `balance_get`
- `usage_get`
- `catalog_list`
- `image-models_list` / `image-models_get`
- `video-router_models`
- `generation_admission_preview`

### Jobs

읽기: `jobs_list`, `jobs_get`, `jobs_status`, `jobs_result`, `jobs_events`,
`jobs_wait`.

쓰기(`idempotency_key`): `jobs_cancel`.

### 에셋

읽기: `assets_list`, `assets_get`, `assets_download_url`.

쓰기(`idempotency_key`): `assets_create`, `assets_upload_url`,
`assets_complete`.

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

### 이미지·비디오·오디오 생성

유료(`idempotency_key`; 사용자가 패밀리를 지정하지 않으면 `payload.model`을
생략해 `sume/auto`로 라우팅):

- `generate_image`
- `generate_video`
- `music_create`
- `tts_create`
- `stt_create`
- `image_upscale_create`
- `rmbg_create`
- `video_upscale_create`
- `kling-motion-control_create`

### 아바타와 토킹 헤드

읽기: `avatars_list`, `avatars_get`, `avatars_search`, `avatar-videos_list`,
`avatar-videos_get`.

유료: `avatars_create`, `avatar-videos_create`,
`avatar-image-to-video_create`, `avatar-video-previews_create` /
`_get` / `_regenerate` / `_generate_video`.

### 크롤 (웹 + 소셜)

읽기: `crawl_scrape`, `crawl_map`, `crawl_search`, `crawl_get`,
`crawl_profile`, `crawl_feed`, `crawl_media`, `crawl_find`.

쓰기(`idempotency_key`; 미과금 유틸): `crawl_site`(이후 같은 id로
`jobs_wait` → `crawl_get`).

소셜 탐색 스킬: `crawl-social`. 웹 리서치 스킬: `crawl-web`.

### 미디어 inspect / import / 캡션 / 타임라인

- `media-imports_create` / `media-imports_get`
- `video_inspect`(클립 검사 기본값; dest와 prod) —
  [비디오 검사](/models/video-inspect)
- `video_frames_create` / `video_frames_get` —
  [비디오 프레임](/models/video-frames)
- `video_trim` — [비디오 트림](/models/video-trim)
- `audio_detach` — [오디오 분리](/models/audio-detach)
- `video_filter` — [비디오 필터](/models/video-filter) (`check_only: true`는 무료 `/check`)
- `video-captions_create` / `video-caption-overlay_create` / `video-captions_get`
- `timeline_create` / `timeline_get` — [Timeline 1.0](/models/timeline)
- `timeline_compose` — [타임라인 합성](/models/timeline-compose)
- `timeline_audio` — [타임라인 오디오](/models/timeline-audio)
- `trending-videos_search`, `trending-research_search`

`video-analyses_*`(#5953): dest(`SUME_COM_VIDEO_ANALYSIS_ENABLED=false`)는
`tools_list`에서 빼고 `video-analyses_create`는
`410 video_analysis_retired`입니다. 프로덕션은 PR-C2까지 목록에 남습니다.
dest에서 create를 호출하지 마세요.

dest 전용(`mcp.dev.sume.com` / `api.dev.sume.com`, 프로덕션 불가):
`video_analyze`와 `video_segment`는 `videoUnderstand.enabled`가 켜진 세션의
`tools_list`에만 보입니다(Railway `development` + 신뢰 origin
`https://api.dev.sume.com` + `SUME_COM_TWELVELABS_API_KEY`). 둘 다
`idempotency_key`와 `max_spend_usd`가 필수입니다. 가벼운 프로브/스틸은
여전히 `video_inspect`입니다.

## 호스팅 MCP에 없는 것

다음 이름은 `tools_list`에 **없습니다**.

- `images_create` / `videos_create` — Sume Image 1.0과 Video 1.0은 REST
  전용입니다. [Developer API](/public-api)를 사용하세요.
- Higgsfield 전용 이름(`get_workflow_instructions`, `models_explore`,
  `media_import_url`, HF 도구로서의 `remove_background`). 컷아웃은
  `rmbg_create`, 소셜 URL 미러는 `media-imports_create`입니다.

`catalog_list`에는 아직 대응하는 MCP 도구가 없는 HTTP 기능이 나타날 수
있습니다.

## 플레이북

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

1. OAuth로 `https://mcp.sume.com/mcp`에 연결합니다. 변경이 필요 없으면 Write를
   꺼 두세요.
2. `mcp_health`를 호출해 `authenticated.auth_source`가 `mcp_oauth`인지
   확인합니다.
3. Write가 꺼져 있으면 `tools_list`에서 `read_only` 도구만 염두에 둡니다.
4. 필요에 따라 `catalog_list`, `balance_get`, `jobs_list`를 호출합니다.
5. Write가 꺼져 있으면 변경 도구 앞에서 멈추세요. `insufficient_scope`를
   반환합니다.

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

1. `name: "generate_image"`(또는 `avatars_create`)로 `tools_schema`를
   호출합니다.
2. `generation_admission_preview`를 호출하거나 유료 도구를 `dry_run=true`로
   호출합니다.
3. 추정치, 잔액, 큐 동작을 확인합니다.
4. `mcp:write`가 있는 세션이나 API 키로 새 `idempotency_key`를 넣어 제출합니다.
   상한이 필요하면 선택 `max_spend_usd`를 넘기세요.

### 플레이북 C — 유료 아바타 생성 (쓰기 세션)

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

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

`allow_write` / `allow_paid`는 여전히 보낼 수 있지만 필수는 아닙니다.

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
```

에이전트가 이미 로컬 셸 명령어를 실행하고 있을 때 사용하세요. CLI 도구 ID는
점 표기(`avatars.create`)를 유지합니다. 그 레지스트리는 호스팅 MCP 카탈로그가
아닙니다. 로컬 `sume mcp`는 현재 CLI 릴리스에서 여전히 `coming_soon`입니다.

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

## 관련 문서

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