MCP API v2 подключает ИИ-клиент к API 2.0 MACRO по стандарту Model Context Protocol. Клиент получает единый каталог доступных инструментов и может читать или изменять данные MACRO без отдельной настройки каждого метода API.

MCP использует те же бизнес-правила, данные и права доступа, что и API 2.0. Состав инструментов определяется разрешениями API-ключа: клиент видит только те действия, которые доступны этому ключу.

Для настройки доступа в главном меню MACRO выберите раздел Компания → API-ключи. Само MCP-подключение создаётся во внешнем ИИ-клиенте.

#Как подключиться

#Подготовьте API-ключ

1. Откройте раздел Компания → API-ключи.
2. Создайте отдельный API-ключ для ИИ-клиента или выберите существующий.
3. Разрешите только те действия API, которые потребуются клиенту.
4. Сохраните настройки и нажмите Скопировать, чтобы получить реквизиты подключения.

В заголовок авторизации передаётся токен API-ключа:

Authorization: Bearer <токен>

Отдельный заголовок AppID для ключей нового формата не требуется: идентификатор приложения уже содержится в токене.

#Добавьте MCP-сервер в ИИ-клиент

Создайте в клиенте новое MCP-подключение со следующими параметрами:

Если ваша система MACRO размещена на другом сервере, замените api.macroserver.ru адресом API вашего сервера. Адрес можно уточнить в поддержке MACRO.

Сервер поддерживает версии протокола MCP 2025-06-18 и 2025-03-26. Использовать подключение через SSE не нужно.

После сохранения подключения клиент:

1. Выполняет initialize.
2. Получает идентификатор сессии в заголовке Mcp-Session-Id.
3. Загружает список инструментов через tools/list.
4. Передаёт Mcp-Session-Id при последующих вызовах.

Сессия действует 30 минут с момента последнего успешного запроса. При истечении сессии клиенту необходимо повторно выполнить initialize.

#Проверьте подключение

После подключения убедитесь, что клиент получил каталог инструментов.

В каталоге всегда доступны справочные инструменты:

Без параметров справочный инструмент возвращает доступные группы, термины или сценарии. Для получения подробностей передайте выбранный ключ в параметре group, term или scenario.

Остальной состав каталога зависит от разрешений API-ключа. Например:

estateBuy.create ↔ /v2/estateBuy/create
company.getUsers ↔ /v2/company/getUsers

Название MCP-инструмента состоит из группы и действия, разделённых точкой.

#Как работать с инструментами

Для каждого инструмента клиент получает:

• название и описание;
• схему входных параметров;
• признак операции только для чтения;
• признак изменения или удаления данных;
• признак безопасного повторного вызова;
• признак обращения к внешней системе.

Эти сведения помогают ИИ-клиенту выбрать подходящий инструмент и определить, требует ли действие дополнительного подтверждения пользователя.

Для сложного процесса сначала используйте help.workflow. Например, справочник содержит сценарии создания заявки, бронирования квартиры, проведения сделки и оформления передачи ключей.

Если в названии или описании встречается незнакомый термин, используйте help.glossary. Чтобы найти нужную область каталога, используйте help.tools.

Подробные схемы параметров и ответов отдельных методов находятся в документации API 2.0Переход на внешний сайтhttps://api.macroserver.ru/docs/api/v2/.

#Особенности каталога

MCP публикует только методы API v2, которые:

• разрешены текущему API-ключу;
• принимают и возвращают данные в формате JSON;
• не помечены как устаревшие или скрытые;
• имеют совместимый с MCP контракт.

Через MCP недоступны загрузка файлов, бинарные ответы и методы, работающие только с multipart/form-data или application/octet-stream. Для них используйте обычный API v2.

После изменения разрешений API-ключа переподключите MCP-сервер или обновите каталог инструментов в клиенте.

#Подключение собственного клиента

Собственный MCP-клиент должен соблюдать следующую последовательность:

1. Отправить initialize методом POST без заголовка Mcp-Session-Id.
2. Сохранить Mcp-Session-Id из заголовка ответа.
3. Отправить уведомление notifications/initialized.
4. Вызывать tools/list, tools/call и ping с тем же токеном и идентификатором сессии.
5. Для явного закрытия сессии отправить DELETE /mcp с теми же заголовками Authorization и Mcp-Session-Id.

Пример вызова инструмента:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "company.getDepartments",
    "arguments": {}
  }
}

Успешный ответ содержит результат API v2 в поле structuredContent. Если API v2 отклонил операцию по бизнес-правилу, результат содержит isError: true и описание ошибки. Это ошибка конкретного действия, а не MCP-подключения.

#Возможные ошибки

Вызовы tools/list и tools/call учитываются в лимите API-ключа как отдельные обращения.