Коннектор 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 сервера.

AGENT_ID=$(ant beta:agents create --transform id --raw-output < github-assistant.agent.yaml)

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

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 или учётные данные. Если сервер MCP недоступен или отклоняет предоставленные учётные данные, сессия всё равно запускается, и взаимодействие остаётся возможным. Генерируется событие session.error с mcp_server_name затронутого сервера и retry_status:

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

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