Connect a new MCP client to Sume: five calls that prove it works

Point your client at https://mcp.sume.com/mcp, finish the OAuth sign-in (or send an API key), and then run five read-only calls in order: mcp_health, tools_list, tools_schema, account_me and catalog_list. If all five answer correctly the session is set up, and you have not spent anything. This is the setup check for a client you have not used with Sume before.

Add the server and sign in

The production URL is the only one customer configs should use. Claude Code adds it with claude mcp add --transport http. Cursor takes an mcpServers entry with a url, and Codex or any streamable-HTTP client takes the same URL in its server config. When the client starts OAuth it reads the protected-resource metadata from the MCP endpoint, then sends you to https://mcp.sume.com/oauth/authorize, which continues to the consent page on the MCP host, not on app.sume.com. If a client cannot complete the flow, the two metadata documents below are the first thing to fetch.

claude mcp add --transport http sume https://mcp.sume.com/mcp
claude mcp login sume

# Discovery documents the client reads before it sends you to consent:
curl -s https://mcp.sume.com/.well-known/oauth-protected-resource/mcp
curl -s https://mcp.sume.com/.well-known/oauth-authorization-server

The five calls

Ask the agent to call each tool by name, or call them from your client's tool inspector. The live tool ids use underscores; dotted aliases such as tools.list are canonicalized to the underscore names.

Read the result for the right scope

By default hosted OAuth grants mcp:read. A read-only session sees only read-only tools, and a call to a write or paid tool such as generate_image, avatars_create or jobs_cancel returns insufficient_scope. That is correct behavior, not a broken connection. To run write or paid tools, grant mcp:write on the consent page by turning the Write toggle on, or use an API-key session. There is no mcp:paid scope.

tools_list is the honest view of what this session can do. A tool that is in catalog_list but not in tools_list is not available over MCP at all, for example images_create and videos_create, which are REST-only.

Common ways the session looks broken

Most failed first connections come down to four things. The client was given a development URL instead of the production one, so use https://mcp.sume.com/mcp. The sign-in was never finished, so the server answers with an OAuth challenge instead of tools. The consent was granted without Write, so write tools are hidden and paid calls fail with insufficient_scope. Or an API key and an OAuth token were mixed up; they are different credentials and one cannot stand in for the other.

If the client supports only API keys, send Authorization: Bearer $SUME_API_KEY or x-api-key: $SUME_API_KEY as a header on the server entry, never both at once. A key session sees the full tool set, and writes and paid calls still need an idempotency_key.

Before the first paid call

Every write and paid tool needs an idempotency_key. Before the first real spend, read the tool contract with tools_schema, then call the tool with dry_run: true or call generation_admission_preview to see the estimate, the balance and the queue behavior. If you want a hard cap, add max_spend_usd; Sume enforces it only when you provide it. After a real submit, use jobs_status or jobs_wait and then jobs_result.

Do not paste an API key or an OAuth token into the chat. If a key does appear in logs or history, rotate it. Keep the first paid test small, for example a single image, so that the result you read back with jobs_result costs you cents while you confirm that the whole path works from submit to media URL.