Сервер MCP Trialix

Trialix работает как сервер MCP (Model Context Protocol). Cursor, Claude Code, Claude Desktop, SDK и любой другой клиент MCP получают инструменты подключённых систем компании (CRM, склад, учёт, трекер, почта и другие), поиск по базе знаний и агентов компании. Запрос «найди сделку в Битрикс24 через Trialix» в редакторе кода проходит через подключения компании, политики доступа, лимиты, обезличивание и журнал так же, как в чате Trialix.

Доступ по MCP входит во все тарифы компаний.

Адрес и вход

• Адрес: https://api.trialix.ru/mcp. Транспорт Streamable HTTP: сообщения JSON-RPC 2.0 методом POST. Версии протокола - 2025-06-18 и 2025-03-26.
• Ответ - JSON или поток SSE: клиент перечисляет оба типа в заголовке Accept, вызовы инструментов приходят потоком, остальные ответы - JSON.
• Вход - по ключу API: заголовок Authorization: Bearer <TRIALIX_API_KEY> (или x-api-key). Подойдёт личный ключ сотрудника (портал, раздел «Мой ключ») или ключ компании (кабинет компании, «Разработчикам»). Входа через OAuth нет.
• Сессия: ответ на initialize приходит с заголовком Mcp-Session-Id, клиент передаёт его в каждом следующем запросе вместе с MCP-Protocol-Version. Запрос DELETE с этим заголовком закрывает сессию. На неизвестную или закрытую сессию сервер отвечает 404, и клиент начинает с initialize заново.
• Методы: initialize, ping, tools/list (страницами по 100, курсор nextCursor), tools/call, resources/list, resources/read, resources/templates/list. Подсказок (prompts), подписок и запросов сервера к клиенту нет; поток GET сервер не открывает, все сообщения приходят в ответах на запросы клиента.

Настройка клиентов

Вместо <TRIALIX_API_KEY> подставьте значение ключа.

Cursor

Файл ~/.cursor/mcp.json (для всех проектов) или .cursor/mcp.json в папке проекта. После сохранения сервер trialix появится в настройках MCP в Cursor. Файл проекта с ключом не добавляйте в репозиторий: для ключа удобнее файл в домашней папке.

{
  "mcpServers": {
    "trialix": {
      "url": "https://api.trialix.ru/mcp",
      "headers": { "Authorization": "Bearer <TRIALIX_API_KEY>" }
    }
  }
}

Claude Code

Команда в терминале. С флагом --scope user сервер доступен во всех проектах; список серверов и их состояние - команда /mcp в Claude Code.

claude mcp add --transport http trialix https://api.trialix.ru/mcp \
  --header "Authorization: Bearer <TRIALIX_API_KEY>"

Claude Desktop

Файл claude_desktop_config.json (Settings › Developer › Edit Config), затем перезапуск приложения. Ключ передаётся через мост mcp-remote, нужен Node.js 18 или новее.

{
  "mcpServers": {
    "trialix": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.trialix.ru/mcp", "--header", "Authorization:${TRIALIX_AUTH}"],
      "env": { "TRIALIX_AUTH": "Bearer <TRIALIX_API_KEY>" }
    }
  }
}

SDK TypeScript

Пакет @modelcontextprotocol/sdk, транспорт Streamable HTTP. Ключ - из переменной окружения TRIALIX_API_KEY.

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const transport = new StreamableHTTPClientTransport(new URL('https://api.trialix.ru/mcp'), {
  requestInit: { headers: { Authorization: `Bearer ${process.env.TRIALIX_API_KEY}` } },
});
const client = new Client({ name: 'my-app', version: '1.0.0' });
await client.connect(transport);

const { tools } = await client.listTools();
const found = await client.callTool({ name: 'search_tools', arguments: { query: 'сделки в Битрикс24' } });
console.log(found.content);

SDK Python

Пакет mcp, транспорт Streamable HTTP. Ключ - из переменной окружения TRIALIX_API_KEY.

