MCP 커넥터

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

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

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

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



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

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

선언된 각 서버는 tools 배열에 일치하는 mcp_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는 참조되지 않은 서버나 연결되지 않은 툴셋이 있는 에이전트 정의를 거부합니다.



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

mcp_toolset 항목은 MCP 서버가 노출하는 도구에 적용되는 default_config 객체와 configs 배열을 지원합니다. 각 configs 항목은 name, enabled, permission_policy만 허용합니다. 기본 제공 에이전트 툴셋의 항목과 달리 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 패턴은 툴셋 구성하기를 참조하고, MCP 도구에 permission_policy를 설정하고 확인 요청을 처리하는 방법은 MCP 툴셋 권한을 참조하세요.



MCP 도구 출력 처리

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



세션 생성 시 인증 제공하기

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

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

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



연결 및 인증 실패 처리하기

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

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



다음 단계