---
title: MCP OAuth and API keys
description: Hosted MCP authentication matrix and Phase-1 OAuth limits.
---

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)

1. The MCP client connects to `https://mcp.sume.com/mcp`.
2. Sume returns an OAuth challenge and protected-resource metadata.
3. The client sends the user to Sume authorization on `app.sume.com`.
4. The user signs in and approves **read-only** Sume MCP access.
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.

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

## 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:

```bash
# Bearer
Authorization: Bearer $SUME_API_KEY

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

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](/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/Video/Music via MCP today? | Not on hosted MCP — use the Developer API ([Image](/models/image), [Video](/models/video), [Music](/models/music)). |
| 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)