--- title: MCP 커넥터 url: https://platform.claude.com/docs/ko/managed-agents/mcp-connector description: 에이전트에 MCP 서버를 연결하여 외부 도구 및 데이터 소스에 접근할 수 있도록 합니다. featureMetadata: topic: title: Managed Agents url: https://platform.claude.com/docs/en/managed-agents/overview status: beta betaHeader: managed-agents-2026-04-01 --- Claude Managed Agents는 [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 서버를 에이전트에 연결하는 것을 지원합니다. 이를 통해 에이전트는 표준화된 프로토콜을 통해 외부 도구, 데이터 소스 및 서비스에 접근할 수 있습니다. MCP 구성은 두 단계로 나뉩니다: 1. **에이전트 생성** 단계에서는 에이전트가 연결할 MCP 서버를 이름과 URL로 선언합니다. 2. **세션 생성** 단계에서는 사전 등록된 vault를 참조하여 해당 서버에 대한 인증을 제공합니다([vault로 인증하기](https://platform.claude.com/docs/ko/managed-agents/vaults) 참조). 이러한 분리를 통해 재사용 가능한 에이전트 정의에서 시크릿을 제외하면서도, 각 세션이 자체 자격 증명으로 인증할 수 있습니다. ## 에이전트에 MCP 서버 선언하기 에이전트를 생성할 때 `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) 배열에 MCP 서버를 지정합니다. 각 서버에는 `type` (csharp, go: `Type`), 고유한 `name` (csharp, go: `Name`), 그리고 `url` (csharp: `Url`; go: `URL`)이 필요합니다. 이 단계에서는 인증 토큰을 제공하지 않습니다. 선언된 각 서버에는 `tools` (csharp, go: `Tools`) 배열에 대응하는 `mcp_toolset` 항목도 필요합니다. toolset의 `mcp_server_name` (java, php: `mcpServerName`; csharp: `McpServerName`; go: `MCPServerName`)은 서버의 `name` (csharp, go: `Name`)과 일치해야 합니다. ```bash cURL 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 '{ "name": "GitHub Assistant", "model": "claude-opus-5-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"} ] }' ``` ```bash CLI ant apply github-assistant.md ``` ```markdown --- name: GitHub Assistant model: claude-opus-5-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 --- ``` ```python Python agent = client.beta.agents.create( name="GitHub Assistant", model="claude-opus-5-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"}, ], ) ``` ```typescript TypeScript const agent = await client.beta.agents.create({ name: "GitHub Assistant", model: "claude-opus-5-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" } ] }); ``` ```csharp C# var agent = await client.Beta.Agents.Create(new() { Name = "GitHub Assistant", Model = BetaManagedAgentsModel.ClaudeOpus5_5, McpServers = [ new() { Type = "url", Name = "github", Url = "https://api.githubcopilot.com/mcp/" }, ], Tools = [ new BetaManagedAgentsAgentToolset20260401Params { Type = "agent_toolset_20260401", }, new BetaManagedAgentsMcpToolsetParams { Type = "mcp_toolset", McpServerName = "github" }, ], }); ``` ```go Go agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{ Name: "GitHub Assistant", Model: anthropic.BetaManagedAgentsModelConfigParams{ ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5, }, MCPServers: []anthropic.BetaManagedAgentsURLMCPServerParams{{ Type: anthropic.BetaManagedAgentsURLMCPServerParamsTypeURL, Name: "github", URL: "https://api.githubcopilot.com/mcp/", }}, Tools: []anthropic.BetaAgentNewParamsToolUnion{ { OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{ Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401, }, }, { OfMCPToolset: &anthropic.BetaManagedAgentsMCPToolsetParams{ Type: anthropic.BetaManagedAgentsMCPToolsetParamsTypeMCPToolset, MCPServerName: "github", }, }, }, }) if err != nil { panic(err) } ``` ```java Java var agent = client.beta().agents().create( AgentCreateParams.builder() .name("GitHub Assistant") .model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5) .addMcpServer( BetaManagedAgentsUrlMcpServerParams.builder() .type(BetaManagedAgentsUrlMcpServerParams.Type.URL) .name("github") .url("https://api.githubcopilot.com/mcp/") .build() ) .addTool( BetaManagedAgentsAgentToolset20260401Params.builder() .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401) .build() ) .addTool( BetaManagedAgentsMcpToolsetParams.builder() .type(BetaManagedAgentsMcpToolsetParams.Type.MCP_TOOLSET) .mcpServerName("github") .build() ) .build() ); ``` ```php PHP $agent = $client->beta->agents->create( name: 'GitHub Assistant', model: 'claude-opus-5-5', mcpServers: [ BetaManagedAgentsURLMCPServerParams::with( type: 'url', name: 'github', url: 'https://api.githubcopilot.com/mcp/', ), ], tools: [ BetaManagedAgentsAgentToolset20260401Params::with( type: 'agent_toolset_20260401', ), BetaManagedAgentsMCPToolsetParams::with( type: 'mcp_toolset', mcpServerName: 'github', ), ], ); ``` ```ruby Ruby agent = client.beta.agents.create( name: "GitHub Assistant", model: "claude-opus-5-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 toolset의 기본 권한 정책은 `always_ask`이며, 이는 각 도구 호출 전에 사용자 승인을 요구합니다. 이 동작을 구성하려면 [권한 정책](https://platform.claude.com/docs/ko/managed-agents/permission-policies)을 참조하세요. ### `mcp_servers` 필드 참조 `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) 배열의 각 항목은 하나의 연결을 정의합니다. | 필드 | 설명 | | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` (csharp, go: `Type`) | 필수. `"url"`이어야 합니다. | | `name` (csharp, go: `Name`) | 필수. 에이전트 내에서 이 서버를 식별하는 고유한 이름입니다(1–255자). `tools` (csharp, go: `Tools`) 배열에서 `mcp_server_name` (java, php: `mcpServerName`; csharp: `McpServerName`; go: `MCPServerName`)으로 사용되며, [세션 이벤트 스트림](https://platform.claude.com/docs/ko/managed-agents/events-and-streaming)의 MCP 도구 이벤트에 표시됩니다. | | `url` (csharp: `Url`; go: `URL`) | 필수. 원격 MCP 서버의 엔드포인트(최대 2,048자). 전송 요구 사항은 [지원되는 MCP 서버 유형](https://platform.claude.com/docs/ko/managed-agents/reference#supported-mcp-server-types)을 참조하세요. | 제약 사항: * 에이전트는 최대 20개의 MCP 서버를 선언할 수 있습니다. 서버 이름은 배열 내에서 고유해야 합니다. * 모든 `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) 항목은 `tools` (csharp, go: `Tools`) 배열의 `mcp_toolset`에서 참조되어야 하며, 모든 `mcp_toolset`은 선언된 서버를 참조해야 합니다. API는 참조되지 않은 서버나 대상이 없는 toolset이 있는 에이전트 정의를 거부합니다. ## 사용 가능한 MCP 도구 구성하기 `mcp_toolset` 항목은 MCP 서버가 노출하는 도구에 적용되는 `default_config` (java, php: `defaultConfig`; csharp, go: `DefaultConfig`) 객체와 `configs` (csharp, go: `Configs`) 배열을 지원합니다. 각 `configs` (csharp, go: `Configs`) 항목은 `name` (csharp, go: `Name`), `enabled` (csharp, go: `Enabled`), `permission_policy` (java, php: `permissionPolicy`; csharp, go: `PermissionPolicy`)만 허용합니다. 내장 에이전트 toolset의 항목과 달리 MCP 도구 항목은 `type` (csharp, go: `Type`) 필드를 받지 않으며, `web_search` 및 `web_fetch`에서 사용할 수 있는 [웹 설정](https://platform.claude.com/docs/ko/managed-agents/tools-web-restrictions#settings)은 MCP 도구에 적용되지 않습니다. 각 `configs` (csharp, go: `Configs`) 항목의 `name` (csharp, go: `Name`)은 서버가 보고하는 그대로의 도구 이름입니다. 기본적으로 MCP 서버가 노출하는 모든 도구가 활성화됩니다. 특정 도구만 활성화하려면 `default_config.enabled`를 `false`로 설정하고 원하는 도구를 명시적으로 활성화하세요: ```json { "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`를 설정하세요: ```json { "type": "mcp_toolset", "mcp_server_name": "github", "configs": [{ "name": "delete_repository", "enabled": false }] } ``` 일반적인 `default_config` (java, php: `defaultConfig`; csharp, go: `DefaultConfig`) / `configs` (csharp, go: `Configs`) 패턴은 [toolset 구성하기](https://platform.claude.com/docs/ko/managed-agents/tools#configuring-the-toolset)를, MCP 도구에 `permission_policy` (java, php: `permissionPolicy`; csharp, go: `PermissionPolicy`)를 설정하고 확인 요청을 처리하는 방법은 [MCP toolset 권한](https://platform.claude.com/docs/ko/managed-agents/permission-policies#mcp-toolset-permissions)을 참조하세요. ### MCP 도구 출력 처리 MCP 도구 출력이 100,000자(약 25,000 토큰)를 초과하면 자동으로 샌드박스의 파일에 기록됩니다. 모델은 파일 경로와 함께 잘린 미리보기를 받으며, 해당 경로에서 전체 내용을 읽을 수 있습니다. ## 세션 생성 시 인증 제공하기 세션을 시작할 때 `vault_ids` (java: `vaultIds`; php: `vaultIDs`; csharp: `VaultIds`; go: `VaultIDs`)를 전달하여 MCP 서버에 대한 자격 증명을 제공합니다. Vault는 한 번 등록하고 ID로 참조하는 자격 증명 모음입니다. vault를 생성하고 자격 증명을 관리하는 방법은 [vault로 인증하기](https://platform.claude.com/docs/ko/managed-agents/vaults)를 참조하세요. `limited` [환경](https://platform.claude.com/docs/ko/managed-agents/environments#networking)에서는 에이전트가 `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`)에 없는 호스트의 MCP 서버를 선언하면 세션 생성이 400 오류로 실패합니다. 환경의 네트워킹 설정에서 `allow_mcp_servers` (java: `allowMcpServers`; php: `allowMCPServers`; csharp: `AllowMcpServers`; go: `AllowMCPServers`)를 `true`로 설정하면 이 검사가 비활성화됩니다. ```bash cURL 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 '{ "agent": "'"$agent_id"'", "environment_id": "'"$environment_id"'", "vault_ids": ["'"$vault_id"'"] }' ``` ```bash CLI ant beta:sessions create \ --agent "$AGENT_ID" \ --environment-id "$ENVIRONMENT_ID" \ --vault-id "$VAULT_ID" ``` ```python Python session = client.beta.sessions.create( agent=agent.id, environment_id=environment.id, vault_ids=[vault.id], ) ``` ```typescript TypeScript const session = await client.beta.sessions.create({ agent: agent.id, environment_id: environment.id, vault_ids: [vault.id] }); ``` ```csharp C# var session = await client.Beta.Sessions.Create(new() { Agent = agent.ID, EnvironmentID = environment.ID, VaultIds = [vault.ID], }); ``` ```go Go session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{ Agent: anthropic.BetaSessionNewParamsAgentUnion{OfString: anthropic.String(agent.ID)}, EnvironmentID: environment.ID, VaultIDs: []string{vault.ID}, }) if err != nil { panic(err) } ``` ```java Java var session = client.beta().sessions().create( SessionCreateParams.builder() .agent(agent.id()) .environmentId(environment.id()) .addVaultId(vault.id()) .build() ); ``` ```php PHP $session = $client->beta->sessions->create( agent: $agent->id, environmentID: $environment->id, vaultIDs: [$vault->id], ); ``` ```ruby Ruby session = client.beta.sessions.create( agent: agent.id, environment_id: environment.id, vault_ids: [vault.id] ) ``` 자격 증명은 URL로 매칭되므로, vault에는 `mcp_server_url` (java: `mcpServerUrl`; php: `mcpServerURL`; csharp: `McpServerUrl`; go: `MCPServerURL`)이 `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`)에 선언된 `url` (csharp: `Url`; go: `URL`)과 동일한 서버를 가리키는 자격 증명이 있어야 합니다. 두 URL은 매칭 전에 정규화되므로(스킴과 호스트는 소문자로 변환되고, 기본 포트와 후행 슬래시는 제거됨) 호스트의 대소문자, 기본 포트, 후행 슬래시의 차이는 매칭을 방해하지 않습니다. 반면 경로, 서브도메인 또는 기본값이 아닌 포트가 다르면 매칭되지 않습니다. 일치하는 항목이 없으면 인증 없이 연결을 시도합니다. `static_bearer` 및 `mcp_oauth` 자격 증명 유형에 대해서는 [자격 증명 추가하기](https://platform.claude.com/docs/ko/managed-agents/vaults#add-a-credential)를 참조하세요. ### 연결 및 인증 실패 처리하기 세션 생성 시에는 MCP 연결이나 자격 증명을 검증하지 않습니다. 다만 선언된 각 서버의 호스트를 환경의 네트워킹 설정과 대조하여 확인합니다. [세션 생성 시 인증 제공하기](https://platform.claude.com/docs/ko/managed-agents/mcp-connector#provide-authentication-at-session-creation)에서 설명한 것처럼, `limited` 환경에서는 호스트가 허용되지 않으면 세션 생성이 400 오류로 실패합니다. MCP 서버에 연결할 수 없거나 서버가 제공된 자격 증명을 거부하더라도 세션은 시작되며 상호작용도 계속 가능합니다. 이때 영향을 받은 서버의 `mcp_server_name` (java, php: `mcpServerName`; csharp: `McpServerName`; go: `MCPServerName`)과 `retry_status` (java, php: `retryStatus`; csharp, go: `RetryStatus`)가 포함된 [`session.error`](https://platform.claude.com/docs/ko/managed-agents/reference#event-types) 이벤트가 발생합니다: | 오류 유형 | 의미 | | --------------------------------- | ----------------------------------------------------------------------------------------------------------- | | `mcp_connection_failed_error` | MCP 서버에 연결할 수 없었습니다(네트워크 오류, 타임아웃, 또는 인증과 무관한 HTTP 실패). | | `mcp_authentication_failed_error` | MCP 서버 인증에 실패했습니다. 서버가 연결된 vault의 자격 증명을 거부했거나, 일치하는 자격 증명이 구성되지 않은 상태에서 인증을 요구했거나, OAuth 토큰 갱신에 실패한 경우입니다. | 이 오류 발생 시 추가 상호작용을 차단할지, 자격 증명 교체를 트리거할지, 또는 영향을 받은 서버의 도구 없이 세션을 계속 진행할지 결정할 수 있습니다. 연결은 다음 `session.status_idle`에서 `session.status_running`으로의 전환 시 재시도됩니다. ## 다음 단계 에이전트 및 MCP 도구가 실행되는 시점을 제어합니다. 이벤트를 전송하고, 응답을 스트리밍하며, 실행 중인 세션을 중단하거나 방향을 전환합니다. 원격 MCP 서버의 전송 요구 사항.