Azure AI Foundry MCP 도구: 에이전트를 Sume에 연결

Azure AI Foundry의 MCP 도구는 Foundry 에이전트를 원격 MCP 서버에 연결합니다. server_label과 server_url로 mcp 도구를 추가하고, 자격 증명은 project_connection_id로 지정하는 프로젝트 연결에 두며, require_approval에서 달리 정하지 않는 한 호출마다 승인합니다. Sume 호스팅 MCP 서버라면 server_url은 https://mcp.sume.com/mcp이고, 연결은 키가 Authorization, 값이 Bearer와 Sume API 키인 Custom keys 연결입니다.

Microsoft 쪽 내용은 제품을 Microsoft Foundry라고 부르는 에이전트를 Model Context Protocol 서버에 연결 페이지와 MCPTool Python 레퍼런스에서, Sume 쪽 내용은 MCP OAuth와 API 키, MCP 도구와 게이트, Job과 결과 (영문)에서 가져왔으며, 모두 2026-09-28에 확인했습니다. Sume에는 Foundry 전용 연동이 없습니다. 에이전트는 URL로 Sume 원격 MCP 서버에 연결하며, Microsoft는 서드파티 MCP 서버를 테스트하거나 검증하지 않는다고 밝힙니다. Sume 기초 페이지는 호스팅 MCP가 여전히 동작하지만 현재 주 경로는 아니라고 설명합니다. OpenAI 자체 MCP 도구는 OpenAI Responses API MCP 도구를 참고하세요.

Sume API 키는 어디에 넣나요?

코드가 아니라 프로젝트 연결에 넣습니다. Microsoft 페이지는 API 키와 bearer 토큰을 앱에 하드코딩하지 말고 프로젝트 연결에 두라고 합니다. Microsoft Foundry에서 오른쪽 위 내비게이션의 Manage, Project details, Connected resources 탭을 차례로 선택한 뒤, Custom keys 유형의 연결을 만들고 키 Authorization에 값 Bearer <your Sume API key>를 추가하세요. Microsoft 페이지는 프로젝트 엔드포인트로 azd ai project set을 실행한 뒤 쓰는 azd 방식도 보여 줍니다. 프로젝트 연결을 만들려면 Foundry Project Manager 역할이 필요합니다.

OAuth 대신 Custom keys를 쓰세요. Foundry의 관리형 OAuth 앱은 Microsoft 목록에 있는 서버만 지원하고, 자체 앱 등록에는 클라이언트 ID와 클라이언트 시크릿이 필요합니다. 현재 Sume 서버는 공개 클라이언트만 등록하므로, 여러분에게 줄 클라이언트 시크릿이 없습니다.

azd ai connection create sume-mcp \
  --kind remote-tool \
  --target https://mcp.sume.com/mcp \
  --auth-type custom-keys \
  --custom-key "Authorization=Bearer $SUME_API_KEY"

Foundry 에이전트에 Sume를 MCP 도구로 어떻게 추가하나요?

Microsoft Python 샘플처럼 프롬프트 에이전트에 MCPTool을 붙이고, project_connection_id에 연결 이름을 적으세요. allowed_tools에는 에이전트에 필요한 Sume 도구만 나열하세요. 이 값이 없으면 에이전트가 서버의 모든 도구를 받고, API 키 세션에는 Sume의 전체 호스팅 도구 세트가 보입니다. 이 설정을 바탕으로 무언가를 만들기 전에 테스트 호출을 한 번 해 보세요. 아래 오류 섹션에서 설명하듯이, generate_image에는 Microsoft가 밝힌 Invalid tool schema 오류 원인에 해당하는 파라미터가 있습니다.

import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import MCPTool, PromptAgentDefinition

project = AIProjectClient(endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
                          credential=DefaultAzureCredential())
sume = MCPTool(
    server_label="sume",
    server_url="https://mcp.sume.com/mcp",
    allowed_tools=["mcp_health", "generate_image", "jobs_wait", "jobs_result"],
    require_approval="always",
    project_connection_id="sume-mcp",
)
agent = project.agents.create_version(
    agent_name="sume-agent",
    definition=PromptAgentDefinition(
        model=os.environ["FOUNDRY_MODEL_DEPLOYMENT_NAME"],
        instructions="Use Sume tools only when the user asks for media.",
        tools=[sume],
    ),
)

Sume 유료 도구의 승인은 어떻게 동작하나요?

승인이 필요하면 응답에 도구와 그 인수를 담은 mcp_approval_request 항목이 들어 있습니다. 내용을 검토한 뒤, previous_response_id를 그 응답으로 설정하고, 요청의 id를 approval_request_id로 담고 approve: true를 넣은 mcp_approval_response 항목을 포함해 후속 요청을 보내세요. 같은 항목 타입은 OpenAI Responses API MCP 도구에서 차례로 다룹니다. {"never": [...]} 목록에는 승인을 건너뛸 도구를 적으며, jobs_wait 같은 Sume Job 읽기 도구에 알맞습니다. generate_image와 다른 유료 도구는 Microsoft가 위험도가 높은 작업에 권하는 대로 승인을 거치게 두세요. Sume 유료 호출에는 idempotency_key도 필요하고, dry_run=true는 Job을 제출하지 않고 접수 여부와 비용을 미리 보여 주며, max_spend_usd는 값을 보낸 경우에만 호출의 상한이 됩니다.

긴 Sume Job은 Foundry의 100초 타임아웃에 걸리나요?

에이전트가 구간을 나눠 기다리면 걸리지 않습니다. Foundry에서 스트리밍이 아닌 MCP 도구 호출은 100초 뒤에 타임아웃되고, Sume의 jobs_wait는 호출 한 번을 최대 55초 동안 붙잡아 둡니다. wait_slice_expired를 받으면 에이전트는 같은 id로 jobs_wait를 다시 호출해야 하며, 유료 create는 절대 다시 제출하면 안 됩니다.

더 긴 MCP 호출을 위한 Foundry의 백그라운드 모드는 프리뷰이며, MCP tasks capability를 구현한 서버가 필요합니다. 현재 코드에서 Sume 서버는 tools capability만 선언하므로, 백그라운드 모드를 써도 Sume Job을 기다리는 방식은 달라지지 않습니다.

Sume를 쓸 때 Foundry에는 어떤 오류가 나올 수 있나요?

• Unauthorized 또는 Forbidden: Bearer 접두사를 포함해 프로젝트 연결의 자격 증명을 확인하세요.
• Invalid tool schema: Microsoft는 이 오류가 보통 서버의 도구 정의에 anyOf나 allOf가 있거나, 파라미터가 여러 타입을 받을 때 생긴다고 설명합니다. 현재 Sume 코드에는 그런 정의가 있습니다. avatars_search는 best_for 필터에 anyOf를 쓰고, generate_image의 image_size는 프리셋 이름, 너비와 높이 객체, WIDTHxHEIGHT 문자열을 받습니다. Sume 정의는 여러분이 바꿀 수 없고, allowed_tools로 이 검사를 피할 수 있는지는 Microsoft가 밝히지 않습니다.
• 모델이 도구를 한 번도 호출하지 않는 경우: server_label, server_url, allowed_tools가 서버가 노출하는 내용과 맞는지 확인하세요. Sume 도구 id는 generate_image처럼 밑줄을 쓰는 이름입니다.