Make an avatar video from an MCP agent: tools, dry run, spend cap
The hosted MCP server of Sume exposes avatars_list, avatar-videos_create and jobs_wait. How dry_run and max_spend_usd gate a paid call, and the scope you need.
An agent connected to Sume's hosted MCP server makes an avatar video with this sequence: avatars_list to find a ready handle, avatar-videos_create with a script, jobs_wait until the job is terminal, then jobs_result for the video URL. Paid and write tools need an idempotency_key, and the first call can be a dry_run that previews the spend before anything is submitted.
The server is remote, at https://mcp.sume.com/mcp. Access depends on how you connected, and that is the usual reason an agent sees the tools but cannot run them.
Tools in the avatar path
From the MCP tools and gates reference.
| Tool | Kind | Use |
|---|---|---|
avatars_list, avatars_get, avatars_search | Read | Find a ready avatar handle |
avatars_create | Paid | Create a new avatar |
avatar-videos_create | Paid | Render a script with an avatar |
avatar-video-previews_create and friends | Paid | First-frame stills before the render |
avatar-image-to-video_create | Paid | Still plus audio talking clip |
jobs_wait, jobs_result | Read | Wait for and read the output |
The spend gate
A paid call carries the arguments idempotency_key, optionally dry_run: true and max_spend_usd, plus a payload holding the same body as the API. Call once with dry_run and read the preview. Then repeat with dry_run omitted to submit.
{
"idempotency_key": "avatar-video-update-001",
"dry_run": true,
"max_spend_usd": 5,
"payload": {
"avatar_handle": "studio_presenter",
"script": "Here is what changed this week.",
"quality": "standard"
}
}Scopes: why a paid call is refused
Under OAuth the default grant is read-only (mcp:read), so a paid tool such as avatars_create returns insufficient_scope. Turn Write on at the consent page to also receive mcp:write; there is no mcp:paid scope. An API-key remote session gets the full hosted tool set, and the wallet and admission checks are the spend gate.
Waiting without timeouts
Avatar renders usually outlast a single slice, so expect several waits.
- A single
jobs_waitholds at most 55 seconds; the default is 50. - On
wait_slice_expired, calljobs_waitagain with the same ids. Never resubmit the paid create. - A 524, 522, 523 or 525 on
jobs_waitis a transport failure, not a job outcome. - Pass up to 20
job_idsto wait on a batch, withwait_for: "all"or"any".
A worked turn
A typical agent turn runs like this. It calls avatars_list and picks a handle with a ready status. It calls avatar-videos_create with dry_run: true and shows you the estimate. After you agree, it repeats the call without dry_run and the same idempotency_key, which is safe because the key ties the retry to the same request. It then loops jobs_wait until the job is terminal and finishes with jobs_result, which returns the public video URL for you to review.
Limits
The agent is only as safe as the budget you set. A max_spend_usd smaller than the rate card's estimate for the clip is the cheapest guard, and a dry run is free. Scripts still have to estimate to 4 to 60 seconds, and output is 720p.
Sources
Related posts
More in Integrations
- Poll a Sume job from a CI step with curl and jq: exit codes
A 23-line bash script that polls /v1/jobs/{id}/status and exits 0, 1, 2 or 3, so a CI step can tell done, failed, still running and a bad request apart.
- Bun.serve webhook receiver for Sume: raw body, verify, dedupe
A 24-line Bun.serve receiver for Sume job webhooks: read the raw body first, verify sume-v1, dedupe on job_id, answer 204 before the work. Tested on Bun 1.4.
- Claude Code MCP whitespace warning: a pasted Sume key with a newline
Claude Code warns when an MCP header or url has leading or trailing whitespace, often a pasted token with a newline. It does not trim it. Fix a Sume entry.
- Claude Code .mcp.json: why ${ANTHROPIC_API_KEY} reads empty for Sume
Claude Code reads credential variables like ANTHROPIC_API_KEY and NPM_TOKEN as empty in a remote url or headers. Name your Sume key variable SUME_API_KEY.
Written by Sume