---
title: MCP tools and gates
description: Hosted MCP tool inventory, safety gates, and agent playbooks.
---

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

| Tool | Purpose |
|---|---|
| `tools_list` | List every tool visible in this session, with safety metadata. |
| `tools_schema` | Fetch one tool contract by `name`. |
| `mcp_health` | Endpoint readiness, auth source, and safety posture. |

Example agent instruction:

```text
Call tools_schema with name "generate_image" and explain idempotency_key and
dry_run before submitting any paid generation.
```

## 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.

| Gate | Required? | Meaning |
|---|---|---|
| `idempotency_key` | **Required** on write and paid tools | Stable key for transport/dedup, not human approval. |
| `dry_run=true` | Optional | Admission/cost preview only; do not submit the job. |
| `max_spend_usd` | Optional | Enforced only when provided. |
| `allow_write` / `allow_paid` | Optional (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 auth | What you see / can call |
|---|---|
| OAuth `mcp:read` only | Read-only tools. Mutating/paid calls return `insufficient_scope`. |
| OAuth `mcp:read` + `mcp:write` | Full hosted tool set. Paid submits still need `idempotency_key` and wallet/admission. |
| API key | Full hosted tool set. Same `idempotency_key` / admission rules. |

## Programmatic tool calling (`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](/models/video-inspect)
- `video_frames_create` / `video_frames_get` —
  [Video frames](/models/video-frames)
- `video_trim` — [Video trim](/models/video-trim)
- `audio_detach` — [Audio detach](/models/audio-detach)
- `video_filter` — [Video filter](/models/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](/models/timeline)
- `timeline_compose` — [Timeline compose](/models/timeline-compose)
- `timeline_audio` — [Timeline audio](/models/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](/public-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.

```json
{
  "idempotency_key": "avatar-create-2026-07-21-001",
  "dry_run": true,
  "max_spend_usd": 2,
  "payload": {
    "avatar_handle": "studio_presenter",
    "type": "prompt",
    "prompt": "A friendly studio presenter in neutral lighting"
  }
}
```

`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

```bash
sume login
sume mcp doctor --json
sume tools list --json
```

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.

## Related

- [MCP quickstart](/mcp/quickstart)
- [OAuth and API keys](/mcp/oauth)
- [Generation admission](/workflows/generation-admission)
- [Jobs and results](/workflows/jobs-and-results)