Настройка MCP-сервера
Платформа lsFusion может выступать в роли MCP-сервера (Model Context Protocol) для внешних AI-клиентов (например, claude.ai). MCP-сервер работает поверх стандартного HTTP API платформы, поэтому отдельный сервис разворачивать не требуется — достаточно сконфигурировать на сервере приложений два параметра: enableAPI и HTTPS. Сам эндпойнт /mcp обслуживает веб-сервер (Client) приложения, а не HTTP-порт сервера приложений — см. пример URL.
1. Параметр enableAPI
Параметр определяет доступ к программному интерфейсу, через который MCP-клиент обращается к серверу (eval/action, exec и т.п.). Полное описание — в разделе Параметры работы.
| Значение | Поведение |
|---|---|
0 | API полностью выключен (по умолчанию) |
1 | Разрешён только аутентифицированный доступ |
2 | Разрешён анонимный доступ — допустимо только в dev/sandbox-инсталляциях |
Для рабочего приложения значение 2 использовать нельзя: оно открывает API без авторизации.
Приоритетный способ: включение для конкретных ролей
Рекомендуемый способ настройки в production — оставить enableAPI=0 глобально и выставить enableAPI=1 только для тех ролей, которым реально нужно работать с MCP-клиентом (как правило — Administrator или специально заведённая роль для AI-доступа). Тогда MCP-сервером смогут пользоваться только конкретные пользователи, которым назначены эти роли.
Задаётся это в работающей системе через форму Администрирование > Система > Настройки > Параметры — параметр enableAPI со значением 1 привязывается к нужной роли (механизм per-role настроек описан в Параметрах работы).
Альтернативные способы задания
Если по каким-то причинам per-role настройка не подходит, enableAPI можно выставить одним из стандартных способов (в порядке возрастания приоритета — см. Параметры работы):
- В
lsfusion.propertiesпроекта —settings.enableAPI=1. - В
conf/settings.propertiesконкретной инсталляции —settings.enableAPI=1. - В Java-параметрах запуска сервера приложений —
-Dsettings.enableAPI=1. - Глобально в форме
Администрирование > Система > Настройки > Параметры(без привязки к роли).
Самый высокий приоритет — у значения, заданного в БД (форма Параметры), поэтому при расхождении со значением в *.properties срабатывает оно.
2. HTTPS — обязателен
Подключение MCP-сервера к claude.ai (как и к любому другому внешнему MCP-клиенту) допускается только по HTTPS. Публикация MCP-эндпойнта по http:// недопустима.
Развёртывание HTTPS выполняется по схеме, приведённой в конце Автоматической установки. URL MCP-сервера, который прописывается в MCP-клиенте, должен начинаться на https:// и резолвиться в публичный DNS-адрес с валидным сертификатом — самоподписанные сертификаты не подходят, клиент откажется устанавливать соединение.
Пример URL
Эндпойнт MCP-сервера соответствует пути /mcp на веб-сервере (Client) рабочего приложения. То есть URL, который прописывается в MCP-клиенте, формируется как:
https://<url веб-сервера>/mcp
Например, если приложение развёрнуто по адресу https://erp.example.com, URL для прописывания в MCP-клиент будет:
https://erp.example.com/mcp
Обнаружение авторизации при развёртывании не в корне
Когда API требует аутентификации (enableAPI=1), /mcp запускает OAuth-обнаружение, возвращая 401 с заголовком-вызовом WWW-Authenticate: Bearer. Вызов содержит resource_metadata, указывающий на документ метаданных защищаемого ресурса:
https://host/<context>/.well-known/oauth-protected-resource
URL метаданных строятся из внешнего базового URL запроса (scheme://host[:port][/contextPath], с учётом forwarded-заголовков proto/host), поэтому содержимое JSON корректно и при развёртывании под контекстным путём. Например, под https://host/lsfusion метаданные защищаемого ресурса сообщают, что ресурс — https://host/lsfusion, а его сервер авторизации — тоже https://host/lsfusion.
Поэтому цепочка обнаружения такая:
POST /lsfusion/mcp
-> 401 WWW-Authenticate: Bearer resource_metadata="https://host/lsfusion/.well-known/oauth-protected-resource"
GET /lsfusion/.well-known/oauth-protected-resource
-> authorization_servers: ["https://host/lsfusion"]
GET /.well-known/oauth-authorization-server/lsfusion
-> метаданные сервера авторизации
Проблема развёртывания не в корне — на последнем шаге. Для издателя с путём RFC 8414 §3.1 размещает сегмент .well-known в корне хоста и дописывает путь издателя после него, поэтому строгий клиент ищет:
https://host/.well-known/oauth-authorization-server/lsfusion
Веб-приложение, развёрнутое под /lsfusion, владеет только /lsfusion/*, поэтому платформа отдаёт метаданные по URL внутри контекста:
https://host/lsfusion/.well-known/oauth-authorization-server
Сам документ метаданных корректен, как только до него добираются. Вне контекста приложения оказывается лишь строгий URL обнаружения. URL метаданных защищаемого ресурса из заголовка WWW-Authenticate уже находится внутри контекста, поэтому этот шаг работает без переписывания.
Строгий OAuth-клиент не откатывается с корневого URL по RFC 8414 на URL внутри контекста при 404: он прекращает обнаружение, а пользователь видит общую ошибку «не удалось подключиться к серверу» без полезных записей в логе сервера. Коннектор claude.ai ведёт себя именно так.
Исправление делается на HTTP-уровне перед приложением (обратный прокси, ingress или контейнер сервлетов), а не в коде приложения — переписыванием корневого URL обнаружения сервера авторизации обратно в контекст приложения. Для Tomcat (RewriteValve на уровне хоста):
RewriteRule ^/\.well-known/oauth-authorization-server/(.+)$ /$1/.well-known/oauth-authorization-server [L]
RewriteRule ^/\.well-known/openid-configuration/(.+)$ /$1/.well-known/oauth-authorization-server [L]
Правила универсальны: захваченный путь и есть контекстный путь, поэтому они работают для /lsfusion, /mycompany и других развёртываний не в корне. Тот же приём реализуется в обратном прокси или ingress. Вторая строка перенаправляет OIDC-обнаружение на тот же документ метаданных OAuth, поскольку некоторые клиенты во время обнаружения пробуют OIDC-адрес .well-known.
Развёртываниям в корне, где приложение отдаётся прямо по https://host (как в примере https://erp.example.com выше), ничего из этого не нужно: корневой URL и URL внутри контекста совпадают и сводятся к одному /.well-known/oauth-authorization-server.
Агент браузера: WebMCP
Те же инструменты получает и ИИ-агент, встроенный в браузер, — через WebMCP, в браузере, где есть document.modelContext. Включать для этого ничего не нужно: открываясь, страница веб-клиента регистрирует в браузере каждый инструмент, который перечисляет MCP-сервер приложения, и агент вызывает их от имени пользователя, вошедшего в приложение, — в его веб-сессии, без отдельного подключения и OAuth. Доступ к каждому инструменту у агента тот же, что у внешнего MCP-клиента, подключившегося от имени этого пользователя (см. параметр enableAPI).
Инструмент остаётся инструментом сервера: его описание, параметры и результат — те же, что отдаёт /mcp, и выполняется он на сервере, как при вызове через /mcp. Сама страница делает одно: выполняет скрипт lsfusion_eval и действие lsfusion_exec там, где работает пользователь. Где именно, задаёт параметр form инструмента:
form | Где выполняется скрипт | Сессия изменений |
|---|---|---|
| Не задан | В навигаторе, как действие, которое запустил пользователь | Новая на каждый вызов: изменения отбрасываются, если скрипт не применил их сам |
| Задан | В форме — той, которую адресует параметр, а при пустом значении {} в той, в которой находится пользователь, — как действие, которое запустил пользователь | Сессия формы: скрипт видит её неприменённые изменения, а его изменения показываются в форме и применяются вместе с изменениями формы |
Форма, которую показывает скрипт, открывается в браузере пользователя, а сообщение или диалог показывается пользователю, и вызов ждёт его ответа (сообщение, показанное с NOWAIT, вызов не ждёт). Поэтому значение скрипт передаёт агенту как результат действия, а не в сообщении. В форме APPLY или CANCEL в скрипте действуют на сессию формы целиком, включая несохранённые изменения пользователя.
Параметр form адресует одну открытую форму любым сочетанием её имени (name), метки, с которой она открыта (label), и окна, в которое она открыта (window), как оператор ACTIVATE FORM; если адрес не называет ни одной формы или называет несколько, а при {} — если пользователь не находится ни в одной форме, вызов завершается ошибкой. Адрес страница показывает в атрибутах элемента формы: lsfusion-form (имя), lsfusion-form-label и lsfusion-form-window. В форме lsfusion_exec сначала ищет имя действия среди того, что форма открывает своей странице (блок CUSTOMS), и такое действие выполняет при любом enableAPI — так же, как его выполняет страница самой формы.
Через /mcp страницы пользователя нет: скрипт выполняется на сервере, в собственной сессии, новой на каждый вызов, показывать сообщение некому — сообщения возвращаются в результате инструмента, — а вызов с form отклоняется. Страница так скрипт не выполняет.
Параметры скрипта и результат инструмента одинаковы, где бы ни выполнялся скрипт, и где он выполнился, результат не сообщает. Текст от 64 КиБ возвращается рядом с результатом, ресурсом, через /mcp и в самом результате на странице, где ссылка на файл, слишком большой для результата, работает в веб-сессии пользователя.
Кроме инструментов сервера страница регистрирует собственный инструмент lsfusion_client, которого в /mcp нет. Он вызывает метод клиента, там, где работает пользователь: method — имя метода, а args задаёт аргументы метода по их именам. Чей это метод, задаёт параметр form — так же, как он задаёт, где выполняется скрипт: если параметр задан, это метод формы — той, которую он адресует, а при {} той, в которой находится пользователь, — а если не задан, метод навигатора. У навигатора один метод: он активирует элемент навигатора по имени, как щелчок по этому элементу, а имя страница показывает в атрибуте lsfusion-container элемента. Методы формы делают то, что пользователь делает в форме, и форма показывает результат так же, как показывает действия самого пользователя: они изменяют сортировки и пользовательские фильтры таблицы, выбирают фильтр группы фильтров, делают строку текущей, выделяют строки и колонки таблицы, возвращают текст выделенных ячеек и вставляют в них текст, изменяют значение свойства в текущей строке или выполняют его действие, возвращают значения, которые форма предлагает для свойства, количество строк таблицы и сумму по колонке, экспортируют таблицу, раскрывают и сворачивают узлы дерева, делают форму текущей и закрывают её. Методы и их аргументы перечислены в описании инструмента. То, что называет вызов, страница показывает: имя свойства — в атрибуте lsfusion-property его ячеек, заголовка его колонки и его поля в панели, а строку таблицы или дерева — в атрибутах элемента строки: lsfusion-group (группа объектов строки) и lsfusion-row (ключ строки). Строка — одна из тех, что форма показывает; у строк, которые рисует пользовательское представление, эти атрибуты есть, только если представление само их записывает. Вызов выполняется собственными запросами клиента, как и действие пользователя, поэтому от параметра enableAPI он не зависит.