import asyncio, os
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    headers = {"Authorization": f"Bearer {os.environ['TRIALIX_API_KEY']}"}
    async with streamablehttp_client("https://api.trialix.ru/mcp", headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            print([t.name for t in tools.tools])
            found = await session.call_tool("search_tools", {"query": "сделки в Битрикс24"})
            print(found.content[0].text)

asyncio.run(main())

Другие клиенты

Любой клиент с транспортом Streamable HTTP подключается так же: адрес сервера и заголовок Authorization. Проверить ключ без клиента можно запросом initialize: в ответе - сведения о сервере и заголовок Mcp-Session-Id.

curl -si https://api.trialix.ru/mcp \
  -H "Authorization: Bearer <TRIALIX_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

Инструменты

• Список собирается на каждый запрос: новые подключения и изменения политики видны клиенту сразу после следующего tools/list.
• У инструментов записи описание начинается с «Запись: выполняется после подтверждения сотрудником в Trialix», в annotations - readOnlyHint: false.
• Когда подключённых систем много, клиент не получает сотни схем: модель клиента сначала вызывает search_tools (несколько систем или задач можно перечислить через запятую), затем найденный инструмент.
• Инструмент, которого нет в списке ключа, отвечает ошибкой «инструмент не найден или не разрешён этому ключу»: чужое подключение не отличить от несуществующего.

Ресурсы

Документы баз знаний доступны как ресурсы MCP с адресами trialix://kb/<база>/<документ>.

• resources/list - готовые документы доступных баз, страницами по 100.
• resources/read - текст документа до 12 000 знаков; если документ длиннее, приходит начало, нужные места находит kb_search.
• Разделы базы, закрытые для отделов, видны только сотрудникам этих отделов; ключу компании - только открытые разделы. Названия и текст документов приходят обезличенными.

Запись и подтверждение

Вызов инструмента записи ничего не меняет в системе. Trialix создаёт действие с номером и возвращает клиенту текст «Действие НЕ выполнено: оно ждёт подтверждения в Trialix» с номером и ссылкой, а в structuredContent - status: "pending_confirmation", number, url и expiresAt.

• Где подтверждать. Действия по личному ключу - в портале, раздел «Ожидают подтверждения» (пункт меню появляется, когда есть ждущие действия). Действия по ключу компании - в кабинете компании, раздел «Ожидают подтверждения»: выполняет владелец или администратор. Там же видны действия сотрудников: администратор может их отменить, выполнить - только сам сотрудник.
• Срок - 24 часа, затем действие получает статус «Срок истёк», клиенту нужно повторить запрос.
• Перед выполнением права проверяются заново: ключ не отозван, политика сотрудника или доступ ключа компании, подключение, лицензия и разрешённые инструменты.
• Из клиента. Если администратор включил сотруднику функцию политики «Подтверждать из внешних клиентов» (по умолчанию выключена), у личного ключа появляется confirm_action: действие выполняется по номеру прямо из клиента.
• Агенты. Запись, которую агент делает во время ответа, тоже становится действием на подтверждение; номера и ссылки приходят в structuredContent.actions.

Личный ключ и ключ компании

• «Доступ по MCP» настраивает владелец или администратор: кабинет компании › «Разработчикам» › меню ключа › «Доступ по MCP». Ключ компании работает без сотрудника, поэтому ничего сверх отмеченного ему не доступно. Инструменты, которые система разрешает только от имени сотрудника, по ключу компании отвечают отказом.
• Ключ с правами «Только чат» к серверу MCP не подключается.
• У сотрудника без лицензии Trialix ключ не работает: клиент получает «Вам не назначена лицензия Trialix, поэтому ключ не работает. Обратитесь к администратору компании».
• На пилоте ключей компании нет, работают личные ключи сотрудников.
• В кабинете «Модели» работает личный ключ: личные подключения и агенты, без базы знаний компании.

Данные

• Ответы систем, базы знаний и агентов обезличиваются так же, как перед зарубежной моделью в чате: ФИО, организации, реквизиты, телефоны, почта и адреса приходят метками вида [ФИО_1], [ОРГ_2]. Метки в аргументах следующих вызовов Trialix заменяет исходными значениями перед обращением к системе. Каждое обезличивание записывается в журнал «Безопасности» компании без самих значений. Если сервис обезличивания недоступен, данные не отдаются.
• Доступы подключений наружу не уходят: токены, пароли и ключи в ответе системы заменяются на «[скрыто]».
• Ответ инструмента - до 12 000 знаков.
• Журнал хранит инструмент, статус и время вызова, без значений аргументов и без ответа.

Журнал, лимиты, отзыв ключа

• Кабинет компании › «Журнал»: подключение клиента, вызовы инструментов, отказы, действия на подтверждение и решения по ним.
• Кабинет компании › «Коннекторы» › подключение › «Использование за 30 дней»: вызовы внешних клиентов отдельной строкой с пометкой «внешний клиент».
• Лимиты запросов в минуту действуют отдельно по ключу и по компании и не расходуют лимит API тарифа; лимит запросов, заданный у ключа компании, тоже действует. Лимиты систем (запросов в минуту к подключению, дневные лимиты политики) - те же, что в чате. При превышении сервер отвечает 429 с заголовком Retry-After.
• После 20 отказов подряд по одному ключу владелец и администраторы получают письмо «Много отказов по ключу API» (не чаще раза в сутки на ключ).
• «Отозвать» ключ в «Разработчикам» сразу закрывает все сессии клиентов по этому ключу.

Расход

• Доступ по MCP входит во все тарифы компаний, отдельной цены за вызов нет. Обращения к системам - действия подключений, как в чате: места подключений считаются как обычно.
• TRX списываются только за работу моделей: ответы агентов (модель агента в пределах политики и ключа, как в чате) и поиск по базе знаний (эмбеддинг запроса и переранжирование по прайсу). Цена вызова - в _meta ответа (trialix/priceKopecks, сотые доли TRX), расход - в «Биллинге» компании по ключу.

Ошибки

Отказ внутри инструмента (не хватает средств, система не ответила, обезличивание недоступно) приходит обычным результатом tools/call с isError: true и текстом для модели клиента.