MCP 커넥터

Claude Managed Agents는 Model Context Protocol (MCP) 서버를 에이전트에 연결하는 것을 지원합니다. 이를 통해 에이전트는 표준화된 프로토콜을 통해 외부 도구, 데이터 소스 및 서비스에 접근할 수 있습니다.

MCP 구성은 두 단계로 나뉩니다:

1. 에이전트 생성 단계에서는 에이전트가 연결할 MCP 서버를 이름과 URL로 선언합니다.
2. 세션 생성 단계에서는 사전 등록된 vault를 참조하여 해당 서버에 대한 인증을 제공합니다(vault로 인증하기 참조).

이러한 분리를 통해 재사용 가능한 에이전트 정의에서 시크릿을 제외하면서도, 각 세션이 자체 자격 증명으로 인증할 수 있습니다.

에이전트에 MCP 서버 선언하기

에이전트를 생성할 때 mcp_servers 배열에 MCP 서버를 지정합니다. 각 서버에는 type, 고유한 name, 그리고 url이 필요합니다. 이 단계에서는 인증 토큰을 제공하지 않습니다.

선언된 각 서버에는 tools 배열에 일치하는 mcp_toolset 항목도 필요합니다. toolset의 mcp_server_name은 서버의 name과 일치해야 합니다.

AGENT_ID=$(ant beta:agents create --transform id --raw-output < github-assistant.agent.yaml)

name: GitHub Assistant
model:
  id: claude-opus-5
mcp_servers:
  - type: url
    name: github
    url: https://api.githubcopilot.com/mcp/
tools:
  - type: agent_toolset_20260401
  - type: mcp_toolset
    mcp_server_name: github

mcp_servers 필드 참조

mcp_servers 배열의 각 항목은 하나의 연결을 정의합니다.

제약 사항:

• 에이전트는 최대 20개의 MCP 서버를 선언할 수 있습니다. 서버 이름은 배열 내에서 고유해야 합니다.
• 모든 mcp_servers 항목은 tools 배열의 mcp_toolset에 의해 참조되어야 하며, 모든 mcp_toolset은 선언된 서버를 참조해야 합니다. API는 참조되지 않은 서버나 연결되지 않은 toolset이 있는 에이전트 정의를 거부합니다.

사용 가능한 MCP 도구 구성하기

mcp_toolset 항목은 default_config 객체와 configs 배열을 지원하며, 이는 MCP 서버가 노출하는 도구에 적용됩니다. 각 configs 항목은 name, enabled, permission_policy만 허용합니다. 내장 에이전트 toolset의 항목과 달리 MCP 도구 항목은 type 필드를 받지 않으며, web_search 및 web_fetch에서 사용할 수 있는 웹 설정은 MCP 도구에 적용되지 않습니다. 각 configs 항목의 name은 서버가 보고하는 순수한 도구 이름입니다.

기본적으로 MCP 서버가 노출하는 모든 도구가 활성화됩니다. 특정 도구만 활성화하려면 default_config.enabled를 false로 설정하고 원하는 도구를 명시적으로 활성화하세요:

{
  "type": "mcp_toolset",
  "mcp_server_name": "github",
  "default_config": { "enabled": false },
  "configs": [
    { "name": "get_issue", "enabled": true },
    { "name": "list_issues", "enabled": true },
    { "name": "add_issue_comment", "enabled": true }
  ]
}

이 패턴은 서버가 많은 도구를 노출하지만 에이전트에는 몇 개만 필요한 경우, 또는 서버 운영자가 추가한 도구를 검토하기 전까지 비활성 상태로 유지하고 싶은 경우에 유용합니다.

나머지는 활성화된 상태로 유지하면서 특정 도구만 비활성화하려면 default_config를 생략하고 개별 항목에 enabled: false를 설정하세요:

{
  "type": "mcp_toolset",
  "mcp_server_name": "github",
  "configs": [{ "name": "delete_repository", "enabled": false }]
}

일반적인 default_config / configs 패턴에 대해서는 toolset 구성하기를, MCP 도구에 permission_policy를 설정하고 확인 요청을 처리하는 방법에 대해서는 MCP toolset 권한을 참조하세요.

MCP 도구 출력 처리

MCP 도구 출력이 100,000자(약 25,000 토큰)를 초과하면 자동으로 샌드박스의 파일에 기록됩니다. 모델은 파일 경로와 함께 잘린 미리보기를 받으며, 해당 경로에서 전체 내용을 읽을 수 있습니다.

세션 생성 시 인증 제공하기

세션을 시작할 때 vault_ids를 전달하여 MCP 서버에 대한 자격 증명을 제공합니다. Vault는 한 번 등록하고 ID로 참조하는 자격 증명 모음입니다. vault를 생성하고 자격 증명을 관리하는 방법은 vault로 인증하기를 참조하세요.

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
)

자격 증명은 URL로 매칭되므로, vault에는 mcp_servers에 선언된 url과 동일한 서버를 가리키는 mcp_server_url을 가진 자격 증명이 포함되어 있어야 합니다. 두 URL은 매칭 전에 정규화되므로(스킴과 호스트는 소문자로 변환되고, 기본 포트와 끝의 슬래시는 제거됨), 호스트의 대소문자 차이, 기본 포트, 또는 끝의 슬래시는 매칭을 방해하지 않습니다. 반면 경로, 서브도메인, 또는 기본값이 아닌 포트가 다르면 매칭되지 않습니다. 일치하는 것이 없으면 인증 없이 연결을 시도합니다. static_bearer 및 mcp_oauth 자격 증명 유형에 대해서는 자격 증명 추가하기를 참조하세요.

연결 및 인증 실패 처리하기

세션 생성 시에는 MCP 연결성이나 자격 증명을 검증하지 않습니다. MCP 서버에 연결할 수 없거나 서버가 제공된 자격 증명을 거부하더라도 세션은 여전히 시작되며 상호작용도 가능합니다. 영향을 받은 서버의 mcp_server_name과 retry_status를 포함한 session.error 이벤트가 발생합니다:

이 오류 발생 시 추가 상호작용을 차단할지, 자격 증명 교체를 트리거할지, 또는 영향을 받은 서버의 도구 없이 세션을 계속 진행할지 결정할 수 있습니다. 연결은 다음 session.status_idle에서 session.status_running으로의 전환 시 재시도됩니다.

다음 단계