Sume hosted MCP from a CI runner: API key or OAuth?

For an unattended job, use an API-key session on the hosted MCP endpoint rather than the OAuth connector. OAuth needs a person to sign in and approve on the consent page. The Sume docs describe API-key remote MCP as the other path for automation that does not use OAuth, and say interactive clients should prefer the OAuth flow.

Send the key as Authorization: Bearer $SUME_API_KEY or as x-api-key. Send one, not both: a request with both credentials is rejected with 401, and neither header wins.

What the key session can do

An API-key session sees the full hosted tool set, including write and paid tools. Spend is governed by wallet and admission. Calls that change data or spend money must include idempotency_key, and the docs recommend dry_run=true or generation_admission_preview before the first paid submit. max_spend_usd is enforced only if you pass it.

Your runner then waits with jobs_wait, which holds a single call for at most 55 seconds (default 50) and takes up to 20 job_ids. On wait_slice_expired, call it again with the same ids and never repeat the paid create.

Security notes

Keep the key in the CI secret store and out of prompts and logs. If a key appears in a log or chat history, rotate it. Do not put it in the MCP server URL; use a header.

• Create the key in the dashboard; its scopes are fixed at creation and cannot be added later.
• Give the runner its own key so it can be revoked without touching people.
• Hosted MCP does not read files from the runner. Uploads use assets_upload_url, a client PUT, then assets_complete.
• A local MCP server is not part of this setup; use hosted MCP.

When to prefer plain REST

If the runner only needs one generation and a result, the Developer API with Idempotency-Key and a poll loop is simpler than an MCP session. Image 1.0 and Video 1.0 are REST only and are not on hosted MCP. MCP earns its place when an agent in the loop chooses the tools.

Cost control for unattended runs

An unattended runner has no human to say no, so put the limits in the call. Pass max_spend_usd on every paid tool, use a stable idempotency_key per job, and keep the wave inside the queue capacity of the workspace. A Pro workspace accepts 24 jobs at once, so a nightly run of 20 clips fits, and a run of 30 does not.

Alert on the failure modes that look like success: a jobs_wait that ended on wait_slice_expired, and a wait_for: any that returned while other jobs still run and bill. Read the final state of every job id before the step ends.

Treat this as a habit, not a one-time fix. Write the rule down next to the code that calls the API, add a test that exercises it, and review it whenever the docs change. Check the linked documentation pages in the sources list for the current wording before you rely on any number here, because limits and field names can be revised, and a short test run costs far less than debugging a production incident.

When something does not match what you read here, capture the x-sume-request-id response header and the job or run id, and send those to support. Do not paste API keys, signing secrets or full request bodies into a ticket or a chat; the ids are enough for the team to find the request.