Коннектор MCP

Claude Managed Agents поддерживает подключение серверов Model Context Protocol (MCP) к вашим агентам. Это даёт агенту доступ к внешним инструментам, источникам данных и сервисам через стандартизированный протокол.

Конфигурация MCP разделена на два шага:

1. Создание агента объявляет, к каким серверам MCP подключается агент, по имени и URL.
2. Создание сессии предоставляет аутентификацию для этих серверов путём ссылки на предварительно зарегистрированное хранилище (см. Аутентификация с помощью хранилищ).

Такое разделение позволяет не включать секреты в переиспользуемые определения агентов, при этом каждая сессия может аутентифицироваться с собственными учётными данными.

Объявление серверов MCP в агенте

Укажите серверы MCP в массиве mcp_servers при создании агента. Каждому серверу нужны type, уникальное name и url. На этом этапе токены аутентификации не предоставляются.

Каждому объявленному серверу также нужна соответствующая запись mcp_toolset в массиве tools. Значение mcp_server_name набора инструментов должно совпадать с name сервера.

ant apply github-assistant.md

---
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_servers

Каждая запись в массиве mcp_servers определяет одно подключение.

Ограничения:

• Агент может объявить до 20 серверов MCP. Имена серверов должны быть уникальными в пределах массива.
• На каждую запись mcp_servers должен ссылаться mcp_toolset в массиве tools, и каждый mcp_toolset должен ссылаться на объявленный сервер. API отклоняет определения агентов с серверами, на которые нет ссылок, или с висячими наборами инструментов.

Настройка доступных инструментов MCP

Запись mcp_toolset поддерживает объект default_config и массив configs, которые применяются к инструментам, предоставляемым сервером MCP. Каждая запись configs принимает только name, enabled и permission_policy. В отличие от записей во встроенном наборе инструментов агента, записи инструментов MCP не принимают поле type, а веб-настройки, доступные для web_search и web_fetch, не применяются к инструментам MCP. Значение name в каждой записи configs — это простое имя инструмента в том виде, в каком его сообщает сервер.

По умолчанию все инструменты, предоставляемые сервером 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. О том, как создавать хранилища и управлять учётными данными, см. Аутентификация с помощью хранилищ.

При использовании среды с режимом limited создание сессии завершается ошибкой 400, если агент объявляет сервер MCP, хост которого отсутствует в allowed_hosts. Установка allow_mcp_servers в true в сетевых настройках среды отключает эту проверку.

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

Учётные данные сопоставляются по URL, поэтому хранилище должно содержать учётные данные, у которых mcp_server_url указывает на тот же сервер, что и url, объявленный в mcp_servers. Оба URL нормализуются перед сопоставлением (схема и хост приводятся к нижнему регистру, порты по умолчанию и завершающие косые черты удаляются), поэтому различия в регистре хоста, порт по умолчанию или завершающая косая черта не мешают сопоставлению; а другой путь, поддомен или нестандартный порт — мешают. Если совпадений нет, выполняется попытка подключения без аутентификации. Типы учётных данных static_bearer и mcp_oauth описаны в разделе Добавление учётных данных.

Обработка сбоев подключения и аутентификации

Создание сессии не проверяет подключение к MCP или учётные данные. Однако оно проверяет хост каждого объявленного сервера на соответствие сетевым настройкам среды: в среде с режимом limited создание сессии завершается ошибкой 400, если хост не разрешён, как описано в разделе Предоставление аутентификации при создании сессии. Если сервер MCP недоступен или отклоняет предоставленные учётные данные, сессия всё равно запускается, и взаимодействие остаётся возможным. Генерируется событие session.error с mcp_server_name затронутого сервера и retry_status:

Вы можете решить, блокировать ли дальнейшее взаимодействие при этой ошибке, инициировать ротацию учётных данных или позволить сессии продолжаться без инструментов затронутого сервера. Повторная попытка подключения выполняется при следующем переходе из session.status_idle в session.status_running.

Следующие шаги