> For the complete documentation index, see [llms.txt](https://doc.velneo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.velneo.com/38/velneo-vserver/servidor-mcp.md). # Servidor mcp ## Servidor MCP [Velneo vServer](/38/velneo-vserver/que-es-velneo-vserver.md) incorpora un **servidor MCP** (*Model Context Protocol*) que permite conectar asistentes y agentes de inteligencia artificial (Claude, ChatGPT, Gemini, Cursor, etc.) directamente con el servidor, sin necesidad de programar nada en la aplicación. MCP es un estándar abierto, independiente de cada fabricante de inteligencia artificial, que permite a un agente descubrir de forma automática qué herramientas tiene disponibles y ejecutarlas. A través del servidor MCP de Velneo vServer, un agente de IA puede: * Consultar y modificar los **datos** de las tablas de una instancia. * Con los permisos adecuados, **administrar** el servidor (usuarios, grupos, instancias, soluciones, tareas, logs, servicio HTTPS…) y **editar proyectos** de forma similar a [Velneo vDevelop](/38/velneo-vdevelop/introduccion.md). {% hint style="info" %} No hay que confundir este servidor MCP, que forma parte de la plataforma y expone un conjunto fijo de herramientas genéricas, con el [MCP de Velneo vERP](/38/velneo-verp/mcp-de-verp.md), que expone las funcionalidades definidas en la API de las aplicaciones que heredan de vERP. {% endhint %} ## Características * **Transporte**: *Streamable HTTP* (JSON-RPC 2.0 sobre HTTPS). * **Versión del protocolo**: 2025-06-18. Se aceptan también 2025-03-26 y 2024-11-05. * **Métodos**: `initialize`, `tools/list` y `tools/call`. * **Capacidades**: herramientas (*tools*). No se ofrecen *resources* ni *prompts*. * **Autenticación**: cabecera `Authorization: Bearer`, con API Key, token OAuth de un proveedor externo o token de sesión de Velneo vServer. ## Habilitar el servidor MCP El servidor MCP no tiene una URL fija: se publica creando una **ruta de tipo MCP** en un *virtual host* del [servicio HTTPS](/38/velneo-vserver/servicio-https.md) de Velneo vServer. ### Crear la ruta Desde [Velneo vAdmin](/38/velneo-vadmin/que-es-velneo-vadmin.md), en la opción [Web](/38/velneo-vadmin/web.md), editaremos el *virtual host* y añadiremos una nueva ruta con los siguientes datos: * **Ruta**: path en el que responderá el servidor MCP, por ejemplo `/mcp`. No puede ser la raíz (`/`). * **Tipo**: **MCP**. * **Usuario**: usuario de Velneo vServer con el que se ejecutan las herramientas cuando se accede con un perfil de seguridad (API Key, OAuth externo, IP o sin autenticación). * **Instancia** (opcional): si se indica, esa instancia queda expuesta y las herramientas de datos trabajarán con ella por defecto, sin que el agente tenga que indicarla. La ruta responde en su path, sin sufijos. Si queremos servir otra cosa, por ejemplo una [API REST](/38/velneo-vserver/api-rest-en-vserver.md), hay que crear otra ruta. #### Configurar la seguridad {% hint style="danger" %} Una ruta MCP sin ningún método de seguridad **no se sirve** (responde con un error 503). En la configuración de la ruta se mostrará el aviso *"Seguridad: NO ACTIVA"*. {% endhint %} La seguridad se configura mediante [perfiles de seguridad](/38/velneo-vadmin/web.md#perfiles-de-seguridad). Cada perfil puede combinar varios métodos de autenticación; basta con que se cumpla uno de ellos: * **API Keys**: hasta dos por perfil, con etiqueta y fecha de caducidad opcional. El agente envía la API Key como token Bearer (`Authorization: Bearer `). * **OAuth externo**: valida tokens emitidos por un proveedor de identidad externo, por introspección (RFC 7662) o con JWKS. * **IPs permitidas**: lista de direcciones IP desde las que se permite el acceso. * **Sin autenticación**: la ruta se sirve sin credencial. Úsalo únicamente combinado con una restricción de IP o en entornos controlados. Las peticiones autenticadas mediante un perfil se ejecutan con el **usuario** de la ruta. En la pestaña **Permisos** del perfil se elige **Acceso completo** o **Acceso restringido** (tablas, campos, verbos, tablas estáticas, procesos y búsquedas permitidos). Ver [herramientas disponibles](#herramientas-disponibles). En la pestaña **Seguridad** de cada perfil se configuran el límite de peticiones por minuto (al superarlo se responde con 429), CORS, el tamaño máximo del cuerpo (10 MiB por defecto; al superarlo se responde con 413), el tiempo máximo de ejecución de una petición (al superarlo se responde con 504) y el nivel de log. Además, en la propia ruta: * **IPs permitidas**: restricción de IP para toda la ruta, aplicable a todos los perfiles. * **Reservar licencia por sesión** (activada por defecto): cada sesión de la ruta ocupa una licencia de ejecución mientras está activa. Si no hay licencias libres, se responde con 503 (*"No hay licencias de ejecución libres. Inténtelo de nuevo más tarde."*) y la cabecera `Retry-After`. Desmárcala para no consumir licencias. ### Reiniciar el servicio HTTPS Tras crear o modificar la ruta hay que guardar la configuración y reiniciar el servicio HTTPS de Velneo vServer para que se apliquen los cambios. ## URL del servidor MCP `https://dominio_del_servidor[:puerto]/ruta/` Por ejemplo, si la ruta es `/mcp`: `https://miservidor.miempresa.com/mcp/` {% hint style="warning" %} Indica siempre la URL **con la barra final**. Una petición a la ruta sin la barra final recibe una redirección (302) que muchos clientes no siguen correctamente en peticiones POST. {% endhint %} En [Velneo Cloud](/38/velneo-cloud/que-es-velneo-cloud.md), el dominio y el puerto serán los del [servicio HTTPS](/38/velneo-vserver/servicio-https.md#servicio-https-en-velneo-cloud) indicados en el [panel de control](/38/velneo-cloud/panel-de-control-vserver-cloud.md). ## Herramientas disponibles Las herramientas son un catálogo fijo incluido en Velneo vServer, compartido con la API REST. No se definen desde los objetos de la solución. Cada herramienta incluye su descripción y el esquema de sus parámetros, que el agente descubre automáticamente con `tools/list`. Las herramientas que puede ver y usar el agente dependen de cómo se autentique: * **Perfil de seguridad con acceso restringido**: herramientas de datos, limitadas a los permisos del perfil. * **Perfil de seguridad con acceso completo**: catálogo completo, según los privilegios del usuario de la ruta. * **Token de sesión de un usuario no administrador** (ruta ruta con perfil **Sin autenticación**): herramientas de datos. * **Token de sesión de un usuario administrador** (ruta con perfil **Sin autenticación**): catálogo completo (datos, administración y desarrollo). Las herramientas de administración del servidor solo están disponibles si el servidor dispone de la [API REST de administración](/38/velneo-vserver/api-rest-en-vserver.md#administracion) (Velneo Cloud o licencia de suscripción). ### Herramientas de datos * `listTables`: lista las tablas de la instancia. * `getTableSchema`: estructura (campos e índices) de una tabla. * `listStaticTables`, `listStaticTableItems`, `getStaticTableItem`: consulta de tablas estáticas. * `listRecords`: lista y cuenta registros, con paginación (máximo 500 por página, 50 por defecto), filtros por campo, ordenación y selección de campos. Filtros disponibles: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `between`, `contains`, `notContains`, `empty` y `notEmpty`. * `getRecord`: lee un registro. * `getObjectField`: lee el contenido de un campo de tipo objeto. * `addRecord`, `addRecordsBulk`: alta de uno o varios registros. * `setRecord`, `modRecord`: modificación de un registro. * `delRecord`: baja de un registro. La instancia que se quiera consultar debe estar expuesta en alguna ruta del *virtual host* y el usuario debe tener permiso sobre ella. ### Herramientas de administración y desarrollo * **Administración del servidor**: usuarios, grupos y permisos, soluciones, instancias (crear, eliminar, detener, reanudar, reiniciar, exponer), conexiones, transacciones, tareas, colas, carpetas y disco, licencia, logs y mensajes del sistema, servicio HTTPS y métricas. * **Desarrollo**: crear soluciones y proyectos, añadir, modificar y eliminar objetos, buscar y reemplazar propiedades, generar objetos a partir de otros (formularios, rejillas…), consultar dónde se usa un objeto, herencia de proyectos, banco de ficheros, navegación y tema de la aplicación, validar scripts de procesos, etc. * **Ayuda para el agente**: guías de uso, referencia del motor de Velneo y consulta de la documentación oficial de Velneo. {% hint style="info" %} Cada herramienta indica si es de solo lectura o destructiva (anotaciones `readOnlyHint` y `destructiveHint`), para que el cliente de IA pueda pedir confirmación antes de ejecutarla. Si el agente invoca una herramienta que no existe, el error sugiere las de nombre parecido. {% endhint %} {% hint style="info" %} Para el servidor MCP, los ficheros que en Velneo vDevelop vemos en el [inspector de scripts](/38/velneo-vdevelop/inspectores.md#inspector-de-scripts) (JavaScript, QML, imágenes, etc.) forman el **banco de ficheros del proyecto**. Al pedirle al agente que cree o modifique uno de estos ficheros, conviene referirse a él como el "banco del proyecto", el "banco de scripts" o el "banco de QML". Si le pedimos, por ejemplo, «crea un JavaScript en la carpeta scripts», buscará en el proyecto un objeto o carpeta llamado «scripts» y no conseguirá crearlo. {% endhint %} ## Configurar el cliente de IA Todos los clientes necesitan la **URL** del servidor MCP y la cabecera `Authorization: Bearer `. ### Claude Code ```bash claude mcp add --transport http velneo https://miservidor.miempresa.com/mcp/ --header "Authorization: Bearer " ``` Podemos comprobar la conexión con `claude mcp list`. ### Clientes que solo admiten servidores locales En clientes como Claude Desktop se puede usar el puente [mcp-remote](https://www.npmjs.com/package/mcp-remote), que requiere Node.js. Ejemplo para `claude_desktop_config.json`: ```json { "mcpServers": { "velneo": { "command": "npx", "args": ["mcp-remote", "https://miservidor.miempresa.com/mcp/", "--header", "Authorization: Bearer ${VELNEO_TOKEN}"], "env": { "VELNEO_TOKEN": "" } } } } ``` ### Token de sesión de Velneo vServer Si la ruta tiene un perfil de seguridad **Sin autenticación**, se puede usar un token de sesión de un usuario de Velneo vServer. El token se obtiene con el [login](/38/velneo-vserver/api-rest-en-vserver/api-rest-de-administracion.md#con-usuario-y-contrasena) de la API REST de administración (`POST …/login` con usuario y contraseña), no desde el propio MCP. El token caduca tras una hora sin uso, por lo que para un uso continuado se recomienda una API Key. ## Ejemplos de peticiones Prueba de conexión con `curl`: ```bash curl -i -X POST https://miservidor.miempresa.com/mcp/ \ -H "Authorization: Bearer " \ -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"}}}' ``` La respuesta incluye la cabecera `Mcp-Session-Id`. Listar herramientas (admite `cursor` y `limit` para paginar, y `filter` para filtrar por nombre): ```json {"jsonrpc":"2.0","id":2,"method":"tools/list","params":{"filter":"record","limit":50}} ``` Ejecutar una herramienta: ```json {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"listRecords","arguments":{"table":"CLIENTES","limit":10}}} ``` Si la ejecución falla, se devuelve un error JSON-RPC con el código HTTP equivalente en `data.httpStatus`: ```json {"jsonrpc":"2.0","id":3,"error":{"code":-32602,"message":"...","data":{"httpStatus":404}}} ``` ## Detalles del protocolo * Solo se admiten peticiones **POST**. Las peticiones GET o DELETE responden con 405. * Si la cabecera `Accept` incluye `text/event-stream`, la respuesta se devuelve como un único evento SSE. * La cabecera `Mcp-Session-Id` se genera en `initialize` y se devuelve en todas las respuestas. * Si se envía la cabecera `MCP-Protocol-Version` con una versión no soportada, se responde con 400. * Si se envía la cabecera `Origin`, solo se acepta si es de la propia máquina (`localhost`, `127.0.0.1` o `::1`), del mismo host del servidor o de un origen autorizado expresamente en los **Orígenes CORS** del perfil de seguridad de la ruta; en otro caso se responde con 403 (protección frente a *DNS rebinding*). Las peticiones sin `Origin`, como las de los clientes que no son navegadores, no se rechazan por este control. * Se rechazan las peticiones con la cabecera `Authorization` duplicada. * Se procesa un único mensaje JSON-RPC por petición (no se admiten lotes). ## Códigos de error * **HTTP 503**: ruta sin método de seguridad, o sin licencias de ejecución libres (con `Retry-After`). * **HTTP 403**: IP u `Origin` no permitidos. * **HTTP 401**: falta la cabecera `Authorization`, o el token o la API Key no son válidos o han caducado. * **HTTP 405**: método HTTP distinto de POST. * **HTTP 429**: límite de peticiones superado. * **HTTP 413**: petición demasiado grande. * **HTTP 400**: versión de protocolo no soportada. * **JSON-RPC -32700**: JSON no válido. * **JSON-RPC -32601**: método o herramienta inexistente. * **JSON-RPC -32602**: la herramienta requiere autenticación o privilegios de administrador, instancia no autorizada o argumentos no válidos. * **JSON-RPC -32603**: error interno de la herramienta. ## Log de accesos Las peticiones al servidor MCP se registran en un log propio, que podemos consultar en Velneo vAdmin, en la opción Web, seleccionando **MCP** en el desplegable **Log**. En este mismo log se registran también las peticiones a las rutas de tipo **Health** y **Metrics**. Los accesos denegados (401, 403, 429, 503) quedan registrados, además, en el [log general del servicio HTTPS](/38/velneo-vadmin/web.md#log), según el nivel de log configurado en la ruta o en el perfil de seguridad.