Cloudflare Agents addMcpServer for Sume: streamable-http and headers

Cloudflare's Agents SDK can hold MCP connections inside an agent. The MCP client API page documents addMcpServer(name, url, options) with a callbackHost and a transport of type streamable-http, sse or auto (the default) plus headers, read 2026-10-03. The call returns either {state: "authenticating", authUrl} or "ready". Sume's hosted MCP server is Streamable HTTP at https://mcp.sume.com/mcp, so an explicit streamable-http removes the guesswork.

Connecting with a key

Sume accepts an API key as Authorization: Bearer or x-api-key, per the Sume MCP overview. Send one. The snippet reads the key from a Worker secret. With a valid key the call should return a ready state; the Cloudflare page does not say what your result looks like for a key that Sume rejects, so log it.

async onStart() {
  const res = await this.addMcpServer(
    "sume",
    "https://mcp.sume.com/mcp",
    {
      transport: {
        type: "streamable-http",
        headers: { Authorization: `Bearer ${this.env.SUME_API_KEY}` },
      },
    }
  );
  if (res.state === "authenticating") console.log(res.authUrl);
}

What persists

The page says connections persist in the agent's SQL storage and survive hibernation, and that removeMcpServer(serverId) drops one. That matters for long jobs: an agent can hibernate while a Sume job runs. Store the job id in the agent's state the moment a create tool returns it, then call jobs_wait after wake-up. Do not re-run the create; paid and write tools need an idempotency_key and a retry without the same key is a new charge.

Keep the waits honest

• jobs_wait holds 50 seconds by default and 55 at most; values above are clamped with wait_slice_clamped.
• On wait_slice_expired, ask again with the same ids.
• A 524, 522, 523 or 525 is transport, not a job result.
• Use jobs_result with job_ids to read several finished jobs at once.