MCP-серверы: инструменты для агентов

Model Context Protocol (MCP) является открытым стандартом обмена контекстом и инструментами между языковыми моделями и внешними системами. Сервер публикует набор инструментов с описанием и схемой аргументов, клиент вызывает их по JSON-RPC. В Semantix MCP используется в обе стороны: платформа подключает серверы как источник инструментов для агентов, а сама может работать как сервер для внешних клиентов.

Реестр MCP-серверов организации

Серверы инструментов регистрируются в пределах организации. В «Настройках пользователя» откройте раздел серверов инструментов и нажмите «Добавить»:

1. Укажите уникальное имя, тип соединения (SSE либо streamable HTTP; stdio не поддерживается), полный адрес и при необходимости токен авторизации. Токен передаётся заголовком, а не в адресе.
2. Нажмите «Проверить». Платформа получит перечень инструментов с описаниями.
3. Просмотрите инструменты и выключите те, которые не одобрены владельцем системы, в первую очередь изменяющие.
4. Сохраните. Перечень инструментов и признак включения кэшируются; после изменений на сервере обновите перечень из карточки.

Доступны импорт и экспорт набора серверов и тестовый вызов инструмента с аргументами прямо из интерфейса. Создание и изменение сервера отражаются в журнале действий.

Где инструменты используются

• Агент на холсте. В компоненте «Агент» выбираются инструменты из подключённых серверов. Метаданные инструмента преобразуются к формату вызова функций модели; выполнение идёт в ReAct-цикле: анализ запроса, вызов инструмента, добавление результата в контекст, продолжение. Имя инструмента, аргументы, результат и время выполнения записываются в трассировку.
• Ассистент в чате. Явно выбранные инструменты MCP дополняют каталог инструментов нового ядра чата. Организация, пользователь, сессия и узел привязываются сервером, текст сообщения не может подменить эту привязку. Каждый вызов инструмента проверяется на доступность при каждом обращении, поэтому выключенный инструмент перестаёт работать сразу.
• Research-режим. Задачи исследования читают из реестра инструментов чтения: 1С, Bitrix24 и внешние источники через модули шлюза. Инструменты записи задачам исследования не выдаются.
• Автоматизации. Триггер опроса вызывает инструмент по расписанию, снимает отпечаток ответа и запускает сценарий только при изменении.

Запись во внешнюю систему всегда проходит через подтверждение: чат останавливает ход перед изменяющим вызовом и показывает карточку подтверждения, холст паркует выполнение на узле одобрения, в Telegram приходят кнопки «Подтвердить» и «Отклонить».

Встроенный шлюз и внешние серверы

Semantix поставляется со своим шлюзом инструментов, в котором интеграции реализованы модулями: 1С, Bitrix24, Jira и Confluence, Telegram, законодательные базы, рекламные кабинеты и другие. У модулей шлюза есть то, чего нет у произвольного внешнего сервера:

Внешний сервер подходит для готовых интеграций, которые уже есть у вендоров (Atlassian, GitHub, HubSpot, Salesforce и другие), и для быстрых прототипов. Если интеграция становится постоянной, её переносят в модуль шлюза, чтобы получить аудит и запечатанные секреты.

Встроенный MCP-сервер платформы

Semantix может сам выступать MCP-сервером и отдавать инструмент поиска по базам знаний внешним клиентам (IDE, агентам, другим платформам). Сервер запускается отдельным процессом рядом с серверной частью.

Из исходников:

uv run mcp/server/server.py --host=127.0.0.1 --port=9382 \
  --base-url=http://127.0.0.1:9380 --api-key=<api-key>

В Docker Compose включается через command службы сервера: --enable-mcpserver, --mcp-host, --mcp-port, --mcp-base-url, --mcp-mode, --mcp-host-api-key. Два режима:

• self-host (по умолчанию): API-ключ задаётся при запуске, сервер видит базы знаний одной организации;
• host: каждый клиент передаёт свой API-ключ в заголовках (api_key либо Authorization) и видит свои базы.

Транспорты: /sse (устаревший SSE) и /mcp (streamable HTTP). Сервер публикует инструмент ragflow_retrieval с аргументами question, dataset_ids и необязательным document_ids; описания всех доступных баз с идентификаторами включены в описание инструмента, поэтому клиент может передать все базы, если не знает, какая релевантна.

Пример клиента на Python в режиме host:

from mcp.client.sse import sse_client

async with sse_client("http://localhost:9382/sse", headers={"api_key": "<api-key>"}) as streams:
    ...

Как добавить свой инструмент

Самый быстрый путь для прототипа: поднять собственный сервер на любой библиотеке MCP (например, FastMCP, в том числе с генерацией из OpenAPI), опубликовать его по streamable HTTP, проверить инспектором MCP и зарегистрировать в реестре организации. После этого инструменты доступны в компоненте «Агент» и у ассистентов. Для промышленного использования опишите, какие инструменты читают, а какие изменяют данные: от этого зависит, потребует ли платформа подтверждения.

Смежные статьи: Агенты на холсте, API-ключ и SDK, Подключение 1С через OData.