Connect an agent to Scene Assembly

Before you start

You need a Scene Assembly account with at least one provider key connected. Sign in at https://sceneassembly.mzork.com/account and add a key under your provider connections. The agent can use only the providers whose keys are connected there, and it cannot add or read keys itself.

The MCP URL

https://mcp-sceneassembly.smoxu.com/mcp

The Connected agents panel on your account page (https://sceneassembly.mzork.com/account) shows the same URL with a copy button.

Connect your client

Each client opens a Scene Assembly page in your browser the first time it connects. Sign in if asked, choose a spend limit and two permissions (see What you approve), and approve. Finish in the browser that opened the page: a link copied to another browser will not complete the connection.

Claude Code

claude mcp add --transport http scene-assembly https://mcp-sceneassembly.smoxu.com/mcp

Then run /mcp inside Claude Code, choose scene-assembly and sign in.

Claude.ai and Claude Desktop

Custom connectors are available in Claude on the web and in Claude Desktop. On a Free, Pro or Max plan (Free allows one custom connector):

1. Open Customize → Connectors (claude.ai/customize/connectors).
2. Click +, then Add custom connector.
3. Paste the MCP URL and click Add. Leave Advanced settings empty: Scene Assembly registers the client itself.
4. Connect it, and Claude opens the Scene Assembly page.

On a Team or Enterprise plan, an Owner adds the connector first: Organization settings → Connectors (claude.ai/admin-settings/connectors), Add, hover over Custom and choose Web, paste the MCP URL and click Add. Each member then opens Customize → Connectors, finds the connector and clicks Connect.

Cursor

Add the server to ~/.cursor/mcp.json, or to .cursor/mcp.json in a project:

{
  "mcpServers": {
    "scene-assembly": {
      "url": "https://mcp-sceneassembly.smoxu.com/mcp"
    }
  }
}

Then follow Cursor's prompt to log in to the server, which opens the Scene Assembly page.

Any other client

The server speaks Streamable HTTP and uses OAuth 2.1 with dynamic client registration and PKCE. A client that supports remote MCP servers with OAuth needs only the URL: an unauthenticated request gets a 401 whose WWW-Authenticate header points at the protected-resource metadata, and discovery goes from there.

Reconnecting

A connection lasts 30 days from the day you approve it and is not extended by use, so expect to reconnect about once a month. When it lapses, the agent's calls fail with HTTP 401; connect again the same way you did the first time. Each approval creates a new entry in the Connected agents panel with its own limit; the lapsed one leaves the panel on its own. Each entry shows when it was connected and last used, which tells a working connection from an old one with the same name.

What you approve

The consent page shows the name the client gave itself, marked unverified, and the address it returns to. It lists what the agent will be able to do: start image and video jobs with your connected keys; cancel, resume or stop tracking jobs, including ones you started in the browser; copy files from any web link into your account's temporary storage; see your jobs, library and spend; and read your providers' remaining balances. It cannot see or change your provider keys.

You choose three things:

• Spend limit per 24 hours. In US dollars, from $0.50 to $500. The default is $5. A job that would go over the limit is refused before it starts.
• Allow models without a published price. Off by default. Some models have no price Scene Assembly can know before they run: every model from Kie.ai, Runware, CometAPI, Cloudflare and Pollinations, and some fal.ai and Atlas Cloud models. These runs count toward the limit only once the provider reports what they cost, so the limit cannot stop them in advance. That is why the default is off. The consent page names the connected providers this affects.
• Allow deleting files from your library. Off by default. Without it the agent is not offered delete_asset at all.

To change these later, open the Connected agents panel on your account page, edit the limit or the switches, and save. The change applies to the agent's next call, though a client may keep showing an old tool list, with or without delete_asset, until it reconnects. Disconnect is in the same panel and also takes effect on the agent's next call, which fails with HTTP 401. Jobs the agent already started keep running and stay in your library.

The usual loop

Each step is one tool call. The arguments are examples.

1. See what can run. list_models with no arguments returns a compact list of the models your connected providers offer. A model the vendor has deprecated still runs. The list sets deprecated to true on it and leaves label as the name a saved job already uses.

   {}
   

2. Read one model's settings. list_models with provider and modelId returns each input mode with its fields, options, bounds and defaults, and how many reference images it takes.

   { "provider": "gemini", "modelId": "gemini-nano-banana-2.1" }
   

3. Price it. estimate_cost takes the same fields as generate and checks the result against the agent's limit. Settings you leave out take the model's defaults, and the response echoes them in values.

   { "provider": "gemini", "modelId": "gemini-nano-banana-2.1", "mediaType": "image", "inputMode": "text", "prompt": "A paper kite over a harbour at dawn", "values": { "aspectRatio": "16:9" } }
   

4. Start the job. generate with an idempotencyKey. It returns at once with a job, the estimate and the agent's remaining budget.

   { "provider": "gemini", "modelId": "gemini-nano-banana-2.1", "mediaType": "image", "inputMode": "text", "prompt": "A paper kite over a harbour at dawn", "values": { "aspectRatio": "16:9" }, "idempotencyKey": "harbour-kite-1" }
   

5. Wait for it. get_job with waitSeconds (up to 25) holds the call until the job's state changes. Call it again until the state is saved, failed, cancelled or needs_attention. A saved job lists its outputs, each with an assetId and a download link.

   { "jobId": "<job.id from generate>", "waitSeconds": 25 }
   

6. Look at the result. view_asset returns an image inline as a WebP no larger than 1024 px, with a download link. A video comes back as the link only.

   { "assetId": "<outputs[0].assetId from get_job>" }
   

Idempotency

The idempotencyKey is any string you choose, up to 200 characters, and it belongs to this agent only. Reuse the key when you retry the same request, for example after a timeout: you get the same job back and are not charged again. A new key, or no key at all, starts a new job and a new charge. Reusing a key with a different request, or with a job that was removed, is refused with token_conflict. If the first call with a key is still starting, a second one is refused with request_in_progress; wait a few seconds and retry, or call list_jobs. Both refusals are described under Errors.

References

Some input modes take reference images, and edit mode takes a source video. Models that list reference video or audio (Seedance 2.5 on Runware, and the Atlas Seedance reference-to-video models) also take referenceVideos and referenceAudios on generate. Stage a file with add_reference, then pass the uploadId it returns.

From a link. Scene Assembly downloads the file straight away.

{ "url": "https://example.com/cat.png" }

• The URL must be public https, with a hostname rather than an IP address and no user name or password in it.
• It cannot point at Scene Assembly itself. Pass { "assetId": … } for a file already in the library.
• Up to 3 redirects are followed, each checked by the same rules. The download times out after 20 seconds.
• The type is read from the file's bytes, not its headers: PNG, JPEG, WebP or AVIF images up to 20 MB, an edit-source MP4 up to 200 MB, WebM up to 100 MB, and MP3 or WAV audio up to 15 MB. WebM staged from a link is an edit source only. A reference video is MP4 up to 100 MB, or a MOV uploaded with video/quicktime. QuickTime and HEIC files are refused from a link, because those brands are not stored from a sniff.

From a file you have. Ask for an upload link with the file's type and its exact size in bytes:

{ "upload": { "mimeType": "image/png", "bytes": 482113 } }

The response has a putUrl. PUT exactly that many bytes there within 15 minutes, with the same Content-Type:

curl -T cat.png -H "Content-Type: image/png" "<putUrl>"

A different type or byte count is refused by the upload link itself with an HTTP 400, not by a tool; ask for a new link with the right figures.

mimeType is one of image/png, image/jpeg, image/webp, image/avif, video/mp4, video/webm, video/quicktime, audio/mpeg, audio/mp3, audio/wav, audio/wave or audio/x-wav. Images stop at 20 MB, audio at 15 MB, and video at 100 MB. video/webm is an edit source. A reference video is video/mp4 or video/quicktime.

From a YouTube video. For edit mode, Scene Assembly can cut a section of a YouTube video into the source clip:

{ "youtube": { "url": "https://youtu.be/aqz-KE-bpKQ", "startSeconds": 62, "endSeconds": 74.4, "provider": "runware", "modelId": "bytedance:seedance@2.5" } }

• Times are seconds to one decimal place. With provider and modelId, the section must fit that model's edit source length (list_models); without them, 1–30 seconds.
• Only that section is downloaded, at 720p or above, and staged as an MP4 for 24 hours.
• Add "saveToLibrary": true to also keep it in your library. The response then has assetId and savedToLibrary: true; pass { "assetId": … } as sourceVideo for any later edit instead of importing again. The saved clip counts against your library storage. If the library is full the import still succeeds for this edit, with savedToLibrary: false and a libraryNotice saying so. In list_assets a saved clip has origin (site, videoId, startSeconds, endSeconds, title).
• The response gives the clip's durationSeconds, width and height; check them against the model before calling generate.
• Private, members-only, age-restricted and live videos cannot be imported. An account can import 10 sections an hour, one at a time, shared with the browser.
• The call returns when the clip is ready, usually within 40 seconds and up to about 2 minutes, so set your client's tool timeout to at least 130 seconds (many default to 60).

Using it. An uploadId lasts 24 hours. It is cleaned up soon after the jobs that used it finish, so stage the file again for a later job. A file already in your library needs no staging: pass its assetId. The refusals these steps can return are listed under Errors.

{ "provider": "gemini", "modelId": "gemini-nano-banana-2.1", "mediaType": "image", "inputMode": "image", "prompt": "The same kite, in watercolour", "references": [{ "uploadId": "<from add_reference>" }, { "assetId": "<from list_assets>" }], "idempotencyKey": "harbour-kite-watercolour" }

References go in order. list_models gives each mode's minimum and maximum count, and whether that mode accepts reference video or audio. In edit mode, pass the clip as sourceVideo instead of in references. Reference video and audio are separate arrays, not extra images. A reference video is MP4 or MOV. WebM is an edit source only. A Seedance draft may include them; finalize_draft does not resend them. An account can hold up to 32 staged references, 256 MB in all, across the browser and every agent.

Budget

• The window rolls. The limit covers the last 24 hours, counted back from each call, not a calendar day.
• A job is charged when it is accepted, at its estimate, before the provider starts it. When the job finishes, the charge settles to the cost recorded in your spend ledger.
• A cancel releases the charge only when the provider never ran the job. cancel_job works only while a job is still queued. A job that fails, or that you stop tracking, keeps its charge, because the provider may have billed for it.
• Models without a published price book $0 when they start, and count at their real cost once the provider reports it. They run only if you allowed them.
• When a job would not fit, generate is refused with budget_exceeded, and roomAt says when enough earlier charges leave the window. estimate_cost answers the same question without starting anything.
• get_spend returns the account's spend totals (browser runs included), this agent's limit, what it has used and what is left, and optionally the latest ledger entries and live balances from providers that publish them.

Tools

The server offers 14 tools. delete_asset is offered only when you allowed the agent to delete files.

Each agent can make 300 read calls, 60 write calls (add_reference, cancel_job, dismiss_job, delete_asset) and 10 submissions (generate, finalize_draft, resume_job) per minute. An account runs at most 10 jobs at a time, shared with the browser.

Seedance drafts

Seedance 2.5 on Runware can render a 480p draft (values.draft set to true on generate; the default is off) and later render that same preview at 1080p with finalize_draft. get_job and view_asset return draftId when the preview has one. Finalize does not take a prompt, references, reference video, reference audio, or a source video — those stay on the draft — and it is budget-checked on its own, using the documented 1080p rate. Runware does not publish a separate finalize price, so that figure is an estimate until the provider reports a cost.

Pass jobId and the length is taken from that draft (durationSeconds, or sourceDurationSeconds on an edit). You can omit durationSeconds. Passing a length more than a second off the saved one is refused, and nothing is reserved. A bare draftId still needs durationSeconds and inputMode, because there is no saved job to read.

An edit draft is priced from the source clip. The Worker reads the duration out of the file before it reserves. sourceDurationSeconds is optional and, when you pass it, must be within a second of that length. If the length cannot be read, the draft is refused instead of priced as unknown.

Errors

A refusal arrives as a normal tool result with isError: true. Its structuredContent is { code, message, retryable, … }: message is a sentence you can pass on, retryable says whether sending the same call again later can succeed, and some codes carry more fields. Read code, not the message.

An HTTP 401 from the server is not a refusal. It means the connection was disconnected from the Connected agents panel or has expired, and the person has to reconnect from their client.

Requests and settings

Providers

Budget and limits

Idempotency

References

Job control

Security and privacy

• Sign-in is OAuth 2.1. Your client gets its own access token, valid for an hour and refreshed for up to 30 days. It is tied to your account and to this one connection, and disconnecting stops it on the next call.
• Keys stay on the server. Jobs run with the provider keys stored on your account. No tool returns a key, and an agent cannot add, read or change one.
• Download links are short-lived and open. A link from get_job or view_asset expires after ten minutes, and anyone holding it can download the file until then. Do not paste links anywhere public; call the tool again for a fresh one.
• Upload links are credentials too. A putUrl accepts one file for 15 minutes from whoever holds it.
• Links you pass are fetched by Scene Assembly's server, with no cookies or credentials of yours, and never from Scene Assembly's own addresses.
• An agent sees the whole account's work: your jobs, prompts, library and spend, including what you made in the browser.