Коннектор MCP

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

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

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

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



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

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

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

AGENT_ID=$(ant beta:agents create \
  --name "GitHub Assistant" \
  --model claude-opus-4-8 \
  --mcp-server '{type: url, name: github, url: "https://api.githubcopilot.com/mcp/"}' \
  --tool '{type: agent_toolset_20260401}' \
  --tool '{type: mcp_toolset, mcp_server_name: github}' \
  --transform id --raw-output)



Справочник по полю mcp_servers

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

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

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



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

Запись mcp_toolset поддерживает ту же структуру default_config и configs, что и встроенный набор инструментов агента, применяемую к инструментам, которые предоставляет сервер 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 токенов, он автоматически записывается в файл в песочнице. Модель получает усечённый предварительный просмотр с путём к файлу и может прочитать полное содержимое оттуда.



Предоставление аутентификации при создании сессии

При запуске сессии передайте vault_ids, чтобы предоставить учётные данные для ваших серверов MCP. Хранилища (vaults) — это коллекции учётных данных, которые вы регистрируете один раз и на которые ссылаетесь по идентификатору. См. Аутентификация с помощью хранилищ, чтобы узнать, как создавать хранилища и управлять учётными данными.

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

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



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

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

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



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