CrewAI MCP 서버: 에이전트에 Sume 도구 연결하기

CrewAI에서 MCP 서버를 쓰려면 에이전트의 mcps 목록에 추가하세요. 빠르게 설정할 때는 URL 문자열을, 헤더와 도구 필터링이 필요할 때는 MCPServerHTTP 설정을 넣습니다. Sume 호스팅 MCP 서버라면 url="https://mcp.sume.com/mcp", Authorization: Bearer 헤더에 담은 Sume API 키, 크루에 필요한 Sume 도구만 허용하는 tool_filter로 MCPServerHTTP를 구성하세요.

CrewAI 쪽 내용은 CrewAI의 MCP 개요와 MCP DSL Integration 페이지에서, Sume 쪽 내용은 MCP OAuth와 API 키, MCP 도구와 게이트, Job과 결과 (영문)에서 가져왔으며, 모두 2026-09-28에 확인했습니다. Sume에는 CrewAI 전용 커넥터가 없습니다. CrewAI 자체의 MCP 클라이언트가 Sume 원격 서버에 연결하는 방식이며, Sume 기초 페이지는 호스팅 MCP가 여전히 동작하지만 현재 주 경로는 아니라고 설명합니다. 대신 커스텀 도구에서 Sume REST API를 호출하려면 Sume Agent Completions 도구로 CrewAI 영상 생성을 참고하세요.

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

mcps 필드를 쓰려면 mcp 라이브러리가 필요합니다(uv add mcp). MCPServerHTTP는 필수인 url과, 선택 항목인 headers, streamable(Streamable HTTP, 기본값 True), tool_filter, cache_tools_list를 받습니다.

• Sume에는 URL 문자열 형식을 쓰지 마세요. CrewAI의 문자열 예제는 자격 증명을 쿼리 문자열에 담지만, Sume 문서가 제시하는 키 전송 방법 두 가지는 모두 헤더입니다(Authorization: Bearer 또는 x-api-key).
• CrewAI DSL 페이지가 API 키에 대해 권하는 대로, 키는 환경 변수에서 읽으세요.

import os
from crewai import Agent, Crew, Task
from crewai.mcp import MCPServerHTTP
from crewai.mcp.filters import create_static_tool_filter

sume = MCPServerHTTP(
    url="https://mcp.sume.com/mcp",
    headers={"Authorization": f"Bearer {os.environ['SUME_API_KEY']}"},
    tool_filter=create_static_tool_filter(
        allowed_tool_names=["tools_schema", "generate_video", "jobs_wait", "jobs_result"],
    ),
)
producer = Agent(
    role="Video producer",
    goal="Turn a brief into one short video with Sume",
    backstory="Previews paid calls with dry_run=true first. Calls jobs_wait with "
    "timeout_seconds 25 and repeats it until the job ends; never resubmits a paid create.",
    mcps=[sume],
)
task = Task(description="A 5-second clip of waves at sunset.",
            expected_output="The video URL", agent=producer)
print(Crew(agents=[producer], tasks=[task]).kickoff())

jobs_wait는 왜 30초 미만으로 유지해야 하나요?

CrewAI DSL 페이지는 MCP 작업에 기본 제공되는 타임아웃을 나열하며, 그중에는 30초짜리 도구 실행 타임아웃이 있습니다. Sume 원격 MCP에서 jobs_wait는 기본 50초이고 상한은 55초입니다. 대기는 Job이 종료 상태가 되는 즉시 반환되지만, 아직 실행 중인 렌더는 슬라이스 내내 호출을 붙잡아 두므로 CrewAI의 한도를 넘깁니다.

그러니 예제의 backstory에 적은 timeout_seconds 25처럼 에이전트가 더 짧은 슬라이스를 요청하게 하고, Job이 끝날 때까지 같은 id로 jobs_wait를 다시 호출하게 하세요. 유료 create는 절대 다시 제출하지 마세요. 중간에 끊긴 대기는 Job에 대해 아무것도 알려 주지 않으며, Job은 계속 실행되고 계속 청구됩니다. 이 패턴은 긴 영상 Job의 MCP 도구 호출 타임아웃에서 다룹니다.

크루에는 어떤 Sume 도구를 보여 줘야 하나요?

API 키 세션에는 유료 도구를 포함한 Sume의 전체 호스팅 도구 세트가 보이며, CrewAI의 기본 tool_filter 값인 None은 모든 도구를 쓸 수 있게 합니다. create_static_tool_filter는 허용 목록과 차단 목록을 받습니다. CrewAI의 필터 예제가 서버의 도구 이름을 쓰듯이, Sume 자체의 도구 이름을 쓰세요. 이름 충돌을 막기 위해 CrewAI는 도구 이름 앞에 서버 이름을 붙이므로(예제에서는 search가 mcp_exa_ai_search가 됩니다), 로그에는 접두사가 붙은 이름이 나온다고 예상하세요.

• 유료 도구에는 idempotency_key가 필요합니다. dry_run=true는 제출하지 않고 비용을 미리 보여 주며, max_spend_usd는 값을 보낸 경우에만 호출의 상한이 됩니다. 이 인수들은 모델이 작성하므로, 사용법을 backstory나 task에 적어 두세요.
• Sume MCP 도구 목록은 모든 호스팅 도구를 읽기, 쓰기, 유료로 나눠 정리합니다.

키가 틀렸거나 Sume에 연결할 수 없으면 어떻게 되나요?

크루는 Sume 없이 계속 진행합니다. CrewAI는 연결 실패를 경고로 기록한 뒤 가진 도구로 계속 진행하고, 인증 오류를 기록하며, 잘못된 설정에 대해서는 에이전트를 만들 때 검증 오류를 발생시킵니다. Sume는 키가 없거나, 형식이 잘못됐거나, 폐기된 경우 401로 응답하므로, Sume 도구를 한 번도 호출하지 않은 실행을 믿기 전에 로그를 확인하세요.

• 호스팅 MCP는 노트북의 파일을 읽을 수 없습니다.