Fix MCP insufficient_scope on Sume: scopes, missing tools, timeouts

On Sume's hosted MCP server, insufficient_scope means an OAuth session with only mcp:read called a tool that writes or spends. Run the client's OAuth login again and turn Write on at consent to grant mcp:write, or switch to an API-key session. Call mcp_health first: it shows which credential and scopes the session actually has.

The fixes come from the MCP quickstart, MCP OAuth and API keys, MCP tools and gates, and Jobs and results, read on 2026-09-26. Fields described as current come from the hosted server's code. The basics page says the CLI and hosted MCP at https://mcp.sume.com/mcp still work but are not part of the primary integration path today. First-time setup is in Connect Claude Code, Cursor, or Codex to Sume.

What should I check first?

Call mcp_health. It reports endpoint readiness, auth source, and safety posture, which separates a credential problem from a tool problem. Under OAuth, authenticated.auth_source is mcp_oauth. The response currently also carries:

• authenticated.credential: its type, oauth_access_token or api_key, and its scopes.
• tools: the tool names this session exposes.
• safety: the posture, such as paid_tools_require_idempotency_key: true and signed_urls_returned: false.
• Its tool description also says a single failed call is not a connectivity problem: retry that call before you debug the connection.

Why do I get insufficient_scope?

Because the Write toggle on the consent page defaults to off, a default OAuth session holds only mcp:read, and every write or paid tool answers insufficient_scope; which tools each session can call is in Connect Claude Code, Cursor, or Codex to Sume. The tool error currently reads Sume MCP OAuth token is missing mcp:write scope., with required_scope set to mcp:write.

The quickstart gives three fixes:

• Grant mcp:write on consent. Run the client's OAuth login again and turn Write on; the granted scopes currently come from that toggle, not from what the client asked for.
• Use an API-key session, which sees the full hosted tool set. Send Authorization: Bearer $SUME_API_KEY or x-api-key, one of them and not both.
• Use the Developer API or the CLI for that write.
• What does not work: requesting an mcp:paid scope, which does not exist (the authorize request fails with invalid_scope), or sending the legacy allow_write and allow_paid flags, which cannot bypass a missing mcp:write scope.

Why is a tool missing, or unable to open my file?

Match the symptom to the cause. The live tool ids are the underscore names in tools_list, and dotted aliases still work.

Why does consent open on the wrong site?

Consent lives on the MCP host: https://mcp.sume.com/oauth/authorize continues to https://mcp.sume.com/oauth/consent, not app.sume.com. www.sume.com is a deprecated authorization-server surface that the metadata no longer advertises. Point the client at https://mcp.sume.com/mcp and let it discover the protected-resource metadata from that endpoint.

Two more credential traps: sume login does not mint hosted MCP OAuth tokens, and an MCP OAuth token is not a Sume API key, so it does not belong in CLI config. Access tokens currently last one hour, with no refresh token, and an expired token gets the same 401 challenge as a missing one: a session that worked an hour ago needs a new sign-in. See how the MCP OAuth flow works.

What do I do when a call times out?

On remote MCP, one jobs_wait call holds at most 55 seconds and defaults to 50. A long render outlives many waits, and a wait that ends does not end the job, which keeps running and billing:

• On wait_slice_expired, call jobs_wait again with the same ids. Never resubmit the paid create.
• A 524 (or 522, 523, 525) on jobs_wait is a transport failure, never a job outcome. Re-issue the wait on the same ids, or read jobs_status once.
• Batch waits and results are in MCP tool call timeouts on long-running video jobs.