Интеграция MCP (Model Context Protocol)

MCP служит для соединения интеллектуальных агентов с внешними инструментами. aihelpme.ru поддерживает подключение внешних MCP-сервисов, а также предоставляет собственный MCP-сервер для вызова другими клиентами:

1. aihelpme.ru как MCP-клиент: в разделе «Инструменты → Сервисы MCP» можно подключить любой внешний MCP-сервер (SSE или Streamable HTTP). Его инструменты загружаются по требованию и доступны агенту в диалоге. Поддерживаются три стратегии аутентификации: API Key / Bearer / OAuth 2.0 (с динамической регистрацией клиента и PKCE, возможностью указать заранее зарегистрированного клиента, а также с JWT Bearer Assertion для получения токена от имени пользователя), включение/выключение инструментов поштучно, ручное подтверждение вызова и OAuth-авторизация в рамках диалога (in-conversation).
2. aihelpme.ru как MCP-сервер: в разделе «Настройки → Публикация интеграций → MCP-сервер» можно создать один или несколько MCP-эндпоинтов для текущего пространства. У каждого эндпоинта свой токен, своя область доступа к базам знаний и свой список доступных инструментов. Клиенты MCP (Claude Desktop, Cursor, Claude Code, VS Code Copilot и др.) подключаются по Streamable HTTP напрямую, без развёртывания дополнительного процесса. Python-сервис в mcp-server/ является устаревшим решением и помечен как deprecated.

Подключение внешних сервисов расширяет инструментарий агента aihelpme.ru. Запуск MCP-сервера aihelpme.ru даёт внешним клиентам доступ к поиску в базах знаний, ответам на вопросы и управленческим возможностям.

Администратор пространства может создать сервис в боковой панели «Инструменты → Сервисы MCP» (старый пункт «Настройки → Сервисы MCP» автоматически перенаправляет туда). После заполнения подключения нужно синхронизировать инструменты и добавить описание их использования, после чего выбрать нужные сервисы в настройках агента. Если требуется контролировать операции записи или внешние вызовы, для соответствующих инструментов можно включить ручное подтверждение — перед вызовом будет показана карточка подтверждения.

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

---

Подключение внешних инструментов

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

Создание сервиса состоит из двух шагов:

1. Настройка подключения: укажите название и URL сервиса, выберите транспорт SSE или Streamable HTTP, настройте аутентификацию (нет / пользовательский заголовок, API Key / Token, OAuth 2.0), таймаут и повторы. Также можно использовать «Импорт из кода»: вставьте стандартный JSON mcpServers — форма заполнится автоматически. Конфигурации stdio с command/args не поддерживаются. После сохранения можно выполнить тест подключения. Для OAuth-сервисов кнопка «Перейти к авторизации» сначала автоматически сохранит конфигурацию, затем инициирует авторизацию от имени текущего пользователя.
2. Инструменты и описание использования: после подключения и получения списка инструментов система сохранит полное описание инструментов и их параметров. Далее заполните поле «Описание использования» — укажите назначение сервиса, подходящие сценарии и ключевые ограничения. После синхронизации инструментов доступна кнопка «Сгенерировать с помощью ИИ» — она создаст краткое описание на основе включённых инструментов, которое можно проверить и сохранить. В списке инструментов можно по отдельности включать/отключать инструмент и требовать ручного подтверждения вызова — изменения применяются сразу, при обновлении каталога эти настройки не перезаписываются.

Модель сначала считывает описание использования сервиса, а затем по необходимости загружает конкретные инструменты, поэтому это описание напрямую влияет на то, выберет ли агент нужный сервис. Для OAuth-сервисов авторизация привязана к конкретному пользователю. Если для инструмента включено ручное подтверждение, в диалоге отобразится карточка с параметрами для одобрения. Отключённый инструмент никогда не будет вызван во время работы агента. MCP-клиент aihelpme.ru не поддерживает транспорт stdio.

Если вызов инструмента одобрен вручную, но при этом OAuth-авторизация отсутствует или истекла, в диалоге появится ссылка на повторную OAuth-авторизацию. Ручное подтверждение и авторизация у внешнего сервиса — независимые шаги. Для вызывающих без браузера можно использовать JWT Bearer Assertion для получения токена от своего субъекта — при условии, что вышестоящий сервис поддерживает такой способ авторизации (см. OAuth API).

Предоставление доступа внешним клиентам

В разделе «Настройки → Публикация интеграций → MCP-сервер» создайте эндпоинт: укажите название, выберите доступные базы знаний (пустое значение — все), отметьте инструменты для публикации, при необходимости укажите агент по умолчанию для инструмента ask (если не указано — используется встроенный быстрый ответ) и ограничение количества вызовов в минуту (по умолчанию 60).

