MCP и AI-ассистенты

MCP позволяет AI-ассистенту читать данные HCAPP по вашему запросу: показывать задачи, анализировать их поля и составлять сводки по комментариям. Вы задаёте вопрос обычным языком, а ассистент получает данные через подключение HCAPP.

Пилотная версия

Подключение требует включения MCP на сервере HCAPP и регистрации вашего AI-приложения администратором. Уточните доступность перед настройкой. Первая версия предназначена только для чтения; совместимость с конкретным AI-клиентом нужно проверить при подключении.

Что можно делать

• Посмотреть доступные боту формы и права.
• Получить задачи формы с фильтрами по датам, автору, ответственному и статусу.
• Прочитать поля отдельной задачи и её комментарии.
• Догрузить следующие страницы задач и комментариев для анализа.

Создание, изменение и удаление задач, отправка комментариев через MCP пока недоступны. Это ограничение самого подключения, даже если у бота есть более широкие права в обычном Bot API.

Что нужно для подключения

1. AI-приложение с поддержкой удалённого MCP через Streamable HTTP и OAuth. Подключение не привязано к одной модели или производителю.
2. Зарегистрированное администратором подключение этого приложения. В пилотной версии регистрация ручная: не все MCP-клиенты поддерживают такой способ настройки.
3. Отдельный пользователь HCAPP с ролью BOT и действующим Bot API токеном.
4. Доступ бота к нужным формам с правами «Только чтение».

Создание бота и выдача токена описаны в разделе Пользователи. Права задаются во вкладке Access каждой формы.

В первой версии аналитика работает с формами, где боту разрешено читать все задачи. Формы с ограничениями на отдельные задачи пока недоступны через MCP. Не расширяйте доступ к конфиденциальным задачам только ради подключения.

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

1. В настройках AI-приложения добавьте удалённый MCP-сервер. Названия пунктов меню могут отличаться.

2. Укажите адрес HCAPP:

   https://api.hcapp.ee/mcp

   Для тестового сервера используйте адрес, выданный администратором. Адрес выше относится к production и заработает после включения MCP в этом окружении.

3. Выберите OAuth. В опубликованном плагине Client ID и Client Secret уже настраивает владелец интеграции. При ручном подключении эти поля заполняет администратор интеграции. Bot-токен в эти поля не вставляется.

4. Начните подключение. Откроется страница HCAPP с названием приложения, которому предоставляется доступ.

5. Вставьте Bot API токен в поле на странице HCAPP и разрешите чтение.

6. Вернитесь в AI-приложение, выберите подключение HCAPP и попросите показать доступные формы.

Не отправляйте Bot-токен в чат с ассистентом. OAuth здесь связывает AI-приложение с HCAPP: пользователь подтверждает доступ своим Bot-токеном, а приложение получает отдельный ключ только для чтения.

MCP-подключение действует до 8 часов. После истечения срока подключитесь заново. Если Bot-токен истёк или был отозван раньше, доступ прекратится раньше.

Примеры запросов

После подключения можно попросить:

Покажи формы HCAPP, доступные для аналитики.

Покажи задачи формы «Заявки», созданные за последние семь дней.

Прочитай задачу с ID 123 и кратко перескажи её комментарии.

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

Используйте названия и ID из своей компании. В отчётах уточняйте период и просите ассистента указать, сколько задач он прочитал и остались ли ещё страницы.

Фильтры и загрузка данных

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

За один запрос возвращается до 50 записей. При чтении задачи сначала загружаются 20 комментариев; остальные можно догрузить отдельно. Одна страница не является полным списком: для итогов по всей форме ассистент должен прочитать все подходящие страницы.

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

Лимиты запросов

MCP и Bot API используют общие квоты чтения на одного бота: до 300 чтений задачи, 60 запросов списка задач, 60 запросов списка форм и 60 запросов комментариев в минуту. Смена AI-приложения или IP не даёт дополнительную квоту. get_task расходует квоты задачи и комментариев одновременно.

