Настройка MCP-сервера
Платформа lsFusion может выступать в роли MCP-сервера (Model Context Protocol) для внешних AI-клиентов (например, claude.ai). MCP-сервер работает поверх стандартного HTTP API платформы, поэтому отдельный сервис разворачивать не требуется — достаточно сконфигурировать на сервере приложений два параметра: enableAPI и HTTPS.
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.