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 prices them 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) and sends you to https://mcp.sume.com/oauth/authorize.
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.
   • 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, a reused one ends the connection, and one unused for 30 days expires. To end a connection, send its refresh token to /oauth/revoke; the next request with its access token fails.

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.

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 only read-only tools. A tool that changes data returns insufficient_scope. On the HTTP API, a read-only sign-in may only read.
• An mcp:write connection sees the tools that change data and the paid tools.
• Paid and write calls must include idempotency_key. dry_run previews the price without running anything; max_spend_usd caps a call 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. 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