MCP OAuth and API keys

Hosted Sume MCP accepts either OAuth access tokens or Sume API keys. They are not interchangeable credentials.

Auth matrix

Mode	How you connect	Hosted capability today
OAuth	Client follows MCP OAuth / protected-resource metadata and first-party consent on the MCP host	`mcp:read` is required and read-only. Toggle Write on consent to also grant `mcp:write`. There is no `mcp:paid` scope.
API key	Client sends `Authorization: Bearer <SUME_API_KEY>` or `x-api-key`	Full hosted tool set. Spend is wallet/admission; `idempotency_key` is required on writes/paid.
Local `sume mcp`	Future CLI MCP after `sume login` or local key	Not launched yet (`sume mcp doctor` → `coming_soon`). 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, which redirects to the first-party consent page GET /oauth/consent on the MCP host (Clerk browser JS on that origin).
After sign-in, consent shows Permissions: Read locked on; Write toggle default off. 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 remains a secondary/deprecated authorization-server surface; protected-resource metadata no longer advertises it. 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). Granting write always includes read.
There is no mcp:paid OAuth scope. Paid submits are wallet/admission.
mcp:read sessions only see read-only tools. Missing write on a mutating tool returns insufficient_scope.
mcp:write sessions see mutating and paid tools.
idempotency_key is required on paid/write submits (transport/dedup). Optional dry_run preflights cost. Optional max_spend_usd is enforced only when provided.
Legacy allow_write / allow_paid are accepted for back-compat and are not required. They cannot bypass a missing mcp:write scope.

API-key remote MCP remains the other path for automation that does not speak OAuth.

API-key remote MCP

API-key compatibility remains available for existing users and automation.

Send either:

API-key sessions can see write and paid tools. Execution still requires idempotency_key on mutating/paid calls. Prefer dry_run=true or generation_admission_preview before the first paid submit. Optional max_spend_usd caps spend when you pass it.

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, paste them into prompts, or 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.
Rotate API keys if they appear in logs or chat history.

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