Safe automation for AI agents that call paid APIs

To let an AI agent call Sume's paid APIs safely, keep exploration read-only, make every credit-spending action explicit, and keep API keys, OAuth tokens, and signed URLs out of logs and chat. On Sume's hosted MCP server, that also means an idempotency_key on each write or paid call, a dry_run cost preview before an expensive burst, and max_spend_usd when you want a cap.

The rules below come from Sume's Safe automation, MCP tools and gates, and MCP OAuth and API keys docs pages.

How should an agent authenticate?

Generation and analysis creation can spend credits, so agent tools should make those actions explicit and keep read-only operations separate. Sume's hosted MCP server accepts OAuth access tokens or Sume API keys, and they are not interchangeable credentials.

Prefer OAuth mcp:read for read-only exploration. Write is a toggle on the consent screen, off by default; grant mcp:write (or use an API key) before paid tools such as generate_image or avatars_create. There is no mcp:paid scope: spend is wallet/admission. Client setup is in Connect Claude Code, Cursor, or Codex to Sume.

Which safety gates apply to paid calls?

Mutating and paid tools stay hidden until the session has mcp:write or an API key. Once they are visible, these gates apply. See also Idempotency keys for AI video APIs and Spend caps for unattended AI agents.

How do I preview cost before an agent spends?

Before expensive bursts, call generation_admission_preview or the paid tool with dry_run=true; ordinary single creates do not need that step. The docs playbook for inspecting a tool before paying:

• Call tools_schema with name: "generate_image" (or avatars_create). Always discover the live contract; do not assume HTTP API parity.
• Call generation_admission_preview, or the paid tool with dry_run=true.
• Confirm the estimate, balance, and queue behavior.
• Submit with a fresh idempotency_key on a session that has mcp:write or an API key. Add max_spend_usd when you want a cap.

What does a paid call look like?

This payload follows the docs playbook for a paid avatar create, which is for use only when the user explicitly confirms spend. Call first with dry_run: true and review the preview, then repeat with dry_run omitted or false to submit. Poll with jobs_status / jobs_wait, then read jobs_result.

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

Can an agent batch paid calls under the same gates?

Yes, with script_run. It runs a short JavaScript program on the Sume side that calls tools in a loop, in parallel, or conditionally, and returns one value. Each call inside it has 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.

How do I keep secrets and workspaces safe?

API keys and app sessions determine the workspace. Tools should not accept user-supplied workspace ids unless the product explicitly supports switching workspaces. In agent reports, prefer Sume public ids and media.sume.com URLs.

• An MCP OAuth token is not a Sume API key.
• Do not store OAuth tokens in CLI config, paste them into prompts, or forward them to third-party providers.
• Do not mint API keys for hosted OAuth clients as a workaround.
• Do not paste signed URLs, OAuth tokens, or API keys into chat logs. Rotate API keys if they appear in logs or chat history.