Mastra MCP 클라이언트: 에이전트를 Sume 호스팅 MCP에 연결

Mastra 에이전트를 Sume 도구에 연결하려면 new URL("https://mcp.sume.com/mcp")를 가리키는 sume 서버로 MCPClient를 만들고, requestInit.headers에 Sume API 키를 Authorization: Bearer로 넣으세요. 그다음 유료 호출이 사람을 기다리도록 requireToolApproval을 설정하고, await mcp.listTools()에서 에이전트에 필요한 도구만 골라 주세요.

Mastra 관련 내용은 Mastra의 MCP 가이드, MCPClient 레퍼런스, 휴먼 인 더 루프 페이지에서, Sume 관련 내용은 OAuth와 API 키, MCP 도구와 게이트, Job과 결과 (영문)에서 가져왔으며, 모두 2026-09-27에 확인했습니다. Sume에는 Mastra용 패키지나 플러그인이 없습니다. @mastra/mcp의 MCPClient는 Mastra 자체의 클라이언트입니다. Sume 기초 페이지는 호스팅 MCP가 여전히 동작하지만 현재 주 경로는 아니라고 설명합니다. MCP 대신 REST 도구를 쓰려면 Vercel AI SDK: Sume API 도구 호출로 영상 생성하기를 참고하세요.

Sume용 MCPClient는 어떻게 설정하나요?

@mastra/mcp@latest를 설치하세요. url로 정의한 서버는 Streamable HTTP 트랜스포트를 쓰며, requestInit은 그 서버로 가는 요청의 fetch 설정입니다. Sume는 키를 Authorization: Bearer나 x-api-key로 받습니다. Mastra 문서가 API 키에 대해 권하는 대로, 둘 중 하나를 환경 변수에서 읽어 보내세요.

import { Agent } from "@mastra/core/agent";
import { MCPClient } from "@mastra/mcp";

export const mcp = new MCPClient({
  id: "sume-mcp",
  servers: {
    sume: {
      url: new URL("https://mcp.sume.com/mcp"),
      requestInit: { headers: { Authorization: `Bearer ${process.env.SUME_API_KEY}` } },
      requireToolApproval: ({ toolName, args }) =>
        toolName === "generate_video" && args.dry_run !== true,
    },
  },
});

const keep = ["tools_schema", "balance_get", "generate_video", "jobs_wait", "jobs_result"];
const tools = Object.fromEntries(
  Object.entries(await mcp.listTools()).filter(([name]) => keep.some((t) => name === `sume_${t}`)),
);

export const producer = new Agent({
  id: "producer",
  name: "Video producer",
  instructions: "Preview generate_video with dry_run: true first. Wait with jobs_wait; never resubmit.",
  model: "openai/gpt-5-mini",
  tools,
});

에이전트에는 어떤 도구 이름이 보이나요?

listTools()는 설정한 모든 서버의 도구를 serverName_toolName 형식의 네임스페이스로 반환하므로, Sume의 generate_video는 sume_generate_video가 됩니다. Sume의 API 키 세션에는 쓰기·유료 도구가 보이므로 예제는 다섯 개만 남깁니다. 나머지 도구가 읽는지, 쓰는지, 비용을 쓰는지는 Sume MCP 도구 목록에 분류되어 있습니다.

유료 Sume 호출은 어떻게 승인을 기다리나요?

서버 정의에서 requireToolApproval은 true를 받거나, 도구 이름, 모델이 넘긴 인자, 요청 컨텍스트, 서버가 알리는 annotation을 받는 함수를 받습니다. Mastra는 인자를 먼저 확인하고 싶은, 비용이 큰 서드파티 API 호출을 휴먼 인 더 루프를 쓰는 이유로 꼽습니다.

호출에 승인이 필요하면 스트림은 toolCallId, toolName, args가 담긴 tool-call-approval 청크를 내보냅니다. agent.approveToolCall({ runId }) 또는 agent.declineToolCall({ runId })로 이어 가세요. generate()를 쓰면 결과가 finishReason: 'suspended'와 함께 돌아오며, approveToolCallGenerate({ runId, toolCallId })로 이어 갑니다.

• 승인은 스냅샷을 쓰므로 Mastra 인스턴스에 스토리지 프로바이더를 설정하세요. 설정하지 않으면 "snapshot not found" 오류가 납니다.
• annotation이 아니라 도구 이름으로 판단하세요. Mastra는 직접 관리하지 않는 서버의 annotation을 신뢰할 수 없는 힌트로 다루라고 합니다.
• Sume 자체 게이트도 그대로 적용됩니다. dry_run=true는 Job을 제출하지 않고 접수 여부와 비용을 미리 보여 주며, max_spend_usd는 값을 넘긴 경우에만 호출의 상한이 됩니다. 프리뷰는 Sume Job 실행 전에 AI 영상 생성 비용 추정하기에서 다룹니다.

MCPClient 타임아웃은 jobs_wait에 충분히 긴가요?

네, 몇 초 여유가 있습니다. 클라이언트 수준 timeout의 기본값은 60000밀리초이며, 서버 수준 timeout이 이를 덮어씁니다. Sume의 jobs_wait는 호출 한 번을 최대 55초, timeout_seconds를 생략하면 50초 동안 붙잡아 두므로, 타임아웃은 기본값 이상으로 유지하세요.

• wait_slice_expired를 받으면 같은 id로 jobs_wait를 다시 호출하세요. 유료 create는 절대 다시 제출하지 마세요. jobs_wait에서 받은 524, 522, 523, 525는 Job 결과가 아니라 전송 실패입니다.
• 기본 설정(onToolError: 'throw')에서는 in-band 도구 오류가 서버의 오류 텍스트를 담은 MastraError를 발생시키므로, 실패가 모델에 전달됩니다.

listTools와 listToolsets 중 무엇을 써야 하나요?

Sume 키 하나로 모든 요청을 처리한다면 Agent 생성자에서 listTools()를 쓰세요. 이때 자격 증명은 모든 요청이 공유합니다. 사용자마다 자기 Sume 키가 있다면 요청마다 클라이언트를 만들고, await client.listToolsets()를 generate()나 stream()에 넘긴 뒤, 응답이 끝나면 disconnect()를 호출하세요. listToolsets()는 도구 이름을 serverName.toolName 형식으로 붙입니다.