> 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-verp/mcp-de-verp.md).

# 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)**.

{% hint style="info" %}
A partir de la versión 38, Velneo vServer incluye además su propio servidor MCP, que expone herramientas genéricas de datos, administración y desarrollo sin necesidad de heredar vERP. Esta documentación se mantiene para aquellos que siguan usando este servicio de vERP.
{% endhint %}

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](/38/velneo-verp/documentacion-del-apirest.md): son dos mecanismos complementarios que comparten la definición del API y su configuración de seguridad.

{% hint style="info" %}
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.
{% endhint %}

## 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](https://claude.ai/epitaxy/local_da672465-93e9-4c61-8e56-04bce217055a#h.mcp-notas-metodos)                                                                        |

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](https://doc.velneo.com/38/velneo-verp/pages/-M7D76uON0uuWLwinYCF#h.75wthxkvhxe).

<figure><img src="https://1985084359-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSSuDG1WIgF9xPUK4NaFS%2Fuploads%2FH3i6ciT8LcnpocIeGLav%2Fimage.png?alt=media&amp;token=29ebe838-75b4-414c-bb34-a9a74b0f6a86" alt=""><figcaption></figcaption></figure>

### 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).

<figure><img src="https://1985084359-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSSuDG1WIgF9xPUK4NaFS%2Fuploads%2FHL7q9c5oSGMQ01YuhyTP%2Fimage.png?alt=media&amp;token=e16fd712-bbfa-4832-8dac-afa6a4f76c35" alt=""><figcaption></figcaption></figure>

### 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.

<figure><img src="https://1985084359-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSSuDG1WIgF9xPUK4NaFS%2Fuploads%2FOsIjXfBM5DqWMULyubbO%2Fimage.png?alt=media&amp;token=1e35e1b7-1d0c-4c9c-95d1-6ab995e151a9" alt=""><figcaption></figcaption></figure>

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.

{% hint style="info" %}
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.
{% endhint %}

### 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.

{% hint style="info" %}
&#x20;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.
{% endhint %}