Шаблоны MCP-сервера для Trialix

Если у вашей системы нет готового коннектора в Trialix, её можно обернуть в MCP-сервер и подключить как «MCP-сервер». Модель в чате и агентах Trialix будет искать, читать и создавать записи в вашей системе через инструменты, которые вы опишете.

MCP (Model Context Protocol) - открытый стандарт подключения инструментов к моделям. Trialix работает как MCP-клиент: обращается к вашему серверу по Streamable HTTP, получает список инструментов и вызывает их.

Здесь два шаблона с одинаковым поведением:

Если разницы нет, берите тот язык, на котором у вас уже есть код доступа к системе.

В обоих шаблонах условная система заявок и три инструмента:

Данные лежат в памяти. В коде отмечено, где подключить свою БД или API: достаточно переписать класс OrderStore.

Как устроен шаблон

• Один адрес /mcp, запросы JSON-RPC 2.0 методом POST. Ответ - обычный JSON (Trialix понимает и поток SSE, если вы его включите).
• Сервер без сессий: каждый запрос самостоятельный. Можно запустить несколько копий за балансировщиком.
• Доступ по токену: каждый запрос должен нести заголовок Authorization: Bearer <токен>. Токен задаётся переменной MCP_TOKEN, без неё или с токеном короче 32 символов сервер не стартует. Запрос без токена или с чужим токеном получает 401.
• GET /health без токена отвечает ok, это проверка живости для Docker и балансировщика.
• Версия протокола - 2025-06-18, её использует Trialix. SDK поддерживают и более ранние версии.

Запуск на своей машине

Нужен Docker. Команды для Python, для Node.js замените python на node:

cd python
docker build -t mcp-orders .
export MCP_TOKEN="$(openssl rand -hex 32)"
docker run --rm -p 127.0.0.1:8000:8000 -e MCP_TOKEN="$MCP_TOKEN" mcp-orders

Проверка из другого окна:

curl -s http://127.0.0.1:8000/mcp \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-06-18' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

В ответе будут три инструмента. Вызов инструмента:

curl -s http://127.0.0.1:8000/mcp \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-06-18' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_orders","arguments":{"query":"Альфа"}}}'

Интерактивно сервер удобно смотреть в MCP Inspector: npx @modelcontextprotocol/inspector, транспорт Streamable HTTP, адрес http://127.0.0.1:8000/mcp, заголовок Authorization с токеном.

Как запустить без Docker, написано в README каждого шаблона.

Свои инструменты

1. Замените OrderStore на свой код доступа к системе. Для чтения заведите в системе отдельную учётную запись с минимальными правами.
2. Опишите инструменты. Описание инструмента и параметров читает модель: пишите, когда инструмент вызывать и что он вернёт. Хорошее описание важнее хорошего имени.
3. Отдавайте ответ компактным JSON и только нужные поля. Большие списки ограничивайте (в шаблоне до 20 записей): Trialix обрезает слишком длинные ответы.
4. Ошибку, которую модель может исправить (не найдено, не хватает параметра), возвращайте как ошибку инструмента с понятным текстом, а не как сбой сервера.

Чтение и запись

Каждому инструменту задайте подсказку readOnlyHint:

• readOnlyHint: true - инструмент только читает. Trialix вызывает его без вопросов, как только модели нужны данные.
• readOnlyHint: false или подсказки нет - запись. Перед каждым вызовом сотрудник видит карточку с инструментом и значениями и нажимает «Выполнить» или «Отменить». Без его нажатия запрос к вашему серверу не уходит.

Ставьте readOnlyHint: true только тем инструментам, которые действительно ничего не меняют. Если сомневаетесь, оставьте запись: лишнее подтверждение безопаснее лишнего изменения.

Администратор компании при подключении видит список инструментов с пометками «чтение» и «запись» и отмечает, какие можно давать модели. По умолчанию отмечены только инструменты чтения. Пометку администратор может поправить вручную, но инструмент с пометкой «запись» Trialix всегда выполняет только после подтверждения сотрудника.

Публикация

Trialix обращается к серверу из интернета, поэтому:

