music_create over MCP: dry run, idempotency key and jobs_wait

To make a track from an MCP client, call Sume's hosted music_create tool with an idempotency_key and a payload that holds your prompt, optionally set dry_run first to preview the cost, then call jobs_wait and jobs_result. A wait holds for at most 55 seconds per call, so a long track means repeating jobs_wait on the same job id, never resubmitting the create.

This post follows MCP tools and gates and jobs and results. Always call tools_schema with the name music_create for the live contract; tool schemas can change.

What does music_create submit to?

The tool submits to Music 1.0 (sume/music-1.0). Music 1.0 is retiring gradually: its routes keep working and keep job.model = sume/music-1.0, but every request resolves through the Music Router, which picks Lyria 3.5 today. The result is the same kind of job you get over HTTP: a Sume-hosted audio artifact, typically audio/mpeg on media.sume.com, at a fixed $0.125 per accepted generation.

The tool is paid, so it is visible only to sessions that can write: an OAuth session with mcp:write, or an API key. A session with mcp:read only sees read tools, and mutating calls return insufficient_scope.

How do the gates work?

Two fields matter on every paid tool. idempotency_key is required: it is a stable key for deduplication, not a human approval step. dry_run=true is optional and returns an admission and cost preview without creating a job. max_spend_usd is enforced only when you provide it. There is no separate paid scope; spend runs through the wallet and admission.

What do the arguments look like?

Put the music fields inside payload, not at the top level. This is the argument object for one call; the rest of the shape is whatever your MCP client wraps around a tool call.

{
  "idempotency_key": "intro-score-001",
  "dry_run": true,
  "payload": {
    "prompt": "A 30-second launch teaser. [0:00-0:10] Intro: sparse piano, 90 BPM, A minor. [0:10-0:30] Build: strings and a soft kick. Instrumental, no vocals."
  }
}

How do you wait for the result?

After the real create returns a job id, call jobs_wait. On remote MCP the wait defaults to 50 seconds and is capped at 55; larger values are clamped, and the response says so in wait_slice_clamped. If you get wait_slice_expired, call jobs_wait again with the same id. A 524 or similar on jobs_wait is a transport failure, not a job outcome, so re-issue the wait or read jobs_status once.

Do not resubmit the create because a wait timed out. The job keeps running and keeps billing, and a second create would be a second charge unless it reuses the same idempotency key. When the job is terminal, call jobs_result and read the audio artifact from result.artifacts[].

What about several tracks at once?

jobs_wait accepts job_ids with 1 to 20 ids and a wait_for of all or any, which is better than N single waits after a fan-out. wait_for: any still reports every id, and the other jobs continue and bill. For three or more calls of the same shape, script_run can loop music_create inside one call, with each paid create still carrying its own idempotency key.

Write a distinct brief per scene instead of one generic bed: the tool description asks for a per-scene brief with emotion, genre, tempo, key, instruments and an arc, as the Music 1.0 page describes.

A short checklist keeps agent runs clean: preview with dry_run when a run will create several tracks, use one stable idempotency key per intended track, wait in slices, and read the result once. If the same brief is retried with the same key, you should not get a second track; if you want a different take, change the key on purpose.