Mobidoo

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.

Live tool ids are underscore names from packages/mcp-server/src/mcp.ts (remoteMcpTools). The server canonicalizes . → _ on call, so dotted aliases such as tools.list still work. Retired aliases: image-generations_create → generate_image, video-router_create → generate_video.

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 visibility under OAuth mcp:read. Mutating and paid tools are hidden until the session has mcp:write (or an API key). Spend is wallet/admission — there is no mcp:paid scope.

GateRequired?Meaning
idempotency_keyRequired on write and paid toolsStable key for transport/dedup, not human approval.
dry_run=trueOptionalAdmission/cost preview only; do not submit the job.
max_spend_usdOptionalEnforced only when provided.
allow_write / allow_paidOptional (legacy)Accepted for back-compat; not required. Cannot bypass a missing mcp:write scope.

Prefer generation_admission_preview and/or dry_run before expensive bursts. Ordinary single creates do not need admission theater.

Auth interaction

Session authWhat you see / can call
OAuth mcp:read onlyRead-only tools. Mutating/paid calls return insufficient_scope.
OAuth mcp:read + mcp:writeFull hosted tool set. Paid submits still need idempotency_key and wallet/admission.
API keyFull hosted tool set. Same idempotency_key / admission rules.

script_run

script_run runs a short JavaScript program on the Sume side that calls the tools below in a loop, in parallel, or conditionally, and returns one value. Use it when a turn needs three or more independent calls of the same shape (one tts_create per sentence, one generate_image per scene). Inside the script, await sume.call(name, arguments) runs any listed tool with the same gates, redaction and errors as a direct call, and paid creates still need their own idempotency_key. The run is bounded by timeout_seconds (5–55), max_calls and max_paid_calls; the response carries the returned value, a calls[] journal and the child jobs[] to jobs_wait on. Discovery tools and script_run itself cannot be called from a script.

Tool inventory (hosted)

Grouped from the current hosted registry. Names are live tool ids. Call tools_list for the session-visible subset.

Meta and health

  • mcp_health
  • tools_list
  • tools_schema
  • script_run (programmatic tool calling, see above)
  • health_service
  • health_v1

Account and catalog

  • account_me
  • balance_get
  • usage_get
  • catalog_list
  • image-models_list / image-models_get
  • video-router_models
  • generation_admission_preview

Jobs

Read: jobs_list, jobs_get, jobs_status, jobs_result, jobs_events, jobs_wait.

Write (idempotency_key): jobs_cancel.

Assets

Read: assets_list, assets_get, assets_download_url.

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.

Image, video, audio generation

Paid (idempotency_key; omit payload.model to route to sume/auto unless the user named a family):

  • generate_image
  • generate_video
  • music_create
  • tts_create
  • stt_create
  • image_upscale_create
  • rmbg_create
  • video_upscale_create
  • kling-motion-control_create

Avatars and talking-head

Read: avatars_list, avatars_get, avatars_search, avatar-videos_list, avatar-videos_get.

Paid: avatars_create, avatar-videos_create, avatar-image-to-video_create, avatar-video-previews_create / _get / _regenerate / _generate_video.

Crawl (web + social)

Read: crawl_scrape, crawl_map, crawl_search, crawl_get, crawl_profile, crawl_feed, crawl_media, crawl_find.

Write (idempotency_key; unbilled utility): crawl_site (then jobs_wait → crawl_get on the same id).

Social discovery skill: crawl-social. Web research skill: crawl-web.

Media inspect / import / captions / timeline

  • media-imports_create / media-imports_get
  • video_inspect (default for “what is this clip”; dest and prod) — Video inspect
  • video_frames_create / video_frames_get — Video frames
  • video_trim — Video trim
  • audio_detach — Audio detach
  • video_filter — Video filter (check_only: true is the unbilled /check)
  • video-captions_create / video-caption-overlay_create / video-captions_get
  • timeline_create / timeline_get — Timeline 1.0
  • timeline_compose — Timeline compose
  • timeline_audio — Timeline audio
  • trending-videos_search, trending-research_search

video-analyses_* (#5953): dest (SUME_COM_VIDEO_ANALYSIS_ENABLED=false) delists them from tools_list and video-analyses_create answers 410 video_analysis_retired. Production still lists them until PR-C2. Do not call create on dest.

Dest-only (mcp.dev.sume.com / api.dev.sume.com, never production): video_analyze and video_segment appear in tools_list only when videoUnderstand.enabled is on (Railway development + trusted origin https://api.dev.sume.com + SUME_COM_TWELVELABS_API_KEY). Both require idempotency_key and max_spend_usd. They are not a replacement for video_inspect on lightweight probe/stills.

Not on hosted MCP

These names are not in tools_list:

  • images_create / videos_create — Sume Image 1.0 and Video 1.0 stay REST-only. Use the Developer API.
  • Higgsfield-only names (get_workflow_instructions, models_explore, media_import_url, remove_background as an HF tool). Cutouts are rmbg_create; social URL mirror is media-imports_create.

catalog_list may still show HTTP capabilities that do not have matching MCP tools.

Playbooks

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

  1. Connect to https://mcp.sume.com/mcp with OAuth. Leave Write off unless you need mutations.
  2. Call mcp_health and confirm authenticated.auth_source is mcp_oauth.
  3. Call tools_list and keep only read_only tools in mind when Write is off.
  4. Call catalog_list, balance_get, and jobs_list as needed.
  5. If Write was off, stop before mutating tools — they return insufficient_scope.

Playbook B — Inspect one tool before paying

  1. Call tools_schema with name: "generate_image" (or avatars_create).
  2. Call generation_admission_preview or the paid tool with dry_run=true.
  3. Confirm estimate, balance, and queue behavior.
  4. Submit with a fresh idempotency_key on a session that has mcp:write or an API key. Optional max_spend_usd when you want a cap.

Playbook C — Paid avatar create (write session)

Use only when the user explicitly confirms spend.

allow_write / allow_paid may still be sent; they are not required.

  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. CLI tool ids stay dotted (avatars.create) — that registry is not the hosted MCP catalog. Local sume mcp remains coming_soon in current CLI releases.

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