Sume MCP insufficient_scope: why it happens and the two ways to fix it

insufficient_scope means your OAuth session holds mcp:read and the tool you called changes data or spends money. Reconnect and switch the Write toggle on at the consent page on the MCP host, or use an API-key session. There is no mcp:paid scope to request, so asking for one will not help.

Which calls trip it

Read tools such as jobs_list, assets_get, catalog_list and crawl_scrape work under read. Write tools like jobs_cancel and assets_create fail, and so do paid tools like generate_image or avatars_create. Hosted MCP also hides those tools from tools_list until the session has write, so an agent may report a missing tool before it ever sees the error.

Fix 1: re-consent with Write

Disconnect the server in your client and connect again. The client sends you to https://mcp.sume.com/oauth/authorize, which continues to the consent page. Read is locked on and Write is off by default. Turn Write on and continue. A write grant always includes read.

• Use this for interactive clients where a person can see the consent page.
• Check the result with mcp_health; authenticated.auth_source should read mcp_oauth.
• Call tools_list again; the write and paid tools should now be listed.

Fix 2: an API key

For automation, send Authorization: Bearer or x-api-key with a key from the dashboard. Do not mint a key just to patch an OAuth client; the docs say not to do that. Do not paste a key into chat, and rotate any key that reaches a log.

What the fix does not remove

A write session still needs an idempotency_key on each paid or write call. dry_run and max_spend_usd stay optional, and the legacy allow_write and allow_paid flags cannot bypass a missing mcp:write grant.

Telling the two causes apart

Call mcp_health first. If authenticated.auth_source is mcp_oauth and the tool list lacks write tools, the session is read-only. If the source is an API key, insufficient_scope should not appear, and the failure is something else, such as a missing idempotency_key or insufficient balance.

Give most agents the read-only grant and keep write sessions for tasks where a person confirmed the spend. A read-only agent can still inspect jobs, assets and the catalog, and can preview cost with generation_admission_preview, which is often all a reviewing assistant needs.

Do not respond to this error by retrying the same call. The scope will not change on its own, and repeated attempts only add noise to your logs. The agent should stop, tell the user which scope is missing, and wait. For a scheduled job, fail the run with a clear message that says to re-consent or use a key. That keeps a human in the loop for the decision to allow spend, which is the point of the read-only default.

Keep in mind that Sume's hosted endpoint is the same for every client in this series: https://mcp.sume.com/mcp, with OAuth consent on the MCP host or an API key in a header. What differs is each client's config keys, its timeout defaults and its approval prompts. When a connection misbehaves, first separate those two layers: test the endpoint with curl and your credential, and only then look at the client's settings.