MCP OAuth and API keys

Hosted Sume MCP accepts OAuth access tokens or Sume API keys. You cannot use one of these credentials in place of the other.

Auth matrix

Mode	How you connect	Hosted capability today
OAuth	The client uses MCP OAuth / protected-resource metadata and first-party consent on the MCP host	`mcp:read` is required and read-only. To also grant `mcp:write`, toggle Write on the consent page. There is no `mcp:paid` scope.
API key	The client sends `Authorization: Bearer <SUME_API_KEY>` or `x-api-key`	Full hosted tool set. Spend is wallet/admission. Writes and paid calls must include `idempotency_key`.
Local `sume mcp`	Future CLI MCP after `sume login` or local key	Not launched yet (`sume mcp doctor` → `coming_soon`). It is separate from hosted OAuth.

OAuth flow (hosted)

The MCP client connects to https://mcp.sume.com/mcp.
Sume returns an OAuth challenge and protected-resource metadata (authorization_servers is the MCP origin, not www / app.sume.com).
The client sends the user to https://mcp.sume.com/oauth/authorize. This URL redirects to the first-party consent page GET /oauth/consent on the MCP host (Clerk browser JS on that origin).
After sign-in, the consent page shows Permissions: Read is locked on, and the Write toggle is off by default. Continue posts to POST /oauth/consent/decision.
The client exchanges the authorization code (PKCE) for an access token.
The client calls https://mcp.sume.com/mcp with that bearer token.

www.sume.com is still a secondary/deprecated authorization-server surface. The protected-resource metadata does not advertise it now. Do not send interactive clients to app.sume.com for MCP OAuth.

Useful public metadata endpoints:

OAuth resource audience:

Development uses the same shape on https://mcp.dev.sume.com.

Scopes

Already shipped (packages/mcp-oauth + packages/mcp-server/src/mcp-oauth-as.ts):

Supported scopes: mcp:read (required) and mcp:write (opt-in). A grant of write always includes read.
There is no mcp:paid OAuth scope. Paid submits are wallet/admission.
mcp:read sessions see only read-only tools. If a session without write calls a tool that changes data, the call returns insufficient_scope.
mcp:write sessions see the tools that change data and the paid tools.
Paid/write submits must include idempotency_key (transport/dedup). The optional dry_run preflights cost. Sume enforces the optional max_spend_usd only when you provide it.
Sume accepts the legacy allow_write / allow_paid for back-compat. They are not required. They cannot bypass a missing mcp:write scope.

API-key remote MCP is the other path for automation that does not use OAuth.

API-key remote MCP

API-key compatibility is still available for current users and automation.

Send one of these:

API-key sessions can see write and paid tools. Calls that change data and paid calls must still include idempotency_key. Before the first paid submit, we recommend dry_run=true or generation_admission_preview. If you pass the optional max_spend_usd, it sets the maximum spend.

Create keys in the dashboard: API keys.

Credential safety

An MCP OAuth token is not a Sume API key.
Do not store OAuth tokens in CLI config. Do not paste them into prompts. Do not forward them to third-party providers.
Do not mint API keys for hosted OAuth clients as a workaround.
sume login does not broker hosted MCP OAuth tokens.
If API keys appear in logs or chat history, rotate the keys.

Hosted MCP vs local MCP vs Studio Agent

Question	Answer
Best interactive connector for Cursor/Claude?	Hosted MCP + OAuth at `https://mcp.sume.com/mcp`.
Best for local shell agents already on the CLI?	Direct CLI commands after `sume login` (local `sume mcp` is not launched yet).
Need Image 1.0 / Video 1.0 (`images_create` / `videos_create`)?	Not on hosted MCP. Use the Developer API. Router stills/clips are `generate_image` / `generate_video`.
Is Studio Agent the same as hosted MCP?	No. Studio Agent is a separate product surface.