For the complete documentation index, see llms.txt. This page is also available as Markdown.

MCP de vERP

MCP de Velneo vERP

¿Qué es el MCP de Velneo vERP?

Todas las aplicaciones programadas con la plataforma de desarrollo Velneo, simplemente heredando vERP y sin necesidad de programar, pueden exponer un servidor MCP (Model Context Protocol).

MCP es un estándar abierto, independiente de cada fabricante de inteligencia artificial, que permite a un asistente o agente de IA (Claude, ChatGPT, Gemini, etc.) descubrir de forma automática qué datos y qué acciones puede consultar o ejecutar sobre una aplicación, sin que el programador tenga que integrar esa aplicación "a medida" contra cada proveedor de IA.

El MCP de Velneo vERP no sustituye a la API REST: son dos mecanismos complementarios que comparten la definición del API y su configuración de seguridad.

Esta es la primera versión del servicio MCP de Velneo vERP. Su comportamiento, endpoints y capacidades pueden ampliarse o ajustarse en próximas versiones de la plantilla.

API REST y MCP: dos formas de exponer vERP

Aunque ambos mecanismos permiten a un tercero consumir datos y funcionalidades de vERP, están pensados para escenarios distintos:

API REST
MCP

Pensado para

Que una aplicación externa (o una persona programadora) se integre con vERP de forma sistemática y predecible

Que un agente de IA descubra y use por sí mismo las capacidades de vERP

Quién decide qué se ejecuta

El programador, en tiempo de diseño

El modelo de IA, en tiempo de conversación

Forma de acceso

Múltiples endpoints REST (uno por tabla, proceso o búsqueda)

Un único endpoint (/MCP) que atiende todas las peticiones del protocolo MCP según el contenido (body) de la peticiónn número reducido de endpoints estándar del protocolo MCP (p. ej. listar herramientas y ejecutarlas)

Documentación que consume

Swagger / OpenAPI

La propia definición del API más las Notas de los métodos

En muchos casos, un servidor MCP acaba invocando por debajo una API REST. En Velneo vERP, el servicio MCP no es una excepción: se apoya en la misma infraestructura de seguridad y configuración del API (ver siguiente apartado).

Habilitar el servicio MCP

1. Crear el API de tipo "Bearer por usuario"

Desde la opción API keys del menú Supervisor, crea un nuevo registro de API e indica como tipo de autentificación Bearer por usuario.

2. Autorizar el API a los grupos de usuario

En la configuración del API, habilítalo para los grupos de usuario que deban poder usar el MCP (por ejemplo, el grupo de administradores).

3. Autorizar el API al usuario y obtener el token

En la ficha del usuario que va a consumir el MCP, localiza el API en el listado de APIs no autorizadas y arrástralo a APIs autorizadas.

A continuación, haz doble clic sobre el API en la lista de APIs autorizadas y pulsa Actualizar token: vERP genera el token Bearer de ese usuario para ese API. Cópialo: es el que tendrás que facilitar al cliente o agente de IA.

Una vez autorizado, vERP genera automáticamente el token Bearer de ese usuario para ese API. Cópialo: es el que tendrás que facilitar al cliente o agente de IA.

El token Bearer identifica a un usuario concreto de la aplicación. Trátalo con la misma precaución que una contraseña: cualquier acción que ejecute la IA a través del MCP se realizará con los permisos de ese usuario.

4. Dar contexto adicional con Notas de los métodos

En la definición del API se ha añadido una nueva pestaña, Notas de los métodos, pensada específicamente para el MCP (no se usa en la documentación Swagger/OpenAPI del API REST).

Aquí puedes añadir, para cada tabla, campo, proceso o búsqueda habilitados en el API, una descripción libre en lenguaje natural. Esa información se envía al agente de IA junto con el resto de metadatos (campos, índices disponibles, etc.) y le sirve para entender mejor qué hace cada recurso y cuándo debe usarlo, más allá de lo que ya se deduce del nombre técnico del campo o del proceso.

Es especialmente útil para aclarar aquello que no queda claro solo con el modelo de datos: por ejemplo, distinguir el parámetro filter (filtrado de listas) del parámetro index (búsqueda por índice), una confusión habitual también entre las propias IAs.

Endpoints del servidor MCP

El servicio expone un único endpoint, /MCP, que es un proceso accesible web. Todo el funcionamiento del protocolo MCP pasa por él: según el contenido (body) de la petición, atiende la consulta de las herramientas (tools) disponibles para ese usuario/API (tablas, procesos y búsquedas habilitados, con sus campos, índices y las notas descritas en el punto anterior) o su ejecución.

Este endpoint se consume únicamente mediante POST (una petición GET no es válida) y requiere la cabecera de autenticación Authorization: Bearer <token>, con el token del usuario autorizado.

No es necesario invocar este endpoint manualmente: un cliente o agente de IA compatible con MCP lo descubre y lo usa siguiendo el estándar en cuanto le proporcionas la URL del servicio y el token.

Consumir el MCP desde un cliente de IA

Para que un asistente de IA (por ejemplo Claude) use el MCP de tu vERP, basta con indicarle:

  1. Solicita al servicio MCP la lista de herramientas para saber qué tablas, procesos y búsquedas tiene disponibles, con sus campos, índices y notas de método.

  2. El token Bearer del usuario autorizado.

A partir de ahí, el propio cliente de IA:

  1. Consulta el endpoint de listado de herramientas para saber qué tablas, procesos y búsquedas tiene disponibles, con sus campos, índices y notas de método.

  2. En función de la conversación con la persona usuaria, decide qué herramienta ejecutar (por ejemplo, dar de alta un artículo, consultar el stock de una referencia o modificar un cliente) y la invoca contra el servicio MCP.

Con esto, es posible mantener una conversación en lenguaje natural del tipo "dame de alta este artículo", "modifica el precio de venta de la referencia X" o "elimina este cliente", sin que el agente de IA tenga que conocer de antemano la estructura del API REST.

Como el MCP puede ejecutar altas, modificaciones y bajas de registros, autoriza el API MCP únicamente a los usuarios y grupos que deban tener esa capacidad, y revisa qué tablas, procesos y campos quedan expuestos en su configuración de seguridad.

Última actualización

¿Te fue útil?