---
title: MCP OAuth and API keys
description: Hosted MCP authentication matrix and mcp:read / mcp:write scopes.
---

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)

1. The MCP client connects to `https://mcp.sume.com/mcp`.
2. Sume returns an OAuth challenge and protected-resource metadata
   (`authorization_servers` is the MCP origin, not `www` / `app.sume.com`).
3. 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).
4. After sign-in, consent shows **Permissions**: Read locked on; Write toggle
   default off. Continue posts to `POST /oauth/consent/decision`.
5. The client exchanges the authorization code (PKCE) for an access token.
6. 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:

```text
https://mcp.sume.com/.well-known/oauth-protected-resource/mcp
https://mcp.sume.com/.well-known/oauth-authorization-server
```

OAuth resource audience:

```text
https://mcp.sume.com/mcp
```

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:

```bash
# Bearer
Authorization: Bearer $SUME_API_KEY

# or header
x-api-key: $SUME_API_KEY
```

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](/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](/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. |

## Related

- [MCP overview](/mcp)
- [MCP quickstart](/mcp/quickstart)
- [Tools and gates](/mcp/tools-and-gates)
- [CLI overview](/cli)
- [Authentication](/authentication)