OpenHands MCP server: add Sume as a Streamable HTTP server

In current OpenHands, add Sume as a Streamable HTTP (SHTTP) server with the URL https://mcp.sume.com/mcp and a Bearer token set to a Sume API key. Do it in Agent Canvas under Customize, MCP Servers, in the CLI's ~/.openhands/mcp.json, or by passing mcp_config to the SDK. Do not use a config.toml [mcp] section: OpenHands' own docs say current releases do not read it.

That last point trips up a lot of older guides, which show shttp_servers in TOML. Here is what the OpenHands page says today and how it maps to Sume.

What does OpenHands require for a remote server?

From the OpenHands MCP settings page, read on 2026-10-02: an SHTTP server needs a name and a URL beginning http:// or https://, plus an authentication choice (none, Bearer token, header or OAuth) and an optional timeout, which the page says to raise for servers whose tools run heavy operations. The page calls Streamable HTTP the recommended transport for remote servers. Sume's hosted endpoint is Streamable HTTP, so it fits without a bridge.

Why a bearer key and not OAuth?

OpenHands lists OAuth with client ID, secret and scopes, and warns that OAuth servers require user interaction for the initial authentication, so they are unsuitable for fully automated workflows. Sume's OAuth has the same property by design: a person signs in on the MCP host's consent page and decides whether to switch Write on (OAuth and API keys).

A coding agent that runs without you needs a credential that does not wait for a browser. Sume accepts Authorization: Bearer <SUME_API_KEY> or x-api-key, and an API-key session sees the full hosted tool set. The cost of that convenience is that nothing is read-only any more: paid tools are visible from the first call. Store the key through the encrypted settings in Agent Canvas rather than in a repo file.

What does a coding agent do with Sume's tools?

OpenHands agents work inside a sandbox and a repository, so the useful Sume jobs are assets for the project: a hero image, a short clip, a cutout, a voiceover. One limit shapes the workflow. Sume's docs state that hosted MCP cannot read files from your machine. Uploading means asking for an upload URL, having the client PUT the bytes, then calling assets_complete, so the agent should use assets_upload_url from its own shell rather than hoping a tool reads a path (MCP tools and gates).

• Generation: generate_image, generate_video, tts_create, music_create, each needing an idempotency_key.
• Cutouts and upscales: rmbg_create, image_upscale_create, video_upscale_create.
• Reading results: jobs_wait then jobs_result, which returns durable media.sume.com URLs the agent can download into the repo.

How do you keep an unattended run from overspending?

There is no approval prompt in an unattended OpenHands run, so lean on Sume's gates and say so in the task. Ask for generation_admission_preview or dry_run=true before any burst. Pass max_spend_usd, which Sume enforces only when it is present. Require a stable idempotency_key per intent, so a retry after a dropped connection returns the original receipt instead of billing twice.

For waiting, one jobs_wait call holds at most 55 seconds and may answer wait_slice_expired. The agent should call it again with the same job ids, and should never resubmit the create (Jobs and results). Up to 20 ids go in a single call, which suits an agent generating a set of images in one task.

Test the connection with something free before a paid task: ask the agent to call mcp_health and tools_list. If the tools do not appear, check the URL first, because OpenHands requires a full http:// or https:// address, and then the token field, since a key pasted with stray whitespace or a doubled Bearer prefix fails authentication.