에이전트 정의

MCP 커넥터

MCP 서버를 에이전트에 연결하여 외부 도구 및 데이터 소스에 액세스합니다.

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

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

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

이러한 분리는 재사용 가능한 에이전트 정의에서 비밀을 유지하면서 각 세션이 자체 자격증명으로 인증할 수 있도록 합니다.

모든 Managed Agents API 요청에는 managed-agents-2026-04-01 베타 헤더가 필요합니다. SDK는 베타 헤더를 자동으로 설정합니다.

에이전트에서 MCP 서버 선언

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

MCP 서버 배열에서 할당한 name은 도구 배열의 mcp_toolset 항목을 참조하는 데 사용됩니다.

agent_response=$(curl -sS --fail-with-body https://api.anthropic.com/v1/agents \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<'EOF'
{
  "name": "GitHub Assistant",
  "model": "claude-sonnet-4-6",
  "mcp_servers": [
    {
      "type": "url",
      "name": "github",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  ],
  "tools": [
    {"type": "agent_toolset_20260401"},
    {"type": "mcp_toolset", "mcp_server_name": "github"}
  ]
}
EOF
)
agent_id=$(jq -r '.id' <<<"$agent_response")

MCP 도구 집합은 기본적으로 always_ask의 권한 정책을 사용하며, 이는 각 도구 호출 전에 사용자 승인이 필요합니다. 권한 정책을 참조하여 이 동작을 구성하세요.

세션 생성 시 인증 제공

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

session_response=$(curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<EOF
{
  "agent": "$agent_id",
  "environment_id": "$environment_id",
  "vault_ids": ["$vault_id"]
}
EOF
)
session_id=$(jq -r '.id' <<<"$session_response")

Vault에서 제공된 인증 자격증명이 유효하지 않으면 세션 생성은 성공하고 상호작용은 여전히 가능합니다. MCP 인증 실패를 설명하는 session.error 이벤트가 발생합니다. 이 오류에 대해 추가 상호작용을 차단하거나, 자격증명 업데이트를 트리거하거나, MCP 없이 세션을 계속 진행할지 결정할 수 있습니다. 인증 재시도는 다음 session.status_idle에서 session.status_running 전환 시 발생합니다. session.error 및 기타 이벤트를 사용하는 방법에 대한 자세한 내용은 세션 이벤트 스트림을 참조하세요.

지원되는 MCP 서버 유형

Claude Managed Agents는 HTTP 엔드포인트를 노출하는 원격 MCP 서버에 연결합니다. 서버는 MCP 프로토콜의 스트리밍 가능한 HTTP 전송을 지원해야 합니다.

MCP 및 MCP 서버 구축에 대한 자세한 내용은 MCP 문서를 참조하세요.

Was this page helpful?

에이전트에서 MCP 서버 선언

MCP 서버 배열에서 할당한 name은 도구 배열의 mcp_toolset 항목을 참조하는 데 사용됩니다.

agent_response=$(curl -sS --fail-with-body https://api.anthropic.com/v1/agents \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<'EOF'
{
  "name": "GitHub Assistant",
  "model": "claude-sonnet-4-6",
  "mcp_servers": [
    {
      "type": "url",
      "name": "github",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  ],
  "tools": [
    {"type": "agent_toolset_20260401"},
    {"type": "mcp_toolset", "mcp_server_name": "github"}
  ]
}
EOF
)
agent_id=$(jq -r '.id' <<<"$agent_response")

세션 생성 시 인증 제공

session_response=$(curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<EOF
{
  "agent": "$agent_id",
  "environment_id": "$environment_id",
  "vault_ids": ["$vault_id"]
}
EOF
)
session_id=$(jq -r '.id' <<<"$session_response")