LlamaIndex MCP: 에이전트에 Sume 호스팅 도구 불러오기

LlamaIndex는 llama-index-tools-mcp 패키지로 MCP 서버를 씁니다. BasicMCPClient가 서버에 연결하고, aget_tools_from_mcp_url이나 McpToolSpec이 서버의 도구를 어떤 에이전트에든 넘길 수 있는 FunctionTool로 바꿉니다. Sume 호스팅 MCP 서버라면 클라이언트가 https://mcp.sume.com/mcp를 가리키게 하고, headers에 Sume API 키를 담아 보내고, 에이전트에 필요한 도구 이름을 allowed_tools에 적으세요.

LlamaIndex 쪽 내용은 LlamaIndex의 LlamaIndex에서 MCP 도구 사용하기 가이드, MCP 사용 예제, MCP API 레퍼런스에서, Sume 쪽 내용은 MCP OAuth와 API 키, MCP 도구와 게이트, Job과 결과 (영문)에서 가져왔으며, 모두 2026-09-28에 확인했습니다. Sume에는 LlamaIndex 전용 커넥터가 없습니다. LlamaIndex 자체의 MCP 클라이언트가 Sume 원격 서버와 통신하는 방식이며, Sume 기초 페이지는 호스팅 MCP가 여전히 동작하지만 현재 주 경로는 아니라고 설명합니다. LlamaIndex 이미지 생성 도구는 대신 Sume REST Image API를 FunctionTool로 감쌉니다.

LlamaIndex 에이전트에 Sume MCP 도구를 어떻게 불러오나요?

llama-index-tools-mcp를 설치하세요. BasicMCPClient는 Sume 주소 같은 https URL을 Streamable HTTP 엔드포인트로 취급합니다. 예제는 Sume 도구 네 개를 남기고, 유료 도구에는 지출 상한을 고정합니다.

• allowed_tools는 이름을 적은 도구만 반환합니다. 빼면 모든 도구가 반환되고, 빈 목록을 주면 경고와 함께 아무 도구도 반환되지 않습니다.
• partial_params_by_tool은 도구 이름을 고정 인수에 대응시킵니다. 레퍼런스에 실린 소스 코드를 보면 이 필드들은 모델이 보는 스키마에서 빠지고 부분 파라미터(partial params)로 도구에 전달되므로, 모델에게 상한을 묻지 않습니다. Sume는 max_spend_usd가 전송되면 언제나 이를 강제합니다.
• 모든 유료 Sume 도구에 필요한 idempotency_key는 여전히 모델이 작성하며, 모델은 dry_run=true로 비용을 미리 볼 수 있습니다.

import asyncio
import os
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI
from llama_index.tools.mcp import BasicMCPClient, aget_tools_from_mcp_url

SUME_MCP = "https://mcp.sume.com/mcp"

async def main() -> None:
    client = BasicMCPClient(
        SUME_MCP,
        headers={"Authorization": f"Bearer {os.environ['SUME_API_KEY']}"},
        timeout=60,
    )
    tools = await aget_tools_from_mcp_url(
        SUME_MCP,
        client=client,
        allowed_tools=["tools_schema", "generate_image", "jobs_wait", "jobs_result"],
        partial_params_by_tool={"generate_image": {"max_spend_usd": 2}},
    )
    agent = FunctionAgent(
        tools=tools,
        llm=OpenAI(model="gpt-5-mini"),
        system_prompt="Preview paid calls with dry_run=true. Wait with jobs_wait; never resubmit.",
    )
    print(await agent.run("A product photo of a red mug on a white table."))

asyncio.run(main())

BasicMCPClient에는 어떤 타임아웃을 줘야 하나요?

BasicMCPClient 문서에는 HTTP 작업의 초 단위 타임아웃인 timeout(기본값 30)과 SSE 읽기 타임아웃인 sse_read_timeout(기본값 300)이 나와 있습니다. 레퍼런스에 실린 소스 코드는 timeout을 MCP 세션에 read_timeout_seconds로도 넘깁니다. Sume jobs_wait 호출 한 번은 최대 55초, timeout_seconds를 생략하면 50초 동안 대기할 수 있고, 현재 코드는 MCP 요청마다 60초의 기한을 두므로, timeout=60은 Sume 호출 하나가 걸릴 수 있는 최대 시간 이상입니다.

API 키 대신 OAuth를 쓸 수 있나요?

LlamaIndex에는 BasicMCPClient.with_oauth(...)가 있습니다. 클라이언트 이름, 리다이렉트 URI, 그리고 리다이렉트와 돌려받은 코드를 처리하는 핸들러를 받습니다. 기본적으로 토큰을 메모리에 보관하므로 재시작하면 토큰이 사라지며, 소스 코드를 보면 authorization_code와 refresh_token grant로 등록합니다. Sume OAuth는 키와 다르게 동작하며, 자세한 내용은 Sume MCP 서버 OAuth 플로에 있습니다.

• 사용자가 동의 화면에서 Write를 켜기 전까지 세션은 읽기 전용이며, Write가 없으면 generate_image 같은 유료 도구는 insufficient_scope를 반환합니다.
• 현재 코드에서 액세스 토큰은 한 시간 동안 유효하고 Sume는 리프레시 토큰을 발급하지 않으므로, 오래 실행되는 LlamaIndex 서비스는 대략 한 시간마다 다시 로그인해야 합니다.
• Sume는 OAuth를 쓰지 않는 자동화를 위한 경로로 API 키 원격 MCP를 유지하며, 서버 쪽 에이전트에는 이 경로가 맞습니다.

그 밖에 무엇을 알아야 하나요?

• include_resources는 기본값인 False로 두세요. 현재 코드에서 Sume 서버는 tools capability만 선언하며, 리소스 목록 조회 같은 다른 메서드에는 method-not-found 오류로 응답합니다.
• API 키 세션에는 유료 도구를 포함한 Sume의 전체 호스팅 도구 세트가 보이며, 범위를 좁히는 수단은 여러분의 allowed_tools입니다.
• wait_slice_expired를 받으면 에이전트는 같은 id로 jobs_wait를 다시 호출해야 하며, 유료 create는 절대 다시 제출하면 안 됩니다. 이 패턴은 긴 영상 Job의 MCP 도구 호출 타임아웃에서 다룹니다.
• 키는 신뢰할 수 있는 서버나 시크릿 저장소에 두고, 프론트엔드 JavaScript에는 절대 넣지 마세요. 호스팅 MCP는 노트북의 파일을 읽을 수 없습니다.