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

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.



Дальнейшие шаги