MCP read-only OAuth session: which Sume tools you do and do not see

When you connect Cursor, Claude Code or another client to https://mcp.sume.com/mcp with OAuth and leave the Write toggle off at consent, the session has only mcp:read. Hosted MCP then hides the tools that change data and the paid tools, and a call to one returns insufficient_scope. There is no mcp:paid scope: paid submits go through wallet and admission once the session has write access.

So if tools_list does not show generate_image, the session is probably read-only, not broken. Check mcp_health first: authenticated.auth_source should be mcp_oauth.

Getting write access

Reconnect and turn the Write toggle on at consent, or use an API-key remote session. Write always includes read. The legacy allow_write and allow_paid fields are accepted for back-compat, are not required, and cannot bypass a missing mcp:write scope.

The consent page is on the MCP host, not app.sume.com. The client discovers the protected-resource metadata, is sent to https://mcp.sume.com/oauth/authorize, then to /oauth/consent, and finishes with a PKCE code exchange.

Read-only is a good default

Most exploratory work needs only reads. tools_list, tools_schema, account_me, balance_get, catalog_list, jobs_list and jobs_status let an agent inspect the account and the jobs without being able to spend. The docs' Playbook A stops before any tool that changes data when Write is off.

• Call mcp_health and confirm the auth source.
• Call tools_list once; with Write off, only read_only tools appear.
• Call tools_schema with a name to read one contract before you request write access.
• If you later need jobs_cancel or generate_image, grant mcp:write deliberately.

Do not work around it

The docs are explicit: an MCP OAuth token is not a Sume API key, and you should not mint API keys for hosted OAuth clients as a workaround. If the agent needs to spend, grant write at consent and keep idempotency_key, dry_run and max_spend_usd in the instructions.

A short checklist

Before you debug, answer three questions. Did the consent page show Write on? Does mcp_health report mcp_oauth as the auth source? Does tools_list include the tool at all? If the tool is missing and Write was off, the cause is scope, not a bug.

When you do grant write, expect to reconnect, because the scope belongs to the grant the client holds. Use tools_schema for the paid tool you want and read its idempotency_key and dry_run fields first, so the first paid call is a preview.

Treat this as a habit, not a one-time fix. Write the rule down next to the code that calls the API, add a test that exercises it, and review it whenever the docs change. Check the linked documentation pages in the sources list for the current wording before you rely on any number here, because limits and field names can be revised, and a short test run costs far less than debugging a production incident.

When something does not match what you read here, capture the x-sume-request-id response header and the job or run id, and send those to support. Do not paste API keys, signing secrets or full request bodies into a ticket or a chat; the ids are enough for the team to find the request.