MCP 커넥터

MCP 커넥터 (MCP connector)

Claude Managed Agents는 Model Context Protocol (MCP) 서버를 에이전트에 연결하는 것을 지원해요. 이렇게 하면 에이전트가 표준화된 프로토콜을 통해 외부 도구, 데이터 소스, 서비스에 접근할 수 있어요. MCP 구성은 두 단계로 나뉘어요: 에이전트 생성 시 이름과 URL로 서버를 선언하고, 세션 생성 시 사전 등록된 볼트(vault)를 참조해 인증을 제공하죠. 이 분리 덕분에 재사용 가능한 에이전트 정의에서 비밀값을 빼내면서도 각 세션이 자신의 자격 증명으로 인증할 수 있어요.

출처: 문서

본문

Claude Managed Agents는 Model Context Protocol (MCP) 서버를 에이전트에 연결하는 것을 지원해요. 이것은 에이전트가 표준화된 프로토콜을 통해 외부 도구, 데이터 소스, 서비스에 접근하게 해줘요.

MCP 구성은 두 단계로 나뉘어요:

  1. Agent creation declares which MCP servers the agent connects to, by name and URL.
  2. Session creation supplies authentication for those servers by referencing a pre-registered vault (see Authenticate with vaults).

이 분리는 재사용 가능한 에이전트 정의에서 비밀값을 빼내면서도, 각 세션이 자신의 자격 증명으로 인증하게 해줘요.

Declare MCP servers on the agent

에이전트를 만들 때 mcp_servers 배열에서 MCP 서버를 지정하세요. 각 서버는 type, 고유한 name, url이 필요해요. 이 단계에서는 인증 토큰이 제공되지 않아요.

선언된 각 서버는 tools 배열에 짝이 되는 mcp_toolset 항목도 필요해요. 도구세트의 mcp_server_name은 서버의 name과 일치해야 해요.

```bash cURL agent_response=$(curl -sS --fail-with-body https://api.anthropic.com/v1/agents \ -H "x-api-key: $ANTHR...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-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"} ] } EOF ) agent_id=$(jq -r '.id' <<<"$agent_response") ``` ```bash CLI ant apply github-assistant.md ``` 
<File filename="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
  ---
  ```
</File>

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"},
    ],
)

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" },
  ],
});

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" },
    ],
});

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)
}

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()
);

$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',
        ),
    ],
);

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"}
  ]
)
The MCP toolset defaults to a permission policy of `always_ask`, which requires user approval before each tool call. See [permission policies](https://platform.claude.com/docs/en/managed-agents/permission-policies) to configure this behavior.

mcp_servers field reference

mcp_servers 배열의 각 항목은 하나의 연결을 정의해요.

Field Description
type Required. Must be "url".
name Required. A unique name for this server within the agent (1–255 characters). Used as the mcp_server_name in the tools array and surfaced on MCP tool events in the session event stream.
url Required. The endpoint of the remote MCP server (up to 2,048 characters). See Supported MCP server types for transport requirements.

제약사항:

  • An agent can declare up to 20 MCP servers. Server names must be unique within the array.
  • Every mcp_servers entry must be referenced by an mcp_toolset in the tools array, and every mcp_toolset must reference a declared server. The API rejects agent definitions with unreferenced servers or dangling toolsets.

Configure which MCP tools are available

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 패턴은 configuring the toolset을, MCP 도구에 permission_policy를 설정하고 확인 요청을 처리하는 방법은 MCP toolset permissions을 참고하세요.

MCP tool output handling

MCP 도구 출력이 100,000자(약 25,000토큰)를 넘으면 자동으로 샌드박스의 파일에 기록돼요. 모델은 파일 경로가 포함된 잘린 미리보기를 받고, 거기서 전체 내용을 읽을 수 있어요.

Provide authentication at session creation

세션을 시작할 때 vault_ids를 전달해 MCP 서버용 자격 증명을 제공하세요. 볼트는 한 번 등록하고 ID로 참조하는 자격 증명 모음이에요. 볼트를 만들고 자격 증명을 관리하는 방법은 Authenticate with vaults를 참고하세요.

```bash cURL session_response=$(curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \ -H "x-api-key: $ANTHR...KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: managed-agents-2026-04-01" \ -H "content-type: application/json" \ -d @- <SESSION_ID=$(ant beta:sessions create \ --agent "$AGENT_ID" \ --environment-id "$ENVIRONMENT_ID" \ --vault-id "$VAULT_ID" \ --transform id --raw-output) 
session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
)

const session = await client.beta.sessions.create({
  agent: agent.id,
  environment_id: environment.id,
  vault_ids: [vault.id],
});

var session = await client.Beta.Sessions.Create(new()
{
    Agent = agent.ID,
    EnvironmentID = environment.ID,
    VaultIds = [vault.ID],
});

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)
}

var session = client.beta().sessions().create(
    SessionCreateParams.builder()
        .agent(agent.id())
        .environmentId(environment.id())
        .addVaultId(vault.id())
        .build()
);

$session = $client->beta->sessions->create(
    agent: $agent->id,
    environmentID: $environment->id,
    vaultIDs: [$vault->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 자격 증명 유형은 Add a credential를 참고하세요.

Handle connection and authentication failures

세션 생성은 MCP 연결이나 자격 증명을 검증하지 않아요. MCP 서버에 도달할 수 없거나 제공한 자격 증명을 거부해도 세션은 여전히 시작되고 상호작용은 가능해요. 영향을 받은 서버의 mcp_server_name과 retry_status를 담은 session.error 이벤트가 발행돼요:

Error type Meaning
mcp_connection_failed_error The MCP server could not be reached (network error, timeout, or non-authentication HTTP failure).
mcp_authentication_failed_error Authentication with the MCP server failed: the server rejected the credential from the attached vault, required authentication when no matching credential was configured, or an OAuth token refresh failed.

이 오류에서 추가 상호작용을 차단할지, 자격 증명 회전을 트리거할지, 영향을 받은 서버의 도구 없이 세션을 계속하게 할지 결정할 수 있어요. 연결은 다음 session.status_idle에서 session.status_running 전환 시 재시도돼요.

Next steps

Control when agent and MCP tools run. Send events, stream responses, and interrupt or redirect your session mid-execution. Transport requirements for remote MCP servers.

더 알아보기 (Learn more)