Claude Agent SDK MCP 서버: API 키로 Sume 연결

Claude Agent SDK에서 Sume 호스팅 MCP 서버를 쓰려면 mcpServers 아래에 https://mcp.sume.com/mcp를 가리키는 http 서버를 추가하고 Authorization: Bearer 헤더에 Sume API 키를 넣으세요. 그런 다음 에이전트가 호출해도 되는 mcp__sume__… 도구를 allowedTools에 정확한 이름으로 적되, 실제로 지출할 실행이 아니라면 유료 도구는 빼 두세요.

SDK 동작은 Claude의 MCP로 외부 도구에 연결하기와 환경 변수 페이지에서, Sume 쪽 내용은 OAuth와 API 키, MCP 도구와 게이트, Job과 결과 (영문)에서 가져왔으며, 모두 2026-09-27에 확인했습니다. Sume에는 Agent SDK 전용 연동이 없습니다. SDK 자체의 MCP 클라이언트를 쓰는 방식입니다. Sume 기초 페이지는 호스팅 MCP가 여전히 동작하지만 현재 주 경로는 아니라고 설명합니다. OAuth로 인터랙티브 Claude Code CLI를 연결하는 방법은 Claude Code·Cursor·Codex를 Sume에 연결하기를 참고하세요.

OAuth 대신 API 키를 쓰는 이유는 무엇인가요?

Agent SDK는 브라우저를 열거나 인터랙티브 OAuth 플로를 실행하지 않습니다. 서버가 인가 챌린지를 반환했는데 저장된 토큰이 없으면, 실행은 그 서버의 도구 없이 계속되고 서버는 needs-auth 상태를 보고합니다. Sume의 호스팅 OAuth는 바로 그런 챌린지와 protected-resource 메타데이터로 시작합니다. Claude 문서는 OAuth를 직접 만든 애플리케이션에 맡깁니다. 그쪽에서 플로를 완료하고 액세스 토큰을 headers로 넘기라는 것입니다.

무인 실행이라면, Sume 문서는 API 키 원격 MCP를 OAuth를 쓰지 않는 자동화를 위한 다른 경로라고 설명합니다. 인터랙티브 클라이언트에는 여전히 OAuth를 권장합니다. Authorization: Bearer $SUME_API_KEY나 x-api-key를 보내세요. API 키 세션에는 유료 도구를 포함한 전체 호스팅 도구 세트가 보이며, Sume 문서는 로그나 채팅 기록에 노출된 키를 교체하라고 합니다.

서버는 어떻게 설정하나요?

mcpServers에 서버를 넘길 때는 SDK에서 streamable HTTP 트랜스포트를 뜻하는 type: "http"를 지정하고, 키는 환경 변수에서 읽으세요. 도구 이름은 mcp__<server-name>__<tool-name> 형식을 따르므로, 서버 키가 sume일 때 generate_video는 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);
}

allowedTools에는 어떤 Sume 도구를 넣어야 하나요?

MCP 도구에는 명시적 권한이 필요합니다. 권한이 없으면 Claude는 도구를 볼 수는 있어도 호출하지는 못합니다. allowedTools는 목록에 적은 이름을 자동 승인합니다. Claude 문서는 권한 모드 대신 allowedTools를 쓰라고 권하는데, bypassPermissions는 MCP 도구를 자동 승인하지만 다른 안전 프롬프트도 대부분 꺼 버리기 때문입니다. mcp__sume__* 같은 와일드카드는 유료 도구를 포함한 모든 Sume 도구를 승인하게 되므로, 이름을 하나씩 적으세요.

유료 호출은 어떻게 먼저 dry-run하나요?

Sume의 지출 게이트는 도구 호출의 인자입니다. idempotency_key는 모든 쓰기·유료 도구에 필수이며, 사람의 승인이 아니라 전송/중복 제거를 위한 고정 키입니다. dry_run=true는 Job을 제출하지 않고 접수 여부와 비용을 미리 보여 주며, max_spend_usd는 값을 넘긴 경우에만 강제됩니다. 프리뷰가 무엇을 알려 주는지는 AI 영상 비용을 추정하는 방법에서 다룹니다.

SDK에서는 allowedTools가 그 호출들이 애초에 실행될 수 있는지를 정합니다. 위 목록에 이미 들어 있는 generation_admission_preview는 generate_video를 승인하지 않은 상태에서도 접수 여부를 미리 확인합니다. dry_run은 유료 도구 자체의 인자이므로, generate_video를 dry-run하려면 allowedTools에 mcp__sume__generate_video를 추가해야 하고, 그 항목은 실제 제출도 승인합니다. 유료 생성에 관한 Sume 플레이북은 사용자가 지출을 명시적으로 확인했을 때 쓰는 것입니다. dry_run=true로 한 번 호출하고, dry_run을 빼거나 false로 두고 다시 호출해 제출한 뒤, jobs_wait로 기다렸다가 jobs_result를 읽습니다. 문서에 나온 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"
    }
  }
}

Sume 도구 호출은 얼마나 오래 실행될 수 있나요?

Claude Code의 기본값은 이미 Sume의 대기에 맞습니다.

• HTTP MCP 서버로 가는 요청은 기본적으로 각각 60초 뒤에 타임아웃됩니다. 밀리초 단위인 MCP_TOOL_TIMEOUT을 60000보다 크게 설정하면 이 한도가 늘어납니다.
• 네트워크 서버에서 도구 호출이 5분 동안 응답도 진행 알림도 받지 못하면 중단되는데(CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT), 이 시간은 Sume 대기 한 번보다 깁니다.
• Sume의 jobs_wait는 호출 한 번을 최대 55초, 기본 50초 동안 붙잡아 둡니다. wait_slice_expired를 받으면 같은 id로 다시 호출하고, 유료 create는 절대 다시 제출하지 마세요.
• 서버 시작은 기본적으로 30초 뒤에 타임아웃됩니다(MCP_TIMEOUT).
• 이미지 콘텐츠가 없는 도구 결과가 25,000 토큰보다 크면 파일로 저장되고, 결과는 그 파일 경로를 알려 주는 오류 메시지로 대체됩니다.

연결은 어떻게 확인하나요?

init 시스템 메시지는 서버마다 상태를 pending, connected, failed, needs-auth, disabled 중 하나로 알려 줍니다. sume 서버가 needs-auth라면 서버가 인가를 요청했다는 뜻이므로, 헤더가 서버에 도달했는지 확인하세요. 자격 증명이 필요한 서버도 init 메시지에는 여전히 pending으로 나올 수 있으며, TypeScript SDK의 mcpServerStatus()로 이를 확인할 수 있습니다. 서버가 connected가 되면 에이전트에게 mcp_health를 호출하게 하세요. 엔드포인트, 인증 출처, 안전 설정을 확인해 줍니다.