Дополнительно MCP ограничивает общее число запросов: 120 в минуту на бота и 300 на IP, включая служебные запросы подключения. При превышении возвращается 429 с заголовком Retry-After: повторите запрос после указанной задержки.

Как ассистент узнаёт о возможностях HCAPP

Публикация этой инструкции не подключает HCAPP к AI-приложениям автоматически. Сначала пользователь или администратор добавляет адрес MCP и разрешает доступ. После подключения клиент запрашивает описание сервера и доступные инструменты; загружать описание Bot API вручную не нужно.

Инструмент	Назначение
list_forms	Формы бота и возможность чтения через аналитику (analytics_read)
list_tasks	Список задач формы с фильтрами и следующими страницами
get_task	Поля задачи и первая страница комментариев
list_comments	Чтение и догрузка комментариев

Доступ и отключение

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

Права, активность бота и действие токена проверяются на каждом MCP-запросе. Чтобы прекратить доступ, отзовите Bot-токен, заблокируйте бота или уберите его доступ к нужной форме. Уже переданные в AI-приложение данные это не удаляет.

Если подключение не работает:

• Адрес MCP недоступен — уточните у администратора, включён ли MCP в выбранном окружении.
• Ошибка OAuth или адреса возврата — администратору нужно проверить регистрацию AI-приложения; замена Bot-токена эту ошибку не исправляет.
• Подключение истекло — подключитесь заново с действующим Bot-токеном.
• Форма не видна или недоступна для аналитики — проверьте права бота и ограничения на отдельные задачи.

Связанные разделы

• Внешние интеграции
• Пользователи и боты
• Доступы к формам
• Аутентификация Bot API

Страница разрешения доступа

Страница HCAPP доступна на русском и английском: показывает название приложения и какие данные оно сможет читать. Здесь нужен только Bot API токен того же окружения. Обычный пароль HCAPP не даёт доступ к MCP.

Ошибочный токен можно исправить на странице. У бота должна быть хотя бы одна форма, доступная для аналитики. «Отмена» возвращает в приложение без выдачи доступа. Если ссылка истекла, начните подключение заново из AI-приложения.

В опубликованном плагине Client ID и Client Secret настраивает владелец интеграции. Пользователю не нужно получать или генерировать этот секрет. При ручной настройке подключения эти поля заполняет администратор интеграции.

Какие данные получает ассистент

Приложение получает запрошенные формы, задачи и комментарии в пределах прав бота. Исходный Bot-токен не передаётся ассистенту: HCAPP выдаёт отдельный ключ только для чтения. Отзыв доступа останавливает новые запросы, но не удаляет данные, уже полученные AI-провайдером. Перед подключением данных компании проверьте настройки обработки данных у этого провайдера.

Поддержка

Напишите на support@hcapp.ee: укажите окружение, приложение и текст ошибки. Не отправляйте токены и секреты. Политика конфиденциальности и условия HCAPP.

Фильтры по полям

Ассистент получает ID, названия, типы полей и допустимые операции через list_form_fields, затем передаёт field_filters в list_tasks. Условия объединяются через И и применяются в базе до пагинации.

Для «неоплаченных счетов Speedtrans» он сначала ищет по значению поля названия в доступной форме контрагентов. Полученный ID задачи использует в условии linked_task_eq поля контрагента в расходах, вместе с условием по остатку, например gt: 0. При нескольких совпадениях требуется уточнение. Нужно определить правильное поле остатка и его смысл, а не считать любую сумму задолженностью.

Для текста доступны сравнение без учёта регистра и поиск подстроки; для чисел — сравнения; для дат — сравнения ISO-дат с часовым поясом. У поля-периода сравнивается начало. Существующие диапазоны по дате создания и основной дате формы сохраняются. Есть условия «пусто»/«не пусто». Вложенные колонки таблиц и неподдерживаемые типы пока не фильтруются: сервер сообщает об ошибке, а не пропускает условие.

ID связанной формы раскрывается только при наличии доступа бота. Для поиска контрагента по названию нужен доступ к его форме. После обновления сервера обновите список инструментов AI-клиента или переподключите MCP.