MCP tools and gates

Hosted MCP tools wrap selected public API capabilities. Always use tools_list and tools_schema to discover the live contract. Do not assume parity with the HTTP API.

The live tool ids are underscore names from packages/mcp-server/src/mcp.ts (remoteMcpTools). On each call, the server canonicalizes . → _. Thus, dotted aliases, for example tools.list, still work. Retired aliases: image-generations_create → generate_image, video-router_create → generate_video.

Discover tools

Tool	Purpose
`tools_list`	List all the tools that this session can see, and their safety metadata.
`tools_schema`	Get one tool contract by `name`.
`mcp_health`	Endpoint readiness, auth source, and safety posture.

Example agent instruction:

Safety gates

Under OAuth mcp:read, hosted MCP gives read-only visibility by default. Hosted MCP hides the tools that change data and the paid tools until the session has mcp:write (or an API key). Spend is wallet/admission. There is no mcp:paid scope.

Gate	Required?	Meaning
`idempotency_key`	Required on write and paid tools	Stable key for transport/dedup, not human approval.
`dry_run=true`	Optional	Admission/cost preview only. It does not submit the job.
`max_spend_usd`	Optional	Sume enforces it only when you provide it.
`allow_write` / `allow_paid`	Optional (legacy)	Sume accepts them for back-compat. They are not required. They cannot bypass a missing `mcp:write` scope.

Before expensive bursts, we recommend generation_admission_preview and/or dry_run. A normal single create does not need these admission steps.

Auth interaction

Session auth	What you see / can call
OAuth `mcp:read` only	Read-only tools. Calls to write/paid tools return `insufficient_scope`.
OAuth `mcp:read` + `mcp:write`	Full hosted tool set. Paid submits still need `idempotency_key` and wallet/admission.
API key	Full hosted tool set. Same `idempotency_key` / admission rules.

`script_run`

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. 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. To get the subset that the session can see, call tools_list.

Meta and health

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

Account and catalog

account_me
balance_get
usage_get
catalog_list
image-models_list / image-models_get
video-router_models
generation_admission_preview

Jobs

Read: jobs_list, jobs_get, jobs_status, jobs_result, jobs_events, jobs_wait.

Write (idempotency_key): jobs_cancel.

Assets

Read: assets_list, assets_get, assets_download_url.

Write (idempotency_key): assets_create, assets_upload_url, assets_complete.

Hosted MCP cannot read files from your laptop. 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
music_create
tts_create
stt_create
image_upscale_create
rmbg_create
video_upscale_create
kling-motion-control_create

Read (free): tts_source_get (accepted-script manifest for tts_create with transcript_source), tts_source_verify_spine (compares the selected TTS jobs with the accepted script).

Avatars and talking-head

Read: avatars_list, avatars_get, avatars_search, avatar-videos_list, avatar-videos_get.

Paid: avatars_create, avatar-videos_create, avatar-image-to-video_create, avatar-video-previews_create / _get / _regenerate / _generate_video.

Read: crawl_scrape, crawl_map, crawl_search, crawl_get, crawl_profile, crawl_feed, crawl_media, crawl_find.

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

Social discovery skill: crawl-social. Web research skill: crawl-web.

Media inspect / import / captions / timeline

media-imports_create / media-imports_get
video_inspect (default for “what is this clip”, dest and prod) — Video inspect
video_frames_create / video_frames_get — Video frames
video_trim — Video trim
audio_detach — Audio detach
video_filter — Video filter (check_only: true is the unbilled /check)
video-captions_get (the legacy video-captions_create / video-caption-overlay_create are unlisted. In-flight clients can still call them by name, but they are not in tools_list)
timeline_create / timeline_get — Timeline 1.0
timeline_compose — Timeline compose
timeline_audio — Timeline audio
trending-videos_search, trending-research_search

video-analyses_* (#5953): dest (SUME_COM_VIDEO_ANALYSIS_ENABLED=false) delists them from tools_list and video-analyses_create answers 410 video_analysis_retired. Production still lists them until PR-C2. Do not call create on dest.

Dest-only (mcp.dev.sume.com / api.dev.sume.com, never production): video_analyze and video_segment appear in tools_list only when videoUnderstand.enabled is on (Railway development + trusted origin https://api.dev.sume.com + SUME_COM_TWELVELABS_API_KEY). Both must have idempotency_key and max_spend_usd. They do not replace video_inspect for lightweight probe/stills.

Not on hosted MCP

These names are not in tools_list:

images_create / videos_create — Sume Image 1.0 and Video 1.0 stay REST-only. Use the Developer API.
Higgsfield-only names (get_workflow_instructions, models_explore, media_import_url, remove_background as an HF tool). Cutouts are rmbg_create. The social URL mirror is media-imports_create.

catalog_list can still show HTTP capabilities that do not have an MCP tool.

Playbooks

Playbook A — OAuth read-only discovery (Cursor / Claude)

Use OAuth to connect to https://mcp.sume.com/mcp. If you do not need to change data, keep Write off.
Call mcp_health. Make sure that authenticated.auth_source is mcp_oauth.
Call tools_list. When Write is off, only the read_only tools are available.
If necessary, call catalog_list, balance_get, and jobs_list.
If Write was off, stop before you call tools that change data. These tools return insufficient_scope.

Playbook B — Inspect one tool before paying

Call tools_schema with name: "generate_image" (or avatars_create).
Call generation_admission_preview or the paid tool with dry_run=true.
Examine the estimate, the balance, and the queue behavior.
Submit with a new idempotency_key on a session that has mcp:write or an API key. If you want a cap, add the optional max_spend_usd.

Playbook C — Paid avatar create (write session)

Use this playbook only when the user explicitly confirms spend.

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

First, call with dry_run=true. Then examine the preview.
To submit, call again with dry_run omitted or false.
Poll with jobs_status / jobs_wait. Then read jobs_result.
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

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.

Hosted OAuth and local CLI login are different flows. sume login does not mint hosted MCP OAuth tokens.