MCP 도구와 게이트

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

호스팅 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`	엔드포인트 준비 상태, 인증 출처, 안전 설정을 알려줍니다.

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

안전 게이트

호스팅 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) — 비디오 검사
video_frames_create / video_frames_get — 비디오 프레임
video_trim — 비디오 트림
audio_detach — 오디오 분리
video_filter — 비디오 필터 (check_only: true는 무료 /check)
video-captions_create / video-caption-overlay_create / video-captions_get
timeline_create / timeline_get — Timeline 1.0
timeline_compose — 타임라인 합성
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를 사용하세요.
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)

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

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

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

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

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

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

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

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

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

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