MCP 프로그래밍 방식 도구 호출: Sume script_run 동작 방식

Sume 호스팅 MCP 서버(https://mcp.sume.com/mcp)의 프로그래밍 방식 도구 호출은 script_run 도구입니다. 에이전트가 짧은 JavaScript 프로그램을 보내면, 그 프로그램이 Sume 쪽에서 실행되면서 서버의 다른 도구를 반복, 병렬, 조건부로 호출하고 값 하나를 돌려줍니다. 중간 도구 결과는 대화에 들어가지 않습니다. 응답에는 그 값과 함께 모든 호출의 저널과 자식 Job id가 담깁니다.

아래 내용은 2026-09-26에 확인한 MCP 도구와 게이트와 Usage, 그리고 호스팅 서버가 현재 MCP 클라이언트에 돌려주는 script_run 설명을 바탕으로 합니다. 기초 페이지는 CLI와 호스팅 MCP가 여전히 동작하지만 현재 주 연동 경로는 아니라고 설명합니다. 백엔드는 HTTP로 Format API나 Developer API를 호출합니다. 각 호출에 그대로 적용되는 게이트는 유료 API를 호출하는 AI 에이전트의 안전한 자동화에서 다룹니다.

에이전트는 언제 script_run을 써야 하나요?

한 턴에 같은 모양의 독립 호출이 세 번 이상 필요할 때입니다. 문장마다 tts_create 한 번, 장면마다 generate_image 한 번이 그 예입니다. 도구 설명은 여러 타임스탬프에서의 video_frames_create, 그리고 한 wave에 대한 jobs_wait 후 jobs_result도 예로 듭니다. 다음 경우에는 쓰지 마세요.

• 호출이 한두 번일 때. 그 도구를 직접 호출하세요.
• 탐색. tools_list, tools_schema, mcp_health, 그리고 script_run 자신은 스크립트 안에서 거부됩니다.
• 요청 하나보다 오래 이어져야 하는 작업. 실행 전체가 timeout_seconds로 제한되므로, create를 제출하고 그 Job id를 반환한 뒤 스크립트 밖에서 jobs_wait를 호출하세요.

스크립트는 어떻게 작성하나요?

script 필드는 순수 JavaScript로 쓴 async (sume, args, console) => { … }의 본문입니다. 최대 64 KB이며, import, 네트워크, 타이머는 쓸 수 없습니다. args는 스크립트가 args로 읽는 JSON 객체입니다. label, max_calls, max_paid_calls, timeout_seconds는 선택입니다. 스크립트 안에서는 다음을 씁니다.

• await sume.call(name, arguments)는 나열된 도구를 그 도구 자체의 입력 객체로 실행하며, 게이트, 마스킹, 오류는 직접 호출과 같습니다.
• sume.tools.<name>(arguments)는 이름으로 하는 같은 호출이며, 하이픈은 밑줄로 씁니다.
• sume.jobs.wait(ids, { timeout_seconds }), sume.jobs.result(ids), sume.jobs.status(id)가 Job 라이프사이클을 다룹니다.
• 유료 create에는 여전히 각자 다른 idempotency_key가 필요합니다. 예를 들면 "tts-" + i입니다.
• console.log 출력 줄은 logs로 돌아옵니다.

{
  "label": "wave results",
  "max_calls": 4,
  "args": { "job_ids": ["job_123", "job_124", "job_125"] },
  "script": "await sume.jobs.wait(args.job_ids, { timeout_seconds: 40 }); return await sume.jobs.result(args.job_ids);"
}

스크립트 실행은 어떤 예산으로 제한되나요?

모든 실행에는 전체 시간 제한, 호출 예산, 그리고 유료 create를 위한 별도 예산이 있습니다. 위 예시처럼 스크립트 안에서 하는 대기는 현재 실행에 남은 시간으로 잘리며, wait나 result 호출 한 번은 jobs_wait, jobs_result와 같은 상한인 최대 20개 id를 받습니다.

호출이 실패하거나 예산이 바닥나면 어떻게 되나요?

실패는 스크립트가 처리할 수 있는 값이며, 예산 때문에 멈추면 조용히 끝나지 않고 보고됩니다.

• 실패한 호출은 SumeToolError { code, message, data }를 던집니다. 잡아서 재시도하거나 건너뛸 수 있고, 잡지 않으면 실행이 실패합니다.
• 예산 때문에 멈추면 실행은 error.code script_timeout, script_call_budget_exceeded, script_paid_budget_exceeded, script_tool_forbidden 중 하나로 끝납니다.
• 어느 경우든 tools[](도구·모델별 호출 수), calls[], jobs[]는 빠짐없이 채워집니다.
• 다음으로 ok, result, jobs[]를 읽고, jobs[]에 대해 jobs_wait(호출당 최대 20개 id)와 jobs_result를 호출하세요. 이미 Job을 등록한 create는 절대 다시 제출하지 마세요. 대기 방법은 긴 영상 Job의 MCP 도구 호출 타임아웃에서 다룹니다.

스크립트 실행 비용은 어떻게 확인하나요?

스크립트 호출은 사용량 원장에 귀속됩니다. GET /v1/usage에 thread_id, run_id, job_id를 붙이면, 그 범위가 만든 모든 원장 행을 접어 계산한 summary가 추가됩니다.

• includes는 종류별 행 수를 세며, 여기에는 script_run 호출이 보낸 Job인 script_run_children도 포함됩니다.
• script_runs는 범위 안의 script_run 호출을 각각의 행, 금액과 함께 나열합니다.
• script_run이 보낸 행에는 script_run_id와 script_run_call_index가 붙습니다.
• 지갑에서 실제로 차감된 금액인 debited_usd_micros를 인용하세요. 행을 직접 더하지 마세요. 환불된 행은 billable_amount_usd_micros에 예약 금액을 그대로 유지합니다.