MCP tools and gates

Hosted MCP tools wrap selected public API capabilities. Do not assume parity with the HTTP API. What a connection can call depends on how it signs in:

The live tool ids are snake_case names, like avatar_image_to_video_create. On each call, the server canonicalizes . → _. Thus, dotted aliases, for example tools.list, still work. Older dashed names, for example avatar-image-to-video_create, also still run the same tool; the tool list, descriptions and results name the snake_case one. The Studio Agent keeps the dashed names. Retired aliases: image-generations_create → generate_image, video_router_create → generate_video.

Discover tools

On a sign-in connection, the tool list that your client shows is the live contract. A sign-in connection has no tools_list, tools_schema or mcp_health. Calling them answers tool_not_found.

An API key on https://api.sume.com/mcp also has these discovery tools:

Example agent instruction (API key):

Call tools_schema with name "generate_image" and explain idempotency_key and
dry_run before submitting any paid generation.

Safety gates

Under OAuth mcp:read, hosted MCP lists only read-only tools. The create and edit tools appear when the session has mcp:write (or an API key). Spend is checked against the workspace balance and generation admission. There is no mcp:paid scope. All prices are in US dollars.

When the balance is short, the call answers insufficient_credits with the dollars that the call needs, the balance and a billing link. A dry_run: true that the balance cannot cover says so in next_steps: top up first, with the price, the balance and the billing link, and admission_blocked carries the same fields. A run that a ticket covers costs $0 and keeps its submit step.

Before expensive bursts, we recommend dry_run: true. An API key can also call generation_admission_preview. A normal single create does not need these admission steps.

Auth interaction

A tool that this host does not list, or that Sume has turned off, answers tool_not_found on any connection, also on a read-only one.

Tool results

Each tool answers one JSON object in a text block, and the same object as structuredContent, so a client can read its fields without parsing the text. On a sign-in connection and with an API key, every listed tool also has an outputSchema that describes that object. Every result carries agent: the next calls to make (next_steps, next_step) and how to recover. Reads that answer from the Sume API have object: "mcp_public_api_response" with the API answer in response. jobs_wait, models_explore, get_workflow_instructions, generate_image and generate_video describe their own shapes. The Studio Agent's list has no outputSchema.

The JSON object is always the first block. On a sign-in connection and with an API key, a result about images or videos (generate_image, generate_video, their batch tools, execute_preset, job_status, jobs_wait and jobs_result) adds a plain-text summary as the second block: each job with one status word (queued, running, completed, failed or canceled), the link to each finished file and the reason for each failure. A dry run says that nothing started and gives the estimated cost. When the client speaks MCP 2025-06-18 or later (the MCP-Protocol-Version header), the result also ends with a resource_link block for each finished file, up to 8.

A failed call sets isError: true and returns code and message, plus fields that say how to fix the call, in the text block only, with no structuredContent: MCP clients check structuredContent against the outputSchema even on an error. A field sent outside payload that belongs inside it answers unsupported_tool_arguments with hint: "move_to_payload", payload_keys and one adjustments entry per field. Any other unknown argument answers unsupported_tool_arguments with unexpected and allowed, the arguments that the tool takes, and the message lists them. The message names the tool that you called.

Some errors add next_steps, the calls that fix them:

• idempotency_conflict: the key already belongs to an earlier job or asset sent with other inputs. Nothing new started. The steps name that job (wait for it with jobs_wait) and ask for a new key to run this request.
• not_found on a job read: send the exact job id that a generate call returned in this workspace, or find it with jobs_list.

An idempotency_key must be new for each new request and unique in the workspace, not only in one chat, so add a random part. Send the same key again only to retry the same call.

A tts_router_voices search that finds nothing sets agent.hint: every word of query must match, so search with fewer words or filter by gender and language only.

An upstream failure keeps the API's fields, OpenRouter-style: for example provider_rate_limited (HTTP 429) carries retryable, retry_after_seconds, next_action and metadata (provider_name, error_type, provider_code, is_byok, raw). Retry such a call with the same idempotency_key after retry_after_seconds. Error results name only the fix: the workflow pointer that a successful dry run carries is left off.

A payload, a batch requests list or a batch item's payload that arrives as a JSON string is read as the object or list it holds, and agent.adjustments names the field so the agent sends an object next time. dry_run and max_spend_usd stay strict: a string there is refused.

An unknown payload.model on generate_image or generate_video answers model_not_found with did_you_mean: up to three close ids from the models that your connection can use.

Prompts

A connection that lists get_workflow_instructions also serves the bundled workflows as MCP prompts. prompts/list names ad-video and product-photoshoot, each with an optional request argument. prompts/get returns one user message: the workflow's SKILL.md, the files that get_workflow_bundle_file can read, and the request. Clients that show prompts offer them as commands, for example /mcp__sume__ad-video in Claude Code.

