|Docs

MCP server

sume mcp starts a local stdio MCP server from the same Sume CLI binary. It uses the same auth/config as the CLI: SUME_API_KEY, SUME_API_BASE_URL, or a key saved by sume login.

Start the default server

Default MCP is read-only. It exposes account, brand read, avatar read, jobs, assets, and schema tools.

Default read tools

The default toolsets are:

Common default tools include:

  • account.me
  • credits.get
  • brand.list, brand.current, brand.get
  • avatars.list, avatars.get
  • jobs.list, jobs.get, jobs.result, jobs.wait
  • assets.search, assets.get
  • tools.list, tools.schema

Use schema discovery before calling tools:

Toolsets

Select toolsets explicitly:

read expands to the default read toolsets.

Non-paid write tools

Mutating non-paid tools are hidden unless the selected toolset is enabled with --allow-write:

These gates expose selected tools such as:

  • brand.analyze
  • uploads.asset_video
  • jobs.download

uploads.asset_video reads exactly one supplied local video path, presigns, uploads bytes internally, finalizes Asset Library upload, and returns a sanitized summary. It does not return the signed upload URL, upload headers, or storage object key.

jobs.download downloads safe public media URLs from an existing job result to an explicit local output directory. It returns local basenames/relative paths, not remote URLs.

Paid/provider tools

Paid/provider tools are hidden unless the selected toolset is enabled with --allow-paid:

generation exposes:

  • images.generate
  • videos.generate
  • reference-analysis.create

ads,face-swap exposes:

  • ads.videos.create
  • face-swap.create

Only expose paid toolsets inside MCP hosts that have a clear human approval model. Do not enable paid tools just for read-only browsing or planning.

MCP client configuration

Local stdio example:

Do not pass API keys as command-line arguments. Prefer environment variables or local Sume config.

Schema metadata

sume tools list --json and sume tools schema <tool> --json include safety metadata:

  • read-only vs mutating;
  • paid/provider call status;
  • sensitive URL behavior;
  • MCP executable status;
  • MCP toolset;
  • required --allow-write or --allow-paid gate.

Agents should use this metadata to decide whether to ask for confirmation.

Result sanitization

MCP outputs are designed for agent use. They should not expose:

  • API keys;
  • raw signed upload URLs;
  • upload headers;
  • storage object keys;
  • full private media URLs;
  • raw provider internals;
  • user/workspace ids or emails unless required by the public API response.

Still treat all job, media, and account outputs as user data. Summarize instead of pasting large raw payloads into chat.