MCP tools and gates

Hosted MCP tools wrap selected public API capabilities. Always discover the live contract with tools.list and tools.schema — do not assume HTTP API parity.

Discover tools

ToolPurpose
tools.listList every tool visible in this session, with safety metadata.
tools.schemaFetch one tool contract by name.
mcp.healthEndpoint readiness, auth source, and safety posture.

Example agent instruction:

Safety gates

Hosted MCP defaults to read-only behavior. Mutating and paid tools require explicit flags in the tool arguments.

GateRequired forMeaning
allow_write=trueWrite tools and paid toolsOpt in to a mutating MCP call.
idempotency_keyWrite tools and paid toolsStable key for safe retries.
allow_paid=truePaid generation toolsOpt in to billable generation.
max_spend_usdPaid generation toolsHard spend cap checked against admission preview.
dry_run=truePaid generation toolsRun admission preview only; do not submit the job.

Server instructions also state this default: mutating tools need allow_write plus idempotency_key; paid tools additionally need allow_paid and max_spend_usd.

Auth interaction

Session authWhat the gates do
OAuth Phase 1 (mcp:read)Write/paid tools are not available. Calls return insufficient_scope even if you pass gate flags.
API keyTools are visible. Gate flags still required for write/paid execution.

Tool inventory (hosted)

Grouped from the current hosted registry. Names use the live tool ids.

Meta and health

  • mcp.health
  • tools.list
  • tools.schema
  • health.service
  • health.v1

Account and catalog

  • account.me
  • balance.get
  • usage.get
  • catalog.list
  • generation.admission_preview

Jobs

Read:

  • jobs.list
  • jobs.get
  • jobs.status
  • jobs.result
  • jobs.events
  • jobs.wait

Write (needs allow_write + idempotency_key):

  • jobs.cancel

Assets

Read:

  • assets.list
  • assets.get
  • assets.download_url

Write (needs allow_write + idempotency_key):

  • assets.create
  • assets.upload_url
  • assets.complete

Hosted MCP cannot read files from your laptop. Upload flow is: create upload URL → client PUT bytes → assets.complete.

Avatars

Read:

  • avatars.list
  • avatars.get
  • avatars.search

Paid (needs allow_write, allow_paid, max_spend_usd, idempotency_key):

  • avatars.create

Avatar videos

Read:

  • avatar-videos.list
  • avatar-videos.get

Paid (needs allow_write, allow_paid, max_spend_usd, idempotency_key):

  • avatar-videos.create

Not available on hosted MCP

These are not hosted MCP tools today:

  • Image generation MCP tools
  • Generic video generation MCP tools (outside Avatar Video)
  • Music generation MCP tools
  • STT MCP tools
  • Video Router MCP tools

Use the Developer API for those families. catalog.list may show HTTP capabilities that do not have matching MCP tools yet.

Playbooks

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

  1. Connect to https://mcp.sume.com/mcp with OAuth.
  2. Call mcp.health and confirm auth_source is OAuth.
  3. Call tools.list and keep only read_only tools in mind.
  4. Call catalog.list, balance.get, and jobs.list as needed.
  5. Stop before any write/paid tool. OAuth Phase 1 will deny them.

Playbook B — Inspect one tool before paying

  1. Call tools.schema with name: "avatars.create" (or avatar-videos.create).
  2. Call generation.admission_preview or the paid tool with dry_run=true.
  3. Confirm estimate, balance, and queue behavior.
  4. Only then submit with allow_write=true, allow_paid=true, max_spend_usd, and a fresh idempotency_key — and only on an API-key session until OAuth write/paid scopes ship.

Playbook C — Paid avatar create (API-key remote MCP)

Use only when the user explicitly confirms spend.

Required arguments pattern:

  1. First call with dry_run=true and review the preview.
  2. Repeat with dry_run omitted or false to submit.
  3. Poll with jobs.status / jobs.wait, then read jobs.result.
  4. Prefer Sume public ids and media.sume.com URLs in agent reports. Do not paste signed URLs, OAuth tokens, or API keys into chat logs.

Playbook D — Local CLI instead of hosted MCP

Use when the agent already runs local shell commands. Drive Avatar workflows with sume avatars / sume avatar-videos / sume jobs, and Image/Video/Music via the Developer API. Local sume mcp remains coming_soon in current CLI releases — do not treat it as a working stdio server yet.

Hosted OAuth and local CLI login are different flows; do not expect sume login to mint hosted MCP OAuth tokens.