Sign-in (OAuth) and API keys

People sign in to Sume once, with OAuth, from an MCP client or from the sume CLI. Scripts use Sume API keys. The two never stand in for each other.

Auth matrix

There is no mcp:paid scope. Paid calls are checked against the workspace balance, need an idempotency_key, and dry_run: true prices them in dollars first.

MCP sign-in

1. The MCP client connects to https://mcp.sume.com/mcp.
2. Sume answers with an OAuth challenge and protected-resource metadata. Its authorization_servers is https://mcp.sume.com.
3. The client registers (Dynamic Client Registration, or an https:// client ID metadata document, as ChatGPT does; Sume accepts a document that offers the none token method and swaps codes with PKCE, no client secret) and sends you to https://mcp.sume.com/oauth/authorize. The redirect must match a registered one. A loopback redirect (http://127.0.0.1, http://localhost or http://[::1]) matches on any port.
4. You sign in. The consent page names the app and the host it returns to.
   • Read is locked on. Create and spend credits is mcp:write. It starts on when the app asks for mcp:write or names no scope, and off when the app asks for mcp:read only. You can turn it on or off.
   • Workspace picks where the connection starts: your personal workspace or a team you belong to.
   • Allow returns a code to the app; Deny returns error=access_denied. Both carry iss=https://mcp.sume.com.
5. The app exchanges the code (PKCE) for a one-hour access token and a refresh token.
6. The app calls https://mcp.sume.com/mcp with the access token.

The app refreshes on its own. Each refresh token works once and gives the next one, and one unused for 30 days expires.

• To end a connection, send its refresh token to /oauth/revoke. The access token from that sign-in fails on the next request.
• Sending a refresh token that was already used ends the connection the same way, and the app must sign in again.
• When Sume's sign-in check is overloaded, /mcp and /v1 answer a valid token with 503, not 401. Retry the request; you do not need to sign in again.

To work in another workspace, ask the agent: list_workspaces shows your workspaces and select_workspace switches this connection. You do not need to reconnect. An API key belongs to one workspace, so select_workspace answers it with 409 workspace_fixed.

Public metadata:

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

Token audience for MCP clients:

https://mcp.sume.com/mcp

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

CLI sign-in

sume login            # opens the browser; the redirect comes back to 127.0.0.1
sume login --device   # prints a code to approve at mcp.sume.com/oauth/device
sume auth status      # how this machine signs in
sume auth token       # a current access token for a script
sume logout           # revokes the sign-in and removes it

sume login uses the same consent page as the MCP. It asks for resource=https://api.sume.com, so its token works on the HTTP API and not on mcp.sume.com/mcp. The CLI keeps the session in ~/.sume-com/config.json (readable only by you) and refreshes it itself.

Scopes

• mcp:read (required) and mcp:write (opt-in). A grant of write always includes read.
• An mcp:read connection sees the 17 read-only tools. A create or edit tool returns insufficient_scope. A tool that this host does not offer returns tool_not_found. On the HTTP API, a read-only sign-in may only read.
• An mcp:write connection sees the sign-in set of create and edit tools: 41 tools in all. Crawl, Avatar and the other API-key tools are not in it. Refer to Tools and gates.
• Paid and write calls must include idempotency_key. dry_run: true returns the price in dollars (usage.usd) without running anything; max_spend_usd caps a call in dollars when you send it.

API keys for scripts

Send one of these to https://api.sume.com/v1/… or to https://api.sume.com/mcp:

# Bearer
Authorization: Bearer $SUME_API_KEY

# or header
x-api-key: $SUME_API_KEY

https://mcp.sume.com/mcp is for people and answers an API key with 401 api_key_not_accepted. Create keys in the dashboard: API keys. A key made on the Open pages answers 403 open_key_route_not_allowed on /mcp. sume login --api-key saves a key for the CLI instead of signing in.

Credential safety

• A sign-in token is not an API key. Do not paste either into prompts or send them to third-party providers.
• sume auth token prints a token for your own scripts; it lasts one hour.
• If a key or token shows up in logs or chat history, revoke it: rotate the key, or run sume logout.

Hosted MCP vs CLI vs Studio Agent

Related

• MCP overview
• MCP quickstart
• Tools and gates
• CLI overview
• Authentication