MCP 도구와 게이트

이 문서는 영문 원고를 AI로 번역한 내용이라 표현이 어색할 수 있습니다.

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

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

안전 게이트

호스팅 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를 사용하세요. catalog.list에는 아직 대응하는 MCP 도구가 없는 HTTP 기능이 나타날 수 있습니다.

플레이북

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

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

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

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

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

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

필요한 인자 패턴입니다.

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

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

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