MCP 커넥터

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

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

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

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



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

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

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

AGENT_ID=$(ant beta:agents create \
  --name "GitHub Assistant" \
  --model claude-opus-4-8 \
  --mcp-server '{type: url, name: github, url: "https://api.githubcopilot.com/mcp/"}' \
  --tool '{type: agent_toolset_20260401}' \
  --tool '{type: mcp_toolset, mcp_server_name: github}' \
  --transform id --raw-output)



mcp_servers 필드 참조

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

제약 사항:

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



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

mcp_toolset 항목은 내장 에이전트 툴셋과 동일한 default_config 및 configs 형식을 지원하며, 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 패턴은 툴셋 구성하기를 참조하고, MCP 도구에 permission_policy를 설정하고 확인 요청을 처리하는 방법은 MCP 툴셋 권한을 참조하세요.



MCP 도구 출력 처리

MCP 도구 출력이 100,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을 가진 자격 증명이 포함되어야 합니다. 일치하는 항목이 없으면 인증 없이 연결이 시도됩니다. static_bearer 및 mcp_oauth 자격 증명 유형에 대해서는 자격 증명 추가하기를 참조하세요.



연결 및 인증 실패 처리하기

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

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



다음 단계