Claude Agent SDK MCP server: connect Sume with an API key

To use Sume's hosted MCP server from the Claude Agent SDK, add an http server for https://mcp.sume.com/mcp under mcpServers with your Sume API key in an Authorization: Bearer header, then name the exact mcp__sume__… tools the agent may call in allowedTools, leaving paid tools out until a run is meant to spend.

The SDK behavior comes from Claude's Connect to external tools with MCP and environment variables pages; the Sume side comes from OAuth and API keys, MCP tools and gates, and Jobs and results, all read on 2026-09-27. Sume has no official Agent SDK integration; this is the SDK's own MCP client. Sume's basics page says hosted MCP still works but is not part of the primary path today. For the interactive Claude Code CLI with OAuth, see Connect Claude Code, Cursor, or Codex to Sume.

Why use an API key instead of OAuth?

The Agent SDK does not open a browser or run an interactive OAuth flow. When a server returns an authorization challenge and no token is stored, the run continues without that server's tools, and the server reports needs-auth. Sume's hosted OAuth begins with that kind of challenge, plus protected-resource metadata. Claude's docs leave OAuth to your own application: complete the flow there and pass the access token in headers.

For unattended runs, Sume's docs call API-key remote MCP the other path, for automation that does not speak OAuth; OAuth stays their recommendation for interactive clients. Send Authorization: Bearer $SUME_API_KEY or x-api-key. An API-key session sees the full hosted tool set, paid tools included, and Sume's docs say to rotate a key that appears in logs or chat history.

How do I configure the server?

Pass the server in mcpServers with type: "http", the SDK's type for the streamable HTTP transport, and read the key from the environment. Tool names follow mcp__<server-name>__<tool-name>, so the server key sume turns generate_video into mcp__sume__generate_video:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Check my Sume balance, then preview admission for a 5-second 9:16 clip.",
  options: {
    mcpServers: {
      sume: {
        type: "http",
        url: "https://mcp.sume.com/mcp",
        headers: { Authorization: `Bearer ${process.env.SUME_API_KEY}` },
      },
    },
    allowedTools: [
      "mcp__sume__mcp_health",
      "mcp__sume__tools_schema",
      "mcp__sume__balance_get",
      "mcp__sume__generation_admission_preview",
      "mcp__sume__jobs_wait",
      "mcp__sume__jobs_result",
    ],
  },
})) {
  if (message.type === "result" && message.subtype === "success") console.log(message.result);
}

Which Sume tools should allowedTools list?

MCP tools need explicit permission: without it, Claude sees them but cannot call them. allowedTools auto-approves the names it lists. Claude's docs prefer it over permission modes, because bypassPermissions auto-approves MCP tools but also disables most other safety prompts. A wildcard such as mcp__sume__* would approve every Sume tool, paid ones included, so list names one by one.

How do I dry-run a paid call first?

Sume's spend gates are arguments on the tool call. idempotency_key is required on every write and paid tool; it is a stable key for transport and dedup, not human approval. dry_run=true previews admission and cost without submitting the job, and max_spend_usd is enforced only when you pass it. Estimating cost before a Sume job covers what a preview tells you.

In the SDK, allowedTools decides which of those calls can run at all. generation_admission_preview, already in the list above, previews admission while generate_video stays unapproved. dry_run is an argument on the paid tool itself, so dry-running generate_video means adding mcp__sume__generate_video to allowedTools, and that entry approves a real submit too. Sume's playbook for a paid create is meant for when the user explicitly confirms spend: call once with dry_run=true, repeat with dry_run omitted or false to submit, then wait with jobs_wait and read jobs_result. The docs' example arguments, for avatars_create:

{
  "idempotency_key": "avatar-create-2026-07-21-001",
  "dry_run": true,
  "max_spend_usd": 2,
  "payload": {
    "avatar_handle": "studio_presenter",
    "input": {
      "type": "prompt",
      "prompt": "A friendly studio presenter in neutral lighting"
    }
  }
}

How long can a Sume tool call run?

Claude Code's defaults already fit Sume's waits:

• Each request to an HTTP MCP server times out after 60 seconds by default. MCP_TOOL_TIMEOUT, in milliseconds, raises that limit when set above 60000.
• A tool call on a network server that gets no response and no progress notification for 5 minutes aborts (CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT), which is longer than one Sume wait.
• Sume's jobs_wait holds one call for at most 55 seconds, 50 by default. On wait_slice_expired, call it again with the same ids; never resubmit the paid create.
• Server startup times out after 30 seconds by default (MCP_TIMEOUT).
• A tool result with no image content that is larger than 25,000 tokens is saved to a file and replaced with an error message that names the file path.

How do I check the connection?

The init system message reports each server's status: pending, connected, failed, needs-auth, or disabled. needs-auth on sume means the server asked for authorization, so check that the header reached it. The init message can still show pending for a server that needs credentials; mcpServerStatus() in the TypeScript SDK confirms it. Once the server is connected, have the agent call mcp_health, which confirms the endpoint, the auth source, and the safety posture.