Integración de complementos y servidores MCP
Cómo conectar a Keural un servidor MCP propio y crear un paquete de complemento para la aplicación de escritorio.
Los complementos de Keural son servidores MCP (Model Context Protocol). Esta página es la especificación para conectar su propio servidor MCP a Keural o crear un paquete de complemento para instalarlo en la aplicación de escritorio.
Métodos de transporte
| Plataforma | Transporte disponible | Uso |
|---|---|---|
| Web y móvil | HTTP (Streamable HTTP) · SSE | Servidores MCP remotos accesibles desde Internet |
| Aplicación de escritorio | STDIO · HTTP | Servidores que se ejecutan en este equipo, servidores HTTP de la red interna |
- En las conversaciones web solo se usan servidores HTTP o SSE remotos. Los servidores STDIO se ejecutan en la aplicación de escritorio.
- Si la dirección del servidor termina en
/mcp, suele ser un servidor Streamable HTTP, así que seleccione HTTP como método de transporte. - El HTTP de la aplicación de escritorio es para direcciones de la red interna. Las direcciones públicas de Internet se registran con HTTP en la web.
Campos para añadir un MCP personalizado
En Configuración → Complementos → ＋ Añadir MCP personalizado los campos son los siguientes.
| Campo | Contenido |
|---|---|
| Nombre | Obligatorio |
| Descripción | Opcional |
| Método de transporte | Consulte la tabla anterior |
| Categoría | Clasificación en la lista |
| URL del servidor | Obligatoria para HTTP o SSE. Ejemplo: https://example.com/mcp |
| Comando de ejecución | Obligatorio para STDIO. Ejemplo: npx |
| Argumentos | Argumentos de STDIO (matriz JSON). Ejemplo: ["-y", "@scope/server"] |
| Usar este complemento para la búsqueda web | Si lo activa, la búsqueda web usa este complemento en lugar de la búsqueda predeterminada. |
| Autenticación | Ninguna · Clave de API |
| Nombre del encabezado · Valor de la clave de API | Cuando es Clave de API. Ejemplo: nombre del encabezado Authorization, valor Bearer … |
Si elige una clave de API, Keural añade el encabezado <nombre del encabezado>: <valor> a cada solicitud.
Servidores con OAuth
Los complementos que un administrador de la organización registra con OAuth requieren que el usuario pulse Conectar e inicie sesión.
| Elemento | Valor |
|---|---|
| Detección del servidor | /.well-known/oauth-protected-resource (con la ruta; después, la raíz), y luego /.well-known/oauth-authorization-server |
| Registro del cliente | Registro dinámico de cliente (DCR) |
| URI de redirección | https://api.keural.ai/api/user-connectors/oauth/callback |
| Encabezado de solicitud | Authorization: Bearer <token de acceso> |
La ventana de inicio de sesión se abre como una ventana emergente y, cuando termina, la lista de complementos se actualiza.
Permisos de herramientas
Defina cómo se ejecuta cada herramienta del complemento.
| Permiso | Comportamiento |
|---|---|
| Permitir siempre | Se ejecuta sin confirmación. |
| Requiere aprobación | Muestra una tarjeta de aprobación antes de ejecutar. La tarjeta también muestra los argumentos de la herramienta. |
| Bloqueado | El agente no usa esta herramienta. |
Paquete de complemento para el escritorio
La aplicación de escritorio instala complementos mediante Archivo ZIP del complemento… o Carpeta del complemento…. El paquete necesita el manifiesto plugin.json.
{
"id": "my-plugin",
"name": "My Plugin",
"version": "1.0.0",
"description": "Consulta del sistema interno",
"mcpServers": {
"my-server": {
"command": "node",
"args": ["server.js"],
"env": { "API_BASE": "https://intranet.example.com" }
}
}
}| Campo | Obligatorio | Contenido |
|---|---|---|
id | Sí | Letras minúsculas inglesas, números y guiones |
name | No | Nombre para mostrar. Si no existe, se usa id. |
version | No | Predeterminado 1.0.0 |
description | No | Descripción |
minAppVersion | No | Versión mínima de la aplicación necesaria |
mcpServers | No | Definiciones de servidores MCP. Para cada servidor, command, args y env. |
requests | No | Permisos solicitados (capabilities, commands, connectors, secrets, permissions). Matriz de cadenas. |
Un complemento STDIO registrado en la web se instala en la aplicación de escritorio con Instalar en este PC. Después de la instalación, introduzca manualmente el token de autenticación y las variables de entorno.