Интеграция плагинов и сервера MCP
Как подключить собственный сервер MCP к Keural и создать пакет плагина для настольного приложения.
Плагины Keural представляют собой серверы MCP (Model Context Protocol). Спецификация предназначена для разработчиков, которые подключают собственный сервер MCP к Keural или создают пакет плагина для установки в настольном приложении.
Способы передачи данных
| Платформа | Способ передачи | Назначение |
|---|---|---|
| Веб и мобильные устройства | HTTP (Streamable HTTP) · SSE | Удалённые серверы MCP, доступные из интернета |
| Настольное приложение | STDIO · HTTP | Серверы, работающие на этом компьютере, и HTTP-серверы во внутренней сети |
- В диалогах веб-версии используются только удалённые серверы HTTP и SSE. Серверы STDIO работают в настольном приложении.
- Если адрес сервера заканчивается на
/mcp, обычно это сервер Streamable HTTP, и способ передачи выбирается HTTP. - HTTP в настольном приложении предназначен для адресов внутренней сети. Публичные адреса из интернета регистрируются через HTTP в веб-версии.
Значения для ручного добавления
Поля, которые появляются после нажатия ＋ Добавить пользовательский MCP в разделе Настройки → Плагины:
| Поле | Содержание |
|---|---|
| Название | Обязательно |
| Описание | Необязательно |
| Способ передачи | См. таблицу выше |
| Категория | Классификация в списке |
| URL сервера | Обязательно для HTTP или SSE. Пример: https://example.com/mcp |
| Команда запуска | Обязательно для STDIO. Пример: npx |
| Аргументы | Аргументы STDIO (массив JSON). Пример: ["-y", "@scope/server"] |
| Использовать этот плагин для поиска в интернете | Если включено, вместо поиска в интернете используется этот плагин. |
| Аутентификация | Нет · ключ API |
| Имя заголовка · значение ключа API | Для ключа API. Пример: заголовок Authorization, значение Bearer … |
Если выбран ключ API, к каждому запросу добавляется заголовок <имя заголовка>: <значение>.
Серверы аутентификации OAuth
Плагин, который администратор организации зарегистрировал с OAuth, подключается, когда пользователь нажимает Подключить и входит в систему.
| Параметр | Значение |
|---|---|
| Поиск сервера | /.well-known/oauth-protected-resource (с путём → корень), затем /.well-known/oauth-authorization-server |
| Регистрация клиента | Динамическая регистрация клиента (DCR) |
| URI перенаправления | https://api.keural.ai/api/user-connectors/oauth/callback |
| Заголовок запроса | Authorization: Bearer <access token> |
Окно входа открывается во всплывающем окне, после входа список плагинов обновляется.
Разрешения инструментов
Задайте, как запускается каждый инструмент плагина.
| Разрешение | Поведение |
|---|---|
| Всегда разрешать | Запускается без подтверждения. |
| Спрашивать сначала | Перед запуском показывается карточка одобрения, в которой также отображаются аргументы инструмента. |
| Заблокировать | Агент не использует этот инструмент. |
Пакет плагина для настольного приложения
Настольное приложение устанавливает плагины через ZIP-файл плагина… или Папка плагина…. Пакет должен содержать манифест plugin.json.
{
"id": "my-plugin",
"name": "My Plugin",
"version": "1.0.0",
"description": "Запрос к внутренним системам",
"mcpServers": {
"my-server": {
"command": "node",
"args": ["server.js"],
"env": { "API_BASE": "https://intranet.example.com" }
}
}
}| Поле | Обязательно | Содержание |
|---|---|---|
id | Да | Строчные латинские буквы, цифры и дефисы |
name | Нет | Отображаемое название. Если не указано, используется id. |
version | Нет | По умолчанию 1.0.0 |
description | Нет | Описание |
minAppVersion | Нет | Минимальная необходимая версия приложения |
mcpServers | Нет | Определения серверов MCP. Для каждого сервера указываются command, args, env. |
requests | Нет | Запрашиваемые разрешения (capabilities, commands, connectors, secrets, permissions). Массив строк |
Плагин STDIO, зарегистрированный в веб-версии, устанавливается в настольном приложении кнопкой Установить на этот ПК. После установки токен аутентификации и переменные окружения вводятся вручную.