도구와 안전장치
도구 목록, 승인·견적·호출 한도를 정리합니다.도구 찾기
도구 목록과 입력 형식은 서버가 정본입니다. 클라이언트가 연결하면 허용한 기능의 도구가 자동으로 보입니다. 사용 방법이 헷갈리면 기능마다 있는 가이드 도구를 먼저 부릅니다. 가이드는 주제를 골라 절차와 주의점을 돌려줍니다.
| 기능 | 가이드 도구 |
|---|---|
| 스튜디오 공통 | studio_guide |
| 이미지 생성 | image_guide |
| 영상 생성 | video_guide |
| 영상 저작 | get_video_guide |
| 만화 저작 | get_toon_guide |
| 웹소설 저작 | get_novel_guide |
연결 방식
- 기능별 주소: 허용한 기능마다 서버가 따로 있습니다. 필요한 서버만 연결할 수 있습니다.
- 통합 주소(
/mcp): 허용한 모든 기능의 도구가 한 서버에 모입니다. 도구 이름은 기능 사이에서 겹치지 않습니다.
안전 장치
| 장치 | 적용 대상 | 동작 |
|---|---|---|
| 도구 모드 | 모든 도구 | 도구마다 읽기, 제안, 생성, 쓰기, 지출, 취소 중 하나로 표시됩니다. 클라이언트가 읽기 전용 여부와 파괴적 여부를 알 수 있습니다. |
| 제안 후 승인 | 작품 저작 도구 | 에이전트는 수정을 제안만 하고, 적용은 사용자가 앱에서 승인합니다. |
| 견적과 보류 | 체리를 쓰는 도구 | 견적과 보류 금액이 같은 계산입니다. 견적 토큰(15분 유효)이 있어야 접수됩니다. |
| 웹 승인 | 장면 배치 확정, 공개 범위 변경, 덮어쓰기 | 에이전트는 요청만 남깁니다. 사용자가 링크의 웹 화면에서 호출마다 승인하고, 승인은 한 번만 쓰이며 10분 안에 해야 합니다. |
| 호출 한도 | 모든 기능 | 기능마다 시간당 읽기·쓰기 한도가 있습니다. 아래 표를 보세요. |
| 결과 크기 상한 | 모든 도구 | 한 번에 돌려주는 결과는 글자 수 상한이 있어 큰 결과는 나눠 받습니다. |
승인 요청에서 장면 배치를 다시 부를 때는 처음과 같은 입력이어야 합니다. 내용이 바뀐 재호출이나 다른 사용자의 호출은 승인을 쓰지 못합니다.
호출 한도
시간당 호출 수입니다. 읽기는 쓰기의 10배입니다.
| 기능 | 주소 | 쓰기 한도(시간당) | 읽기 한도(시간당) |
|---|---|---|---|
| 영상 저작 | /video/mcp | 1200 | 12000 |
| 만화 저작 | /toon/mcp | 600 | 6000 |
| 웹소설 저작 | /novel/mcp | 600 | 6000 |
| 스튜디오 공통 | /studio/mcp | 600 | 6000 |
| 이미지 생성 | /image/mcp | 300 | 3000 |
| 영상 생성 | /video-gen/mcp | 300 | 3000 |
도구 목록
도구 이름, 한 줄 설명, 모드는 서버 계약에서 생성합니다.
스튜디오 공통
| 도구 | 하는 일 | 모드 |
|---|---|---|
studio_guide | 이 서버의 사용 가이드(읽기 전용, 서비스 호출 없음) | 읽기 |
studio_query | 스튜디오 공통 상태를 action 하나로 조회한다(읽기 전용, 본인 데이터만) | 읽기 |
studio_upload | 외부 대화에서 받은 참고 사진을 내 자산으로 올리는 3단 도구(체리를 쓰지 않는다) | 쓰기 |
studio_register_skill | 사용자가 채팅에 붙여 넣은 스킬 텍스트를 그 사용자의 '내 스킬'에 새 스킬로 저장한다 | 쓰기 |
studio_share | 내 공유(shareId)의 공개 범위를 바꾼다(shareId·visibility·idempotencyKey) | 쓰기 |
studio_curate | 이미지(kind=image)·영상(kind=video) 생성 잡의 즐겨찾기를 목표 값으로 설정한다(jobId·favorite) | 쓰기 |
이미지 생성
| 도구 | 하는 일 | 모드 |
|---|---|---|
image_guide | 이 서버의 사용 가이드(읽기 전용, 서비스 호출 없음) | 읽기 |
image_query | 이미지 정보를 action 하나로 조회한다(읽기 전용) | 읽기 |
image_quote | 이미지 생성 총액 견적(읽기 전용, 과금 없음; modelId·resolution·quality·candidateCount) | 읽기 |
image_generate | 이미지 생성을 접수한다(체리 hold) | 쓰기 |
image_enhance_prompt | 이미지 프롬프트를 생성 모델에 맞게 다듬는다(호출당 1 체리 차감, 시간당 30회 한도) | 쓰기 |
image_upscale | 내 이미지 자산을 2배 또는 4배로 키운 새 자산을 만든다(assetId·revision·scale; 서버 안의 고정 리샘플링이라 체리를 쓰지 않는다) | 쓰기 |
image_select | 완료된 이미지 잡의 후보 중 대표 하나를 고른다(내 작업의 표시 상태만 바뀌고 체리·문서는 바뀌지 않는다) | 쓰기 |
image_cancel | 이미지 생성 잡 취소(jobId·idempotencyKey) | 쓰기 |
영상 생성
| 도구 | 하는 일 | 모드 |
|---|---|---|
video_guide | 이 서버의 사용 가이드(읽기 전용, 서비스 호출 없음) | 읽기 |
video_query | 영상 생성 정보를 action 하나로 조회한다(읽기 전용) | 읽기 |
video_quote | 영상 클립 제출 전 체리 금액을 견적한다(읽기 전용, 과금 없음; modelId·duration·resolution·generateAudio·candidateCount·inputImageCount) | 읽기 |
video_generate | kind 로 두 갈래를 낸다(유료, 체리 hold) | 쓰기 |
video_run | 캔버스 문서의 노드 실행을 action 하나로 다룬다(start 는 노드마다 체리를 차감한다) | 쓰기 |
video_batch_plan | 여러 장면(1~50개)을 같은 설정으로 영상 생성할 계획과 견적을 만든다(documentId·revision·sceneHeadingIds·params·idempotencyKey) | 쓰기 |
video_batch_confirm | video_batch_plan 으로 만든 계획의 확정(체리 hold)을 사람에게 요청한다(batchId·expectedRevision·idempotencyKey) | 쓰기 |
video_cancel | 대기(queued) 중인 영상 클립 생성 잡을 취소한다(jobId) | 쓰기 |
video_plan | 발행된 씬 배치를 action 하나로 다룬다 | 쓰기 |
영상 저작
| 도구 | 하는 일 | 모드 |
|---|---|---|
create_video_document | 호출자 소유의 빈 캔버스 문서를 만든다 | 쓰기 |
create_video_storyboard | 평평한 입력 한 번으로 대본(씬·지문·대사)·컷(샷 크기·카메라 움직임·길이)·자막을 갖춘 새 초안 영상 문서를 만든다 | 쓰기 |
list_video_documents | 호출자 소유 문서 목록(읽기 전용, 휴지통 제외, 최신 수정순 한 페이지) | 읽기 |
list_video_proposals | 문서에 발행된 제안 목록(읽기 전용) | 읽기 |
get_video_proposal | 제안 하나의 요약(읽기 전용): 상태·결정 봉투·대상 revision·operation 개수·rationale | 읽기 |
list_video_document_versions | 문서의 보관된 revision 목록(읽기 전용, 최신순 최대 200개): revision·createdAt·name | 읽기 |
read_video_document_version | 문서의 과거 revision 본문(읽기 전용) — read_video_document 와 같은 투영(일시 자격증명 제거)·같은 sectionId 의미 | 읽기 |
read_video_document | 현재 비디오 문서 정본 스냅샷 반환(읽기 전용) | 읽기 |
simulate_video_operations | 제안 전 관찰(읽기 전용 — 문서·제안 어느 것도 바꾸지 않는다) | 읽기 |
propose_video_operations | 닫힌 operation 1..60개를 하나의 배열 페이로드(하나의 검토 카드 = 하나의 undo 단위)로 담은 PENDING 제안을 발행한다 — 문서는 바꾸지 않는다 | 쓰기 |
propose_cut_clips | 문서의 스토리보드 컷을 고른 영상 모델의 생성 길이(supported_durations)에 맞춰 이웃 컷끼리 클립으로 묶고, 클립마다 영상 노드 하나를 더하는 PENDING 제안을 발행한다 — 웹 콘티의 '클립 변환'과 같은 규칙이며 문서는 바꾸지 않는다(승인 전에는 컷 노드뿐이라 실행할 수 없다) | 쓰기 |
propose_timeline_assembly | 캔버스 실행이 만든 영상 클립을 촬영 순서(씬→컷→영상 노드)대로 타임라인 V1 에 배치하는 place_clip 연산을 서버가 만들어 PENDING 제안을 발행한다 — 문서는 바꾸지 않는다(승인 전 불변) | 쓰기 |
read_plot_memos | 문서가 핀한 대본의 플롯 카드 메모를 읽는다(읽기 전용) | 읽기 |
write_plot_memo | 플롯 카드 메모 한 칸을 바로 쓴다(덮어쓴다, memo ≤1000자) | 쓰기 |
write_memo_node | 캔버스의 순수 메모 노드(text, memoOnly)를 바로 쓴다 | 쓰기 |
list_memo_writes | 문서의 직접 쓰기 기록(읽기 전용, 최신순): write_id·write_type(story_plot_memo|video_memo_node|undo)·before_revision·after_revision·undone_by·created_at | 읽기 |
undo_memo_write | 직접 쓰기 하나를 되돌린다 — 그 쓰기가 만든 revision 이 문서의 현재 head 일 때만 된다(그 뒤 누군가 고쳤으면 conflict 이고, 웹의 버전 목록에서 복원한다) | 쓰기 |
get_video_guide | 이 서버의 사용 가이드(읽기 전용, 서비스 호출 없음) | 읽기 |
만화 저작
| 도구 | 하는 일 | 모드 |
|---|---|---|
list_toon_documents | 내 만화 작품 목록(documentId·title·revision·updatedAt)을 최근 수정순 커서 페이지로 돌려준다 | 읽기 |
read_toon_document | 작품의 개요(제목·형식·페이지 목록)와 현재 revision 을 돌려준다 | 읽기 |
create_toon_document | 제목(과 선택 형식·색)으로 빈 만화 작품(첫 페이지 1)을 만든다 — 웹 '새 작품'과 같은 빈 문서다 | 쓰기 |
simulate_toon_operations | 제안 전 관찰(읽기 전용 — 문서·제안 어느 것도 바꾸지 않는다) | 읽기 |
propose_toon_operations | 닫힌 operation 1..20개를 하나의 배열 페이로드(하나의 검토 카드 = 하나의 undo 단위)로 담은 PENDING 제안을 발행한다 — 문서는 바꾸지 않는다 | 쓰기 |
list_toon_proposals | 작품의 제안 목록(status 기본 pending, cursor 페이지) | 읽기 |
get_toon_guide | 이 서버의 사용 가이드(읽기 전용, 서비스 호출 없음) | 읽기 |
웹소설 저작
| 도구 | 하는 일 | 모드 |
|---|---|---|
list_novel_documents | 내 웹소설 작품 목록(documentId·title·revision·updatedAt)을 최근 수정순으로 최대 100개 돌려준다 | 읽기 |
read_novel_document | episodeId 없이 부르면 작품 개요(제목·진입 회차·회차 목차와 요약·폴더)와 현재 revision 을 돌려준다 | 읽기 |
create_novel_document | 제목(과 선택 시놉시스 씨앗)으로 새 웹소설 작품(1화 뼈대)을 만든다 — 웹 '새 작품'과 같은 뼈대다 | 쓰기 |
simulate_novel_operations | 제안 전 관찰(읽기 전용 — 문서·제안 어느 것도 바꾸지 않는다) | 읽기 |
propose_novel_operations | 닫힌 operation 1..20개를 하나의 배열 페이로드(하나의 검토 카드 = 하나의 undo 단위)로 담은 PENDING 제안을 발행한다 — 문서는 바꾸지 않는다 | 쓰기 |
list_novel_proposals | 작품의 제안 목록(status 기본 pending, cursor 페이지) | 읽기 |
get_novel_guide | 이 서버의 사용 가이드(읽기 전용, 서비스 호출 없음) | 읽기 |
플레이북
읽기 전용으로 둘러보기
- 가이드 도구를 부릅니다.
- 조회 도구로 목록과 상세를 읽습니다.
- 아무것도 바꾸지 않았음을 사용자에게 알립니다.
견적 보고 생성하기
- 조회 도구로 모델과 가격 조합을 고릅니다.
- 견적 도구로 금액을 받고, 잔액과 함께 사용자에게 보여 줍니다.
- 사용자가 동의하면 견적 토큰을 붙여 접수합니다. 새 키로 다시 접수하면 새 작업입니다. 같은 키는 같은 작업을 돌려줍니다.
- 안내된 대기 시간 뒤에 조회합니다. 완료되면 읽기 링크를 바로 보여 줍니다. 링크는 15분 안에 쓰입니다.
승인 대기 처리하기
- 영수증에 승인 링크가 있으면 사용자에게 링크를 보여 줍니다.
- 사용자가 웹에서 승인할 때까지 기다립니다. 에이전트는 승인할 수 없습니다.
- 승인을 받으면 같은 입력으로 같은 도구를 다시 부릅니다.