Google ADK MCP 도구: McpToolset으로 Sume 서버 연결

Google ADK 에이전트를 Sume MCP 도구에 연결하려면 에이전트의 tools에 McpToolset을 추가하고, StreamableHTTPConnectionParams(url="https://mcp.sume.com/mcp"), Authorization: Bearer 헤더에 담은 Sume API 키, 에이전트가 호출해도 되는 Sume 도구만 적은 tool_filter를 지정하세요. 유료 도구는 require_confirmation=True를 설정한 두 번째 McpToolset에 넣으세요.

ADK 관련 내용은 ADK의 MCP 도구, Python API 레퍼런스, 액션 확인 페이지에서, Sume 관련 내용은 OAuth와 API 키, MCP 도구와 게이트, Job과 결과 (영문)에서 가져왔으며, 모두 2026-09-27에 확인했습니다. Sume에는 ADK용 패키지나 플러그인이 없습니다. McpToolset은 ADK 자체의 MCP 클라이언트입니다. Sume 기초 페이지는 호스팅 MCP가 여전히 동작하지만 현재 주 경로는 아니라고 설명합니다. Anthropic SDK에서 같은 설정을 하는 방법은 Claude Agent SDK MCP 서버를 참고하세요.

ADK 에이전트에 Sume MCP 서버를 어떻게 추가하나요?

Python 3.10 이상에서 MCP extra를 포함해 ADK를 설치하세요(pip install "google-adk[mcp]"). ADK 문서에 따르면 프로덕션에 배포하는 에이전트는 agent.py에서 McpToolset을 동기적으로 정의해야 하므로, 두 툴셋 모두 임포트 시점에 만드세요.

import os
from google.adk.agents import LlmAgent
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

def sume(tools, confirm=False):
    return McpToolset(
        connection_params=StreamableHTTPConnectionParams(
            url="https://mcp.sume.com/mcp",
            headers={"Authorization": f"Bearer {os.getenv('SUME_API_KEY')}"},
        ),
        tool_filter=tools,
        require_confirmation=confirm,
    )

root_agent = LlmAgent(
    model="gemini-flash-latest",
    name="video_producer",
    instruction="Preview paid calls with dry_run=true. Wait with jobs_wait; never resubmit.",
    tools=[
        sume(["tools_schema", "balance_get", "jobs_wait", "jobs_result"]),
        sume(["generate_video"], confirm=True),
    ],
)

Sume API 키는 어디에 넣나요?

ADK의 MCP 페이지는 os.getenv로 읽은 bearer 토큰을 headers로 넘기며, 예제도 같은 방식을 씁니다. 이 페이지는 헤더를 직접 만드는 대신 ADK 고유의 auth_scheme, auth_credential 파라미터를 쓰라고도 권합니다. 이 파라미터를 쓰면 ADK가 Authorization 헤더를 직접 구성합니다. MCP 도구에 API 키 인증을 쓸 때 ADK는 헤더 기반 키만 지원하며, Sume가 받는 방식도 헤더입니다(Authorization: Bearer 또는 x-api-key).

• 사용자마다 키가 다르다면 header_provider에 callable을 넘길 수 있습니다. 이 callable은 ReadonlyContext를 받아 세션의 헤더를 반환합니다.
• Sume의 API 키 세션에는 유료 도구를 포함한 전체 호스팅 도구 세트가 보입니다. 어떤 도구가 읽고, 쓰고, 비용을 쓰는지는 Sume MCP 도구 목록에 나와 있습니다. ADK 체크리스트는 필요한 액션만 노출하도록 항상 tool_filter를 지정하라고 하며, ADK 문서는 직접 연결한 툴셋의 모든 도구 정의가 에이전트 히스토리에 들어간다고 짚습니다.
• 키를 채팅에 붙여 넣지 말고, 로그나 채팅 기록에 노출되면 교체하세요.

확인 요청은 유료 Sume 호출을 어떻게 멈추나요?

require_confirmation=True를 설정하면 그 툴셋의 모든 도구가 실행 전에 멈추고 예/아니요 응답을 기다립니다. adk web 인터페이스에서는 사용자에게 대화상자가 뜹니다. UI가 없다면 adk_request_confirmation이라는 이름의 FunctionResponse를 ADK API 서버의 /run 또는 /run_sse 엔드포인트로 보내세요. 확인 요청의 id를 넣고, response에 confirmed를 담으면 됩니다.

• ADK는 Tool Confirmation을 실험적 기능으로 표시하며, 이 기능은 DatabaseSessionService와 VertexAiSessionService를 지원하지 않습니다.
• 불리언 값은 툴셋의 모든 도구에 적용되므로 dry_run=true 프리뷰도 확인을 요청합니다. ADK API 레퍼런스에 따르면 require_confirmation은 도구의 인자를 받아 불리언을 반환하는 callable일 수도 있지만, ADK 확인 가이드는 이 형태를 함수 도구에 대해서만 보여 줍니다.
• 결제 전 Sume 플레이북은 유료 도구를 dry_run=true로 호출하고, 추정치, 잔액, 큐 동작을 확인한 다음, 새 idempotency_key를 넣어 제출하는 것입니다. 모든 쓰기·유료 도구에는 idempotency_key가 필요합니다. max_spend_usd는 값을 넘긴 경우에만 호출의 상한이 됩니다. 다른 한도는 무인 AI 에이전트 지출 상한에서 다룹니다.

Sume의 긴 대기가 ADK 타임아웃 안에 들어오나요?

들어옵니다. Streamable HTTP에서 timeout은 연결 수립에, sse_read_timeout은 데이터 읽기에 걸리는 시간을 제한합니다. Sume의 jobs_wait는 호출 한 번을 최대 55초, timeout_seconds를 생략하면 50초 동안 붙잡아 두므로 읽기 타임아웃 안에 넉넉히 들어옵니다.

• wait_slice_expired를 받으면 같은 id로 jobs_wait를 다시 호출하고, 유료 create는 절대 다시 제출하지 마세요. jobs_wait에서 받은 524, 522, 523, 525는 Job 결과가 아니라 전송 실패입니다.
• adk web 밖에서는 await toolset.close()를 호출하거나 async 컨텍스트 매니저를 쓰세요. close()는 MCP 세션을 닫고 리소스를 해제합니다. 배치 대기는 긴 영상 Job의 MCP 도구 호출 타임아웃에서 다룹니다.