Programmatic tool calling (script_run)

script_run is on API keys only. A sign-in connection does not have it.

script_run runs a short JavaScript program on the Sume side. The program calls the tools below in a loop, in parallel, or with conditions, and returns one value. Use it when a turn needs three or more independent calls of the same shape (one tts_create per sentence, one generate_image per scene).

Inside the script, await sume.call(name, arguments) runs any listed tool. The call has the same gates, redaction and errors as a direct call. Paid creates still need their own idempotency_key. timeout_seconds (5–55), max_calls and max_paid_calls set the limits of the run. Each request in a *_batch call counts toward max_paid_calls. A script that computes for too long without awaiting a tool call is stopped. The response contains the returned value, a calls[] journal and the child jobs[] to use with jobs_wait. A script cannot call discovery tools or script_run itself.

Tool inventory (hosted)

This list groups the tools from the current hosted registry. The names are live tool ids. A sign-in connection sees the tools in the first list. An API key sees those too, plus the tools that the groups below mark as API keys only.

On a sign-in connection

Read (mcp:read):

• Workflows and presets: get_workflow_instructions, get_workflow_bundle_file, get_presets, get_preset_instructions
• Models and account: models_explore, balance, usage_get
• Workspaces: list_workspaces, select_workspace
• Jobs: jobs_wait, job_status, jobs_list, jobs_get, jobs_result
• Media: tts_router_voices, video_frames_get, timeline_get

Create and edit (mcp:write, idempotency_key):

• Uploads: media_upload, media_confirm, media_import_url
• Generation: generate_image, generate_video, generate_audio, generate_image_batch, generate_video_batch, generate_audio_batch, execute_preset
• Edits: avatar_image_to_video_create, kling_motion_control_create, remix_video_create, rmbg_create, video_upscale_create, video_frames_create, video_inspect, video_trim, audio_detach, video_filter, timeline_create, timeline_audio, timeline_compose
• Jobs: jobs_cancel

Speech and music go through generate_audio. A talking still is avatar_image_to_video_create.

Meta and health (API keys only)

• mcp_health
• tools_list
• tools_schema
• script_run (programmatic tool calling, refer to the section above)
• health_service
• health_v1

Account and catalog

Every connection: models_explore, balance, usage_get, list_workspaces, select_workspace. An API key belongs to one workspace, so select_workspace answers it with 409 workspace_fixed.

API keys only:

• account_me
• balance_get
• catalog_list
• image_models_list / image_models_get
• video_router_models
• generation_admission_preview

Jobs

Read, every connection: jobs_list, jobs_get, jobs_result, jobs_wait, job_status. API keys also have jobs_status and jobs_events.

Write (idempotency_key): jobs_cancel. It works only before provider work starts. After that, the API answers 409 job_generation_already_started.

To wait, call jobs_wait with include_results: true. While timed_out comes back true, call it again with wait_slice_expired.pending_job_ids.

jobs_list answers 10 jobs a page by default (limit up to 100), newest first, as summaries: id, type, status, model, idempotency_key, created_at, completed_at, outputs (result URLs) and error.public_reason. Pass next_cursor back as cursor for the next page. type and status filter the page. detail: "full" returns whole job records, as before.

Uploads and assets

Every connection with mcp:write: media_upload, media_confirm, media_import_url. Hosted MCP cannot read files from your laptop. A client sends an attached file to media_upload as file. If the client can reach the upload URL, it can use the media_upload payload PUT flow and then media_confirm. A public https:// URL works directly.

API keys only:

• Read: assets_list, assets_get.
• Write (idempotency_key): assets_create, assets_upload_url, assets_complete. The upload flow is: create upload URL → client PUT bytes → assets_complete.

Image, video, audio generation

Paid (idempotency_key, and omit payload.model to route to sume/auto unless the user named a family):

• generate_image
• generate_video
• generate_audio (speech and music)
• generate_image_batch, generate_video_batch, generate_audio_batch (2–12 requests)
• execute_preset
• remix_video_create
• rmbg_create
• video_upscale_create
• kling_motion_control_create
• API keys only: music_create, tts_create, stt_create

Read (free): tts_router_voices (every connection: the voices for speech in generate_audio and tts_create). API keys only: tts_source_get (accepted-script manifest for tts_create with transcript_source) and tts_source_verify_spine (compares the selected TTS jobs with the accepted script). tts_router_voices answers 50 voices a page (limit up to 100), with total and next_cursor. Send next_cursor back as cursor until it is null, or narrow the list with query, gender and language.

