2026-09-26Agents

MCP vs CLI vs API for AI agents: which Sume interface to use

On Sume, HTTP and the Format API are the primary path for AI agents. Hosted MCP fits remote MCP clients; the CLI fits shell agents and is Avatar-heavy.

6 min readSume

All posts

For AI agents on Sume, the primary path is HTTP: the Format API, which the docs call the surface most partners should integrate, and the Developer API, called directly or through the TypeScript SDK. Hosted MCP at https://mcp.sume.com/mcp fits agent clients that speak remote MCP, and the Sume CLI fits agents that run shell commands. The docs say both still work but are not part of the primary path today.

The comparison below comes from Sume's Agents, Sume basics, MCP overview, and CLI overview pages, read on 2026-09-26.

How do the API, hosted MCP, and the CLI fit together?

Sume's developer tools use one boundary, the public API, as What is a video agent? explains. What differs is the wrapper: the CLI is a shell-friendly wrapper around the Developer API, hosted MCP tools wrap selected public API capabilities for Cursor, Claude Code, Codex, and other remote MCP clients, and the SDK is a thin client over the same Developer API.

API and MCP access start with the Pro plan, which also lists CLI access (Pricing).

Which interface should my agent use?

The docs map goals to surfaces like this:

From Agents, MCP OAuth and API keys, MCP quickstart, and Scheduled, read 2026-09-26.
If your agent or app…	Use
Calls a saved recipe from a backend	The Format API over HTTP or the SDK
Runs the agent on a one-off task from a backend	Agent Completions over HTTP
Runs the same task on a cadence	Scheduled, authored in the dashboard; no MCP tool or CLI command
Is Cursor, Claude Code, Codex, or another remote MCP client	Hosted MCP, signed in with OAuth
Speaks remote MCP but not OAuth	Hosted MCP with an API key
Is a local agent that can run shell commands	Direct CLI commands after `sume login`

Which capabilities work over MCP, the CLI, or HTTP?

Hosted MCP is not full parity with the HTTP API, and the CLI's generation coverage is narrower still: paid Avatar generators are the only first-class generation submit path in the CLI today. Hosted MCP tools wrap public API capabilities, so every row below is also reachable over HTTP.

Image 1.0 and Video 1.0 are retiring soon. New integrations send POST /v1/images or POST /v1/videos with model: "sume/auto", shell agents included, even though the CLI docs still show the Image 1.0 route (migration guide).

From MCP overview, MCP tools and gates, CLI command reference, and CLI generation workflows, read 2026-09-26.
Capability	Hosted MCP	CLI
Image, video, and music generation	`generate_image`, `generate_video`, `music_create`	No subcommand. Submit over HTTP, then recover with `sume jobs`
Speech, upscaling, background removal, video editing	`tts_create`, `stt_create`, `image_upscale_create`, `video_upscale_create`, `rmbg_create`, `video_trim`, `video_filter`, `timeline_*`	No submit command
Avatars and avatar videos	`avatars_create`, `avatar-videos_create`	`sume avatars create`, `sume avatar-videos create`
Jobs	`jobs_status`, `jobs_wait`, `jobs_result`	`sume jobs status`, `result`, `watch`, `download`
Account, balance, usage, catalog	`account_me`, `balance_get`, `usage_get`, `catalog_list`	`sume account get`, `sume balance`, `sume usage get`, `sume catalog list`

How should a shell agent use the CLI?

When the agent can run shell commands on your machine, the docs prefer direct CLI commands: sume login, sume tools list --json, Avatar submits, and sume jobs … for recovery. The --confirm-paid and --confirm-submit write gates and the redacting --agent --json output are covered in the CLI tutorial. Two points matter for the choice itself:

CLI tool ids stay dotted (avatars.create). That registry is not the hosted MCP catalog.
Bundled agent skills: sume skills install writes the packaged Sume skill into .agents/skills or .claude/skills, and sume skills export sume lets you review the source files first.

sume login
sume tools list --json
sume skills export sume
sume skills install
sume jobs status <job_id> --agent --json

What changes when the agent uses hosted MCP?

The tool set comes from the session, not from the HTTP reference. tools_list and tools_schema show which tools the current session has, and catalog_list can still show HTTP capabilities that have no matching MCP tool. Credentials do not carry over either: CLI login and hosted MCP OAuth are different flows, so sume login does not mint hosted MCP tokens.

OAuth sessions start read-only until the user turns Write on at consent; sign-in, scopes, and client setup are in Connect Claude Code, Cursor, or Codex to Sume, and the gates every paid call keeps are in Safe automation for AI agents that call paid APIs. The grouped inventory is in Sume MCP tools list.

What can't MCP or the CLI do today?

These gaps send an agent back to HTTP or the dashboard:

Run schedules. Scheduled has no MCP tool and no CLI command.
Call Image 1.0 or Video 1.0 (images_create, videos_create) over MCP. Both are REST-only and retiring soon.
Generate images, video, or music from a CLI subcommand. The docs say not to invent those commands.

Sources

Written by Sume