Pydantic AI MCP 서버: 에이전트에 Sume 호스팅 도구 연결

Pydantic AI 에이전트가 Sume 도구를 쓰게 하려면 https://mcp.sume.com/mcp를 가리키는 MCPToolset을 만들고 Authorization: Bearer 헤더에 Sume API 키를 넣으세요. 그다음 .filtered()로 에이전트에 필요한 도구만 남기고, .approval_required()로 유료 호출을 보류하고, Agent(toolsets=[...])로 툴셋을 등록하세요.

Pydantic AI 쪽 내용은 MCP 클라이언트 가이드, MCPToolset 레퍼런스, 툴셋 페이지에서, Sume 쪽 내용은 OAuth와 API 키, MCP 도구와 게이트, Job과 결과 (영문)에서 가져왔으며, 모두 2026-09-27에 확인했습니다. Sume에는 Pydantic AI용 패키지나 플러그인이 없습니다. Pydantic AI 자체의 MCP 클라이언트가 Sume 원격 서버와 통신하는 방식입니다. Sume 기초 페이지는 호스팅 MCP가 여전히 동작하지만 현재 주 경로는 아니라고 설명합니다.

Pydantic AI 에이전트를 Sume MCP 서버에 어떻게 연결하나요?

pydantic-ai-slim[mcp]를 설치하세요. MCPToolset은 FastMCP 클라이언트를 감싸며, URL 문자열을 넘기면 Streamable HTTP로 연결합니다. Pydantic AI는 Streamable HTTP를 원격 MCP 서버에 연결하는 권장 방식이라고 설명하며, 경로가 /sse로 끝날 때만 SSE로 바뀝니다. 툴셋은 에이전트의 toolsets 인자로 등록하세요. Pydantic AI는 대부분의 경우 MCP capability를 권장하고, 클라이언트를 직접 관리하거나 capability가 노출하지 않는 옵션이 필요할 때는 MCPToolset을 권장합니다. 이 글은 .filtered()와 .approval_required()로 감쌀 수 있도록 MCPToolset을 씁니다. 예제는 에이전트에 Sume 도구 다섯 개를 보여 주고, dry run이 아닌 generate_video 호출은 승인을 받을 때까지 멈춥니다.

import os
from pydantic_ai import Agent, DeferredToolRequests
from pydantic_ai.mcp import MCPToolset

ALLOWED = {"tools_schema", "balance_get", "generate_video", "jobs_wait", "jobs_result"}

sume = (
    MCPToolset(
        "https://mcp.sume.com/mcp",
        headers={"Authorization": f"Bearer {os.environ['SUME_API_KEY']}"},
    )
    .filtered(lambda ctx, tool_def: tool_def.name in ALLOWED)
    .approval_required(
        lambda ctx, tool_def, args: tool_def.name == "generate_video" and not args.get("dry_run")
    )
)

agent = Agent(
    "openai:gpt-5.2",
    instructions="Preview generate_video with dry_run=true first. Wait with jobs_wait; never resubmit.",
    toolsets=[sume],
    output_type=[str, DeferredToolRequests],
)

Sume 키는 auth와 headers 중 어디에 넣어야 하나요?

어느 쪽이든 됩니다. HTTP 트랜스포트에서 MCPToolset은 auth로 bearer 토큰 문자열, httpx2.Auth, 또는 FastMCP OAuth 플로를 쓰는 'oauth'를 받습니다. Pydantic AI 문서는 API 키 같은 고정 헤더는 대신 headers에 넣을 수 있다고 설명합니다. Sume MCP 문서는 키를 Authorization: Bearer나 x-api-key로 받으므로, 둘 중 하나를 보내세요.

• Sume는 OAuth를 쓰지 않는 자동화를 위한 경로로 API 키 원격 MCP를 유지합니다. API 키 세션에는 쓰기·유료 도구가 보이며, 예제가 도구를 걸러 내는 이유도 이것입니다.
• headers와 사용자 지정 http_client는 함께 쓸 수 없습니다.
• 공유된 MCPToolset은 하나의 신원으로 서버에 연결합니다. 사용자마다 자기 Sume 키가 있다면 @agent.toolset(per_run_step=False)로 실행마다 툴셋을 만드세요.
• 키는 환경 변수에서 읽으세요. Sume 문서는 API 키를 채팅에 붙여 넣지 말고, 로그나 채팅 기록에 노출된 키는 교체하라고 안내합니다.

에이전트에는 어떤 Sume 도구를 보여 줘야 하나요?

filtered()는 실행의 각 단계에 앞서, 도구 정의마다 여러분의 함수가 내놓는 답에 따라 어떤 도구를 쓸 수 있을지 정합니다. 그다음 approval_required()가 호출마다 멈출지 정합니다. Sume의 라이브 도구 ID는 밑줄을 쓰며, Sume MCP 도구 목록은 모든 호스팅 도구를 읽기, 쓰기, 지출 여부에 따라 묶어 보여 줍니다. 예제의 두 함수를 적용하면 다음과 같습니다.

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

approval_required()에 넘기는 함수는 실행 컨텍스트, 도구 정의, 검증된 인자를 받습니다. 이 함수가 true를 반환하면 실행은 DeferredToolRequests로 끝나며, 그 approvals에 대기 중인 호출이 담깁니다. 에이전트의 output_type에 이 타입이 들어 있는 이유입니다. 실행의 message_history와 DeferredToolResults(approvals={tool_call_id: True})로 재개하세요. False를 넘기면 모델에 "The tool call was denied."라는 메시지가 돌아갑니다.

이 게이트는 결제 전에 도구를 확인하는 Sume 플레이북과 맞아떨어집니다. 유료 도구를 dry_run=true로 호출하고, 추정치, 잔액, 큐 동작을 확인한 다음, 새 idempotency_key를 넣어 제출합니다. idempotency_key는 모든 쓰기·유료 도구에 필수입니다. max_spend_usd는 값을 넘긴 경우에만 호출의 상한이 됩니다. 이 게이트들은 유료 API를 호출하는 AI 에이전트의 안전한 자동화에서 다룹니다.

긴 jobs_wait 호출은 타임아웃되나요?

기본값이라면 타임아웃되지 않습니다. Pydantic AI 타임아웃 페이지에 따르면 read_timeout은 MCP 요청 하나의 시간을 제한하며 기본값은 300초이고, 에이전트의 tool_timeout은 MCP 서버에서 온 도구에는 적용되지 않습니다. init_timeout은 최초 연결과 핸드셰이크에 적용됩니다. Sume의 jobs_wait는 호출 한 번을 최대 55초, timeout_seconds를 생략하면 50초 동안 붙잡아 두므로, 대기 한 번은 이 한도 안에 들어옵니다.

• wait_slice_expired를 받으면 같은 id로 jobs_wait를 다시 호출하세요. 유료 create는 절대 다시 제출하지 마세요.
• jobs_wait에서 받은 524, 522, 523, 525는 전송 실패이며, 결코 Job 결과가 아닙니다.
• 서버가 도구 오류를 보고하면 Pydantic AI는 기본적으로 그 오류를 재시도 프롬프트로 모델에 돌려보냅니다(tool_error_behavior='retry'). 'failed'로 설정하면 오류를 실패한 도구 결과로 기록하고, 다음에 무엇을 할지는 모델이 정하게 됩니다.
• 배치 대기와, 한 번에 기다린 결과 묶음 전체를 읽는 방법은 긴 영상 Job의 MCP 도구 호출 타임아웃에서 다룹니다.