--- title: Коннектор MCP url: https://platform.claude.com/docs/ru/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. **Создание сессии** предоставляет аутентификацию для этих серверов путём ссылки на предварительно зарегистрированное хранилище (см. [Аутентификация с помощью хранилищ](https://platform.claude.com/docs/ru/managed-agents/vaults)). Такое разделение позволяет не включать секреты в переиспользуемые определения агентов, при этом каждая сессия может аутентифицироваться с собственными учётными данными. ## Объявление серверов MCP в агенте Укажите серверы MCP в массиве `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) при создании агента. Каждому серверу нужны `type` (csharp, go: `Type`), уникальное `name` (csharp, go: `Name`) и `url` (csharp: `Url`; go: `URL`). На этом этапе токены аутентификации не предоставляются. Каждому объявленному серверу также нужна соответствующая запись `mcp_toolset` в массиве `tools` (csharp, go: `Tools`). Значение `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 по умолчанию использует политику разрешений `always_ask`, которая требует одобрения пользователя перед каждым вызовом инструмента. См. [политики разрешений](https://platform.claude.com/docs/ru/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 символов). Используется как `mcp_server_name` (java, php: `mcpServerName`; csharp: `McpServerName`; go: `MCPServerName`) в массиве `tools` (csharp, go: `Tools`) и отображается в событиях инструментов MCP в [потоке событий сессии](https://platform.claude.com/docs/ru/managed-agents/events-and-streaming). | | `url` (csharp: `Url`; go: `URL`) | Обязательное. Конечная точка удалённого сервера MCP (до 2 048 символов). Требования к транспорту см. в разделе [Поддерживаемые типы серверов MCP](https://platform.claude.com/docs/ru/managed-agents/reference#supported-mcp-server-types). | Ограничения: * Агент может объявить до 20 серверов MCP. Имена серверов должны быть уникальными в пределах массива. * На каждую запись `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) должен ссылаться `mcp_toolset` в массиве `tools` (csharp, go: `Tools`), и каждый `mcp_toolset` должен ссылаться на объявленный сервер. API отклоняет определения агентов с серверами, на которые нет ссылок, или с висячими наборами инструментов. ## Настройка доступных инструментов MCP Запись `mcp_toolset` поддерживает объект `default_config` (java, php: `defaultConfig`; csharp, go: `DefaultConfig`) и массив `configs` (csharp, go: `Configs`), которые применяются к инструментам, предоставляемым сервером MCP. Каждая запись `configs` (csharp, go: `Configs`) принимает только `name` (csharp, go: `Name`), `enabled` (csharp, go: `Enabled`) и `permission_policy` (java, php: `permissionPolicy`; csharp, go: `PermissionPolicy`). В отличие от записей во встроенном наборе инструментов агента, записи инструментов MCP не принимают поле `type` (csharp, go: `Type`), а [веб-настройки](https://platform.claude.com/docs/ru/managed-agents/tools-web-restrictions#settings), доступные для `web_search` и `web_fetch`, не применяются к инструментам MCP. Значение `name` (csharp, go: `Name`) в каждой записи `configs` (csharp, go: `Configs`) — это простое имя инструмента в том виде, в каком его сообщает сервер. По умолчанию все инструменты, предоставляемые сервером 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 }] } ``` См. [настройку набора инструментов](https://platform.claude.com/docs/ru/managed-agents/tools#configuring-the-toolset) для общего шаблона `default_config` (java, php: `defaultConfig`; csharp, go: `DefaultConfig`) / `configs` (csharp, go: `Configs`), а также [разрешения набора инструментов MCP](https://platform.claude.com/docs/ru/managed-agents/permission-policies#mcp-toolset-permissions) для установки `permission_policy` (java, php: `permissionPolicy`; csharp, go: `PermissionPolicy`) для инструментов MCP и обработки запросов на подтверждение. ### Обработка вывода инструментов MCP Когда вывод инструмента MCP превышает 100 000 символов (около 25 000 токенов), он автоматически записывается в файл в песочнице. Модель получает усечённый предварительный просмотр с путём к файлу и может прочитать полное содержимое оттуда. ## Предоставление аутентификации при создании сессии При запуске сессии передайте `vault_ids` (java: `vaultIds`; php: `vaultIDs`; csharp: `VaultIds`; go: `VaultIDs`), чтобы предоставить учётные данные для ваших серверов MCP. Хранилища — это коллекции учётных данных, которые вы регистрируете один раз и на которые ссылаетесь по ID. О том, как создавать хранилища и управлять учётными данными, см. [Аутентификация с помощью хранилищ](https://platform.claude.com/docs/ru/managed-agents/vaults). При использовании [среды](https://platform.claude.com/docs/ru/managed-agents/environments#networking) с режимом `limited` создание сессии завершается ошибкой 400, если агент объявляет сервер MCP, хост которого отсутствует в `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`). Установка `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, поэтому хранилище должно содержать учётные данные, у которых `mcp_server_url` (java: `mcpServerUrl`; php: `mcpServerURL`; csharp: `McpServerUrl`; go: `MCPServerURL`) указывает на тот же сервер, что и `url` (csharp: `Url`; go: `URL`), объявленный в `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`). Оба URL нормализуются перед сопоставлением (схема и хост приводятся к нижнему регистру, порты по умолчанию и завершающие косые черты удаляются), поэтому различия в регистре хоста, порт по умолчанию или завершающая косая черта не мешают сопоставлению; а другой путь, поддомен или нестандартный порт — мешают. Если совпадений нет, выполняется попытка подключения без аутентификации. Типы учётных данных `static_bearer` и `mcp_oauth` описаны в разделе [Добавление учётных данных](https://platform.claude.com/docs/ru/managed-agents/vaults#add-a-credential). ### Обработка сбоев подключения и аутентификации Создание сессии не проверяет подключение к MCP или учётные данные. Однако оно проверяет хост каждого объявленного сервера на соответствие сетевым настройкам среды: в среде с режимом `limited` создание сессии завершается ошибкой 400, если хост не разрешён, как описано в разделе [Предоставление аутентификации при создании сессии](https://platform.claude.com/docs/ru/managed-agents/mcp-connector#provide-authentication-at-session-creation). Если сервер MCP недоступен или отклоняет предоставленные учётные данные, сессия всё равно запускается, и взаимодействие остаётся возможным. Генерируется событие [`session.error`](https://platform.claude.com/docs/ru/managed-agents/reference#event-types) с `mcp_server_name` (java, php: `mcpServerName`; csharp: `McpServerName`; go: `MCPServerName`) затронутого сервера и `retry_status` (java, php: `retryStatus`; csharp, go: `RetryStatus`): | Тип ошибки | Значение | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `mcp_connection_failed_error` | Не удалось связаться с сервером MCP (сетевая ошибка, тайм-аут или HTTP-сбой, не связанный с аутентификацией). | | `mcp_authentication_failed_error` | Аутентификация на сервере MCP не удалась: сервер отклонил учётные данные из подключённого хранилища, потребовал аутентификацию при отсутствии настроенных подходящих учётных данных, или не удалось обновить токен OAuth. | Вы можете решить, блокировать ли дальнейшее взаимодействие при этой ошибке, инициировать ротацию учётных данных или позволить сессии продолжаться без инструментов затронутого сервера. Повторная попытка подключения выполняется при следующем переходе из `session.status_idle` в `session.status_running`. ## Следующие шаги Управляйте тем, когда запускаются инструменты агента и MCP. Отправляйте события, получайте ответы в режиме потоковой передачи, а также прерывайте или перенаправляйте сессию в процессе выполнения. Требования к транспорту для удалённых серверов MCP.