tts_create without model is TTS 1.0 on Sonic: the spine, saved voices and sentence slices. model: "eleven-v4" is one expressive take: inline audio tags such as [excited] in the transcript, a tts_router_voices id as voice.id, and nothing saved to the voice library. seed-audio-1.0, qwen-audio-3.0-tts, minimax-speech-2.8-hd and seed-speech take a preset voice name from tts_router_voices with the model's family (seed_audio, qwen, minimax, seed_speech). Speech through generate_audio runs the same models.

Avatars and talking-head

Every connection with mcp:write: avatar_image_to_video_create (lip-sync a still to audio).

API keys only:

• Read: avatars_list, avatars_get, avatars_search, avatar_videos_list, avatar_videos_get.
• Paid: avatars_create, avatar_videos_create, avatar_video_previews_create / _get / _regenerate / _generate_video.

Web crawl, API keys only

A sign-in connection does not list these.

Read: crawl_scrape, crawl_map, crawl_search, crawl_get.

Write (idempotency_key, unbilled utility): crawl_site (then jobs_wait → crawl_get on the same id).

Web research skill: crawl-web.

The social crawl tools (crawl_profile, crawl_feed, crawl_media, crawl_find) and trending_videos_search / trending_research_search are not available on hosted MCP. Calling one answers tool_moved.

Media inspect / import / captions / timeline

Every connection (writes need mcp:write):

• video_inspect (default for “what is this clip”) — Video inspect. Paid by compute: dry_run: true shows the most it can cost, and max_spend_usd caps it.
• video_frames_create / video_frames_get — Video frames. video_frames_create is paid by compute, with the same dry_run and max_spend_usd.
• video_trim — Video trim
• audio_detach — Audio detach
• video_filter — Video filter (check_only: true is the unbilled /check)
• timeline_create / timeline_get — Timeline 1.0
• timeline_compose — Timeline compose
• timeline_audio — Timeline audio

API keys only:

• media_imports_create / media_imports_get
• video_captions_get (the legacy video_captions_create / video_caption_overlay_create are unlisted. In-flight API-key clients can still call them by name, but they are not in tools_list)

video_analyses_* are retiring. Where Sume has turned them off, they are not listed and video_analyses_create answers 410 video_analysis_retired. A sign-in connection never lists them. Use video_inspect for new work.

video_analyze and video_segment appear only on API keys, and only where Sume has a TwelveLabs key configured. They are not on production today. Both need idempotency_key and take max_spend_usd. They do not replace video_inspect for a quick probe or stills.

Not on hosted MCP

These names are not on any hosted MCP connection:

• images_create / videos_create — Sume Image 1.0 and Video 1.0 stay REST-only. Use the Developer API.
• remove_background — Sume does not have this tool. Cutouts are rmbg_create.
• image_upscale_create — removed.
• The social crawl and trending tools (refer to Web crawl).

catalog_list (API keys) can still show HTTP capabilities that do not have an MCP tool.

Playbooks

Playbook A — Sign-in read-only (Cursor / Claude)

1. Sign in to https://mcp.sume.com/mcp. If you do not need to change data, turn off Create and spend credits.
2. Read the tool list that your client shows. A read-only connection lists the 17 read-only tools.
3. If necessary, call balance, models_explore and jobs_list.
4. Stop before you call a create or edit tool. On a read-only connection, these tools return insufficient_scope.

Playbook B — Inspect one tool before paying (API key)

1. Call tools_schema with name: "generate_image" (or avatars_create).
2. Call generation_admission_preview or the paid tool with dry_run: true.
3. Examine the price in dollars (usage.usd), the balance, and the queue behavior.
4. Submit with a new idempotency_key. If you want a cap, add the optional max_spend_usd (dollars).

On a sign-in connection, read the tool from your client's list and price the call with dry_run: true.

Playbook C — Paid avatar create (API key)

Use this playbook only when the user explicitly confirms the price.

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

You can still send allow_write / allow_paid. They are not required.

1. First, call with dry_run: true. Then examine the price in usage.usd.
2. To submit, call again with dry_run omitted or false.
3. Poll with jobs_wait or jobs_status (on a sign-in connection, job_status). Then read jobs_result.
4. In agent reports, Sume public ids and media.sume.com URLs are preferred. Do not paste signed URLs, OAuth tokens, or API keys into chat logs.

Playbook D — Local CLI instead of hosted MCP

sume login
sume mcp doctor --json
sume tools list --json

Use this playbook when the agent already runs local shell commands. CLI tool ids stay dotted (avatars.create). The CLI registry is not the hosted MCP catalog. In the current CLI releases, local sume mcp is still coming_soon.

sume login uses the same Sume sign-in as hosted MCP. Its token is for the HTTP API (https://api.sume.com), so it does not connect to mcp.sume.com/mcp; an MCP client signs in on its own.

Related

• MCP quickstart
• Sign-in and API keys
• Generation admission
• Jobs and results