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

MCP использует бизнес-правила и данные API 2.0. Компания определяет разрешённые действия в настройках API-ключа и выбирает общий или индивидуальный доступ.

Общий доступ подходит для интеграции с единым набором разрешений: клиент подключается по App Token и работает с данными всей компании в рамках разрешённых действий. Индивидуальный доступ подходит для подключения сотрудников: каждый проходит OAuth под своей учётной записью MACRO, и действия с ключиком дополнительно учитывают его права в системе.

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

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

#Общий доступ

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

Действия с ключиком в общем режиме работают с данными всей компании. Например, documents.list возвращает документы всей компании, tasks.get — любую задачу компании, finances.get — любую финансовую операцию. Это шире, чем видит отдельный сотрудник в интерфейсе. Разрешайте такие действия, только если интеграции нужен доступ ко всей компании. Если доступ нужно ограничить правами сотрудника, используйте индивидуальный режим.

Исключение — приватные документы: по общему ключу не видны ни они, ни их акты, ни финансовые операции по ним. На запрос такого документа или операции API отвечает так же, как на несуществующий. Работать с приватным документом через API может сотрудник с доступом к нему — через индивидуальный режим. Если документ не конфиденциален, достаточно снять с него признак «Приватный».

Изменения, сделанные по общему ключу, отмечаются в истории названием API-ключа. Файлы, загруженные в документы, отображаются с автором «Система». Изменения задач — переходы по статусам, комментарии, вложения, перенос, смена ответственного, отмена — выполняются от имени постановщика задачи, поэтому действуют его права и ограничения карточки.

Некоторые действия работают только в индивидуальном режиме — например, работа с публикациями блога. По общему ключу такие действия отвечают ошибкой 403.

#Настройте API-ключ

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

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

Authorization: Bearer <токен API-ключа>

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

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

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

#Индивидуальный доступ

В индивидуальном режиме администратор назначает API-ключ сотрудникам, а каждый сотрудник подключается через OAuth. Общий App Token скрыт и для подключения не принимается. Один API-ключ можно назначить нескольким сотрудникам; у каждого будет собственное подключение.

Разрешения API-ключа определяют доступные действия. Если у действия есть ключик, при выполнении дополнительно проверяются актуальные права сотрудника: например, доступ к документу, финансовой операции или задаче. Наличие действия в каталоге само по себе не даёт доступа ко всем записям.

Изменение задач — перенос (tasks.update), смена ответственного (tasks.changeManager), отмена (tasks.cancel), отметка о несостоявшейся встрече (tasks.markNotHeld) — по личному токену недоступно: эти действия выполняются от имени постановщика и работают только по общему ключу.

#Предоставьте доступ сотрудникам

1. Откройте Компания → API-ключи и выберите нужный ключ.
2. Укажите понятное «Название API-ключа»: сотрудник увидит его при подтверждении подключения.
3. Включите «Индивидуальный режим».
4. В поле «Сотрудники с доступом» выберите сотрудников. Можно назначить действующих сотрудников с доступом в компанию, в том числе межкомпанейным. При пустом списке новые подключения запрещены.
5. В разделе «Управление доступами к действиям» разрешите необходимые действия. Обратите внимание на ключик у действия и подсказки над списком действий: они показывают, какие действия учитывают права сотрудника, а какие доступны только по личному токену.
6. Нажмите Сохранить. При включении индивидуального режима подтвердите предупреждение о перевыпуске токена.

Сотрудник может быть назначен только на один API-ключ в каждой компании. Если он уже назначен на другой ключ этой компании, в списке отображается «уже есть доступ». Чтобы переназначить сотрудника, сначала удалите его из прежнего ключа и сохраните изменения.

#Подключитесь от имени сотрудника

1. Войдите в MACRO под своей учётной записью и выберите компанию, в которой вам предоставлен доступ.
2. Во внешнем ИИ-клиенте создайте MCP-подключение к https://api.macroserver.ru/mcp с транспортом Streamable HTTP или HTTP.
3. Выберите авторизацию OAuth и запустите подключение. Клиент должен поддерживать OAuth для MCP; вручную передавать общий App Token не нужно.
4. На странице «Доступ к API» проверьте приложение, компанию, пользователя и название доступа.
5. Нажмите Подтвердить. После подтверждения клиент получает личный токен и загружает каталог инструментов. Кнопка Отклонить отменяет выдачу доступа.

Если клиент позволяет вручную выбрать область доступа OAuth, для этого подключения используется api:access. Доступ к MacroData не заменяет назначение API-ключа для MCP API v2.

Если появляется сообщение «Индивидуальный доступ к API не предоставлен. Обратитесь к администратору компании», проверьте выбранную компанию и попросите администратора проверить ваше назначение в поле «Сотрудники с доступом».

#Измените или прекратите доступ

Администратор может изменить разрешённые действия API-ключа или удалить сотрудника из списка «Сотрудники с доступом» и сохранить изменения. Разрешения действий и применимые права сотрудника проверяются при вызовах.

После удаления назначения уже выданный личный токен действует до окончания своего срока; обновление токена и новое подключение без назначения запрещены. Переназначение на другой API-ключ не меняет права старого подключения: оно остаётся связано с прежним ключом до истечения токена. Токен уволенного или отключённого сотрудника отклоняется при очередном обращении.

Чтобы выключить индивидуальный режим, удалите всех сотрудников из списка и сохраните изменения. После этого выключите переключатель и снова нажмите Сохранить.

#Общие параметры подключения

Если ваша система 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. Загрузка файлов, которая принимает содержимое в base64 или ссылку на файл (например, documents.uploadFile, tasks.uploadFile), через MCP доступна.

После изменения разрешений 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-ключа как отдельные обращения.