После создания на экране однократно отобразятся токен и адрес https://<домен>/mcp/<endpoint_id>. Там же будут приведены готовые фрагменты конфигурации для Cursor, VS Code, Claude Desktop, команда для Claude Code и вариант для клиентов, поддерживающих только stdio, с использованием моста mcp-remote.

При использовании кастомного обратного прокси, помимо маршрута /api/, необходимо проксировать и /mcp/ на бэкенд aihelpme.ru с сохранением заголовков Authorization, заголовков протокола MCP, без буферизации ответа и с достаточными таймаутами чтения/записи для long-polling/потоков. В стандартном Nginx-конфиге, конфиге Vite dev/preview и в готовых шаблонах сайта эти правила уже предусмотрены — можно подключаться по домену сайта без прямого доступа к порту 8080 бэкенда.

В одном пространстве можно создать несколько эндпоинтов. Например, для службы поддержки — эндпоинт только с поиском и вопрос-ответом по ограниченному набору БЗ, для контент-команды — с доступом к инструментам записи. Токен можно в любой момент перевыпустить, эндпоинт — отключить или удалить. При удалении эндпоинта все клиенты, использующие его, мгновенно теряют доступ.

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

Группа	Инструменты	Описание
Поиск и чтение	list_knowledge_bases, search_knowledge, grep_chunks, list_documents, read_document	Параметр knowledge_base принимает ID или название. search_knowledge поддерживает mode (hybrid/semantic/keyword) и limit (по умолчанию 10, максимум 30). grep_chunks использует регистронезависимую семантику регулярного выражения: из шаблона извлекаются буквальные токены для полнотекстового поиска (если у БЗ нет полнотекстового индекса — используется семантический поиск для отбора кандидатов), затем каждый фрагмент проверяется регуляркой. Шаблоны без буквальных токенов (например, ^\d+$) отклоняются. read_document поддерживает пагинацию offset/limit либо поиск фразы внутри документа через query.
Вопрос-ответ	ask	Всегда использует агента по умолчанию, настроенного для эндпоинта (клиент не может выбрать другого). Если агент не настроен — встроенный быстрый ответ. Сервер автоматически создаёт сессию, возвращает полный ответ со ссылками и session_id; для продолжения диалога передайте его обратно. Веб-поиск при вызове через этот эндпоинт не используется.
Wiki	wiki_search, wiki_read_page, wiki_index	Действуют только для БЗ с включённой Wiki. wiki_search сохраняет оригинальную семантику регулярного выражения (регистронезависимую): если шаблон не является валидным regex — выполняется точное посимвольное совпадение по буквальному тексту. regex=false принудительно включает буквальное совпадение, regex=true требует валидного регулярного выражения.
Запись	add_document, update_document, delete_document	По умолчанию выключены. Поддерживается импорт Markdown-текста или по URL.

Результаты вызова существующих MCP-инструментов автоматически преобразуются с учётом ссылок на ресурсы REST/IM: изображения в тексте, содержимом Wiki и в структурированных данных конвертируются в доступные по HTTP(S) ссылки после проверки прав доступа. Для этого не требуется добавлять новые инструменты или менять список инструментов эндпоинта. В ask поле references[].images сохраняет URL изображения, подпись и текст OCR; список текстовых ссылок также включает ссылки на изображения, чтобы не потерять их при обрезке сводки ответа.

Для локального или приватного хранилища необходимо настроить APP_EXTERNAL_URL, доступный внешнему клиенту, и убедиться, что прокси пробрасывает маршрут /r/. Изображения в формате resource:// преобразуются во временные ссылки /r/<token> с ограниченным сроком действия. Для прочих бэкендов используются HTTP(S)-URL, сгенерированные соответствующим хранилищем. В рамках одного вызова инструмента один и тот же ресурс преобразуется только один раз; возвращаемые ссылки не сохраняются в документе и не пишутся в историю сессии. Если ссылку сгенерировать нельзя — исходная ссылка остаётся без изменений, текстовый результат при этом не прерывается.

Перед генерацией ссылки повторно проверяется соответствие области видимости эндпоинта (доступные БЗ), права общего доступа, принадлежность ресурса пространству и привязка к действующему документу — применяются те же правила, что и для предпросмотра изображений в БЗ. У эндпоинта без ограничений по БЗ проверка ведётся по списку БЗ, доступных вызывающему пользователю, поэтому изображения из общедоступных БЗ, найденные агентом в рамках ask, также могут быть преобразованы. Оригинальные загруженные файлы не получают ссылки на скачивание только потому, что упомянуты в тексте ответа. Для исторических документов без привязки изображений к файлам необходимо, чтобы пользователь с правами администратора повторно провёл разбор документа — после этого при повторном поиске привязка появится и ссылки станут доступными. Автоматически дозаполнять права доступа по редактируемому тексту или по image_info нельзя.