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 Phase 1	Client follows MCP OAuth / protected-resource metadata and Sume consent	Read-only tools. Scope: `mcp:read`.
API key	Client sends `Authorization: Bearer <SUME_API_KEY>` or `x-api-key`	Full hosted tool set, still gated by write/paid flags.
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.
The client sends the user to Sume authorization on app.sume.com.
The user signs in and approves read-only Sume MCP access.
The client exchanges the authorization code (PKCE) for an access token.
The client calls https://mcp.sume.com/mcp with that bearer token.

Useful public metadata endpoints:

OAuth resource audience:

Phase-1 OAuth limits

Already shipped platform behavior:

Supported scope: mcp:read
OAuth sessions only see read-only tools
Write and paid tools return insufficient_scope (required scope conceptually mcp:write / paid scopes are not granted in Phase 1)
Passing allow_write / allow_paid does not bypass OAuth scope limits

Phase 2 (not enabled yet): explicit mcp:write / mcp:paid consent. Until then, use an API key remote MCP session or the Developer API for mutations and paid generation.

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, but execution still requires:

allow_write=true and idempotency_key for mutating tools
allow_paid=true, max_spend_usd, and idempotency_key for paid generation
Prefer dry_run=true before the first paid submit

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/Video/Music via MCP today?	Not on hosted MCP — use the Developer API (Image, Video, Music).
Is Studio Agent the same as hosted MCP?	No. Studio Agent is a separate product surface.