• Только HTTPS, TLS 1.2 или новее, сертификат от публичного удостоверяющего центра (например, Let's Encrypt). Самоподписанный сертификат не подойдёт.
• Белый список IP. Разрешите входящие запросы к серверу только с адресов Trialix, адреса сообщит менеджер. Токен остаётся обязательным и при белом списке.
• Секреты (токен, пароль к БД) передавайте переменными окружения или через хранилище секретов, не в коде и не в образе.
• Токен меняйте так: выпустите новый, запустите сервер с ним и сразу обновите токен в ЛК Trialix.

Сервер слушает обычный HTTP, TLS ставит обратный прокси перед ним. Пример для Caddy (сертификат получает сам, TLS 1.2 и 1.3 по умолчанию):

mcp.example.ru {
    @trialix remote_ip 203.0.113.10 203.0.113.11
    handle @trialix {
        reverse_proxy 127.0.0.1:8000
    }
    handle {
        respond 403
    }
}

Пример для nginx:

server {
    listen 443 ssl;
    server_name mcp.example.ru;
    ssl_certificate     /etc/letsencrypt/live/mcp.example.ru/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mcp.example.ru/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;

    location /mcp {
        allow 203.0.113.10;   # адреса Trialix сообщит менеджер
        allow 203.0.113.11;
        deny all;
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        proxy_buffering off;          # нужно, если включите ответы потоком SSE
        proxy_read_timeout 60s;
        proxy_set_header X-Forwarded-For $remote_addr;
    }
}

Адреса 203.0.113.x в примерах условные. Trialix ждёт ответ на один вызов до 20 секунд: долгие операции запускайте в фоне и возвращайте номер задания, а результат отдавайте отдельным инструментом чтения.

Подключение в Trialix

Подключает владелец или администратор компании:

1. ЛК › Коннекторы › Своя система › MCP-сервер › «Подключить».
2. «Доступы»: адрес сервера вида https://mcp.example.ru/mcp и токен. Trialix отправляет его в заголовке Authorization: Bearer.
3. «Проверка»: «Получить список инструментов». Trialix вызывает initialize и tools/list и показывает инструменты с пометкой «чтение» или «запись».
4. «Что разрешаем»: отметьте инструменты, которые можно давать модели, и проверьте пометки «чтение» и «запись».
5. «Политики»: выберите, каким сотрудникам доступно подключение.

После этого сотрудники могут спрашивать в чате, например: «Найди заявки клиента Альфа» или «Создай заявку на замену картриджей для ИП Смирнов». Если вы добавили или изменили инструменты на сервере, откройте страницу подключения в ЛК и нажмите «Обновить список с сервера».

Система во внутренней сети

Если сервер нельзя открыть в интернет, поставьте Trialix Connector на машину в вашей сети и включите режим шлюза. Коннектор сам ходит в Trialix по исходящему HTTPS и передаёт запросы к вашему MCP-серверу, входящие порты не нужны.

1. Установите коннектор и включите шлюз: trialix-connector gateway enable.
2. Разрешите адрес сервера: trialix-connector gateway allow add mcp.company.local:8000.
3. В ЛК на шаге «Доступы» укажите внутренний адрес, например http://mcp.company.local:8000/mcp, и выберите коннектор в поле «Trialix Connector».

Внутри сети допустим и http://, но если трафик идёт через общие сегменты, лучше HTTPS с внутренним сертификатом (корневой сертификат указывается в gateway.caFile коннектора). Токен нужен и в этом случае.

Подробнее в разделах «Для ИТ»:

• Trialix Connector: архитектура и безопасность, шлюз
• Установка на Linux, настройка шлюза
• Установка на Windows, настройка шлюза

Если не работает

MCP-сервер как источник базы знаний

Кроме инструментов для чата MCP-сервер может отдавать документы в базу знаний Trialix (ЛК › «База знаний» › «Источники» › вид «Свой источник (MCP-сервер)»). Для этого сервер реализует два инструмента по контракту ниже; ответ - JSON-текст в первом элементе content.

Правила: version меняется при любом изменении документа (хеш, дата, номер ревизии) - Trialix скачивает только документы с новой версией и удаляет из базы те, которых нет в списке; список должен быть полным (страницы по nextCursor до пустого); name - с расширением из поддерживаемых форматов базы знаний (PDF, DOCX, XLSX, PPTX, TXT, MD, HTML, CSV), без расширения документ считается Markdown; лимит документа 25 МБ; ошибка инструмента (isError) попадает в журнал обновлений источника как ошибка по документу.