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

## 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 "avatars.create" and explain the required gates
before submitting any paid generation.
```

## Safety gates

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

| Gate | Required for | Meaning |
|---|---|---|
| `allow_write=true` | Write tools and paid tools | Opt in to a mutating MCP call. |
| `idempotency_key` | Write tools and paid tools | Stable key for safe retries. |
| `allow_paid=true` | Paid generation tools | Opt in to billable generation. |
| `max_spend_usd` | Paid generation tools | Hard spend cap checked against admission preview. |
| `dry_run=true` | Paid generation tools | Run 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 auth | What 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 key | Tools 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](/public-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:

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

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. Drive Avatar workflows
with `sume avatars` / `sume avatar-videos` / `sume jobs`, and Image/Video/Music
via the [Developer API](/public-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.

## Related

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