Servidor MCP de integraciones

Además del Servidor MCP de configuración — que deja a una IA leer y configurar integraciones —, el CMS publica un segundo servidor MCP, el de integraciones: expone Entregas y Recolecciones que usted marque como tools (el término del protocolo MCP) que un agente de IA llama para enviar datos al CMS o buscar datos a través de él.

La diferencia importa: el servidor de configuración arma integraciones; el de integraciones usa las que ya existen. Una Entrega se vuelve una tool “envíe esto al MES”; una Recolección se vuelve “consulte el stock en el ERP”. El agente no necesita conocer la URL, la autenticación ni el formato — completa los campos que la tool declara, y el CMS hace el resto por el mismo camino de cualquier productor.

Nada queda expuesto por defecto. Una Definición solo se vuelve tool después de que alguien activa Exponer como tool MCP en su pantalla. Los Packs y la propia IA nunca activan esa marca.

La dirección es por Aplicación

Cada Aplicación tiene su dirección:


POST https://SU-CMS/api/mcp/applications/{SIGLA}

Lista solo las Entregas y Recolecciones de esa Aplicación que están marcadas y que la credencial ve. El servidor de configuración (/api/mcp) sigue separado — una API Key de un sistema externo nunca alcanza las herramientas de crear/configurar.

Quién puede llamar

Tres credenciales, las mismas que ya envían datos al CMS — ninguna nueva que distribuir:

Credencial	Cómo	Dónde se crea
API Key	`Authorization: Bearer <token>`	API Keys
Credencial de Entrada	`Authorization: Basic base64(login:clave)`	Credenciales, dirección Entrada
Token MCP de usuario	`Authorization: Bearer cms_mcp_…`	Servidor MCP, en Servicios de Seguridad

El token MCP de usuario exige además, en el Perfil del usuario de servicio, la Herramienta /mcp/integration-tools — en la pantalla de Perfiles aparece como MCP Integration Tools. Poder editar una Entrega no es poder accionarla para escribir en un equipo o ERP. Y el token vale mientras vale el usuario: desactivar el usuario de servicio derriba su token al instante, sin esperar la expiración.

Exponer una Definición

Encuentre la llave en el formulario

Edite la Entrega o la Recolección. La llave Exponer como tool MCP tiene el mismo aspecto que Activar WebService (WSDL) y está al lado de ella:

Entrega — en la primera línea de la sección Validaciones de Recepción.
Recolección — en la línea de la URL de la API Dinámica, que aparece apenas la Recolección gana el primer Parámetro de Entrada.

Una Recolección sin Parámetro de Entrada, o de un tipo que la propia fuente activa (MQTT, OPC UA Trigger, archivo), no muestra la llave: nunca aparecería para la IA.

Active la llave

Activada, aparecen la Dirección MCP de la Aplicación, con botón de copiar, y un botón con el estado de la configuración: Configurada, en verde, o Configurar, en naranja. Naranja quiere decir que falta nombre, descripción o límite — y, en ese estado, la Definición no se guarda con la tool activada.

Al activarla por primera vez, el nombre ya viene sugerido a partir de la sigla y el límite nace en 30 llamadas por minuto.

El botón abre el popup Configuración de la tool MCP:

Nombre de la tool — es lo que el agente hace coincidir (hasta 64 caracteres, letras, números, _ y -; único en la Aplicación, sumando Entregas y Recolecciones). Hay un botón de sugerencia.
Descripción para la IA — lo que el modelo lee para decidir usar la tool. Describa qué hace, cuándo usarla y qué devuelve. El botón con ícono de destello sugiere la descripción con IA (ver abajo).
Límite/min — tope de llamadas por minuto. En escritura física, use un valor bajo.
En la Recolección, Devolver el contenido recogido a la IA decide si la tool devuelve lo que buscó (la API REST de Recolección nunca lo devolvió). El contenido cifrado nunca sale.
En una Entrega que escribe en un equipo o ERP — OPC UA, Modbus, Sparkplug, PI, BAPI con commit —, un aviso rojo recuerda que un agente autorizado podrá accionar esa escritura.
Cómo configurar y usar despliega el resumen del acceso y el fragmento de configuración del cliente MCP, con botón de copiar.

El popup edita el formulario en vivo; nada se graba hasta el Guardar de la Definición.

Conecte el cliente

Apunte el cliente MCP (Claude Desktop, VS Code, Cursor) a la dirección, con una de las credenciales de arriba. El botón Conectar vía MCP arma el fragmento listo — vea la sección siguiente.

La descripción sugerida por la IA

Escribir una buena descripción es la parte difícil: es lo que hace que el agente elija la tool correcta. El botón de sugerencia entrega un borrador a partir de lo que está guardado en la Definición — por eso solo funciona después del primer guardado, y queda desactivado, con la explicación, hasta entonces.

El modelo recibe las descripciones de la Aplicación y de la Interfaz, los parámetros (y cuáles son obligatorios), si la Recolección devuelve contenido, el modo de la Entrega y si esta escribe en un equipo. Nunca recibe credenciales ni datos de la conexión. El texto vuelve en el idioma de la pantalla, con hasta 600 caracteres — la descripción va en cada listado de tools, y un texto largo cuesta en cada llamada.

La sugerencia entra en el campo con un Deshacer al lado, y solo vale después de que alguien la revisa y guarda. Depende de la IA configurada y del recurso Descripción de tool MCP por IA, en Configuración › IA; con uno de los dos desactivado, el botón dice por qué. Cada sugerencia queda en el Log de Auditoría.

Conectar vía MCP

El popup Conectar vía MCP muestra la dirección, el encabezado de autenticación y un ejemplo de configuración para pegar en el cliente:


{
  "mcpServers": {
    "cms-MES": {
      "url": "https://SU-CMS/api/mcp/applications/MES",
      "headers": { "Authorization": "Bearer <su-token>" }
    }
  }
}

Se abre desde tres lugares:

Dónde	Autenticación en el ejemplo
API Keys, en la fila de cada clave	`Bearer`
Credenciales, solo en las de dirección Entrada	`Basic` (login y contraseña)
Servidores MCP, al abrir cada Aplicación	Cualquiera de las tres

El secreto nunca aparece en el popup: el ejemplo trae un marcador, y quien configura pega el valor que ya tiene en mano — por el botón Copiar de la propia pantalla, que registra quién copió.

Qué devuelve la tool

Tipo	La tool…	La IA recibe
Entrega síncrona	envía y espera al destino	la respuesta del destino
Entrega asíncrona	encola	el id del mensaje (siga con `cms_message_status`)
Recolección	ejecuta y reenvía a los destinos	id y estado; y el contenido, si lo marcó

Los argumentos son el contrato de entrada de la Definición: los Parámetros de Entrada de la Recolección, el Payload de Entrada de la Entrega. Una Entrega sin contrato de entrada recibe el cuerpo del mensaje listo, en un argumento único, corpo, en el Content-Type de la Definición.

Como los argumentos ya llegan en el formato de la Entrega, la tool no pasa por el Transformador por Aplicación productora — ni cuando se llama con la API Key de una productora que tiene uno. Solo se ejecuta el Transformador de la propia Entrega.

La tool fija cms_message_status muestra la situación de los mensajes que esa credencial envió por MCP — estado, intentos, fechas.

El estado viene en inglés

Internamente, el estado de un mensaje es un valor en portugués (NAO_PROCESSADA, ERRO_ENTREGA…), que las pantallas traducen. En la respuesta del MCP se vuelve un valor estable en inglés, con una frase corta, situacao, que el agente transmite en el idioma de quien preguntó:

`status`	Significa
`queued`	Recibido y en la cola; la entrega o el reenvío está programado
`processing`	En procesamiento
`done`	Concluido con éxito
`retrying`	Esperando un nuevo intento automático
`error`	Falló al entregar en el destino, o al recolectar en el origen
`business_error`	Rechazado por una regla de Error de Negocio
`cancelled`	Cancelado
`source_offline`	La Aplicación de origen está fuera de línea; corre sola cuando vuelva
`destination_offline`	El destino está fuera de línea; el mensaje espera un nuevo intento

El agente del otro lado atiende a gente en cualquier idioma: un NAO_PROCESSADA crudo terminaba repetido tal cual para el usuario.

Servidores MCP — `/mcp-servers`

Cada Aplicación con tools MCP es un servidor: uso por credencial, estado y contrato

Toda Aplicación con al menos una Entrega o Recolección marcada como tool es un servidor MCP, con dirección propia. Esta pantalla, en Config. de Integración justo después de Disparadores, reúne esos servidores y las tools de cada uno. Las dos pantallas quedan una al lado de la otra porque responden a la misma pregunta: quién más dispara esta Recolección o Entrega, además del sistema de origen — el programador interno o un agente de IA.

Cada Aplicación es un bloque que se expande — solo, cuando hay una sola o cuando hay una búsqueda activa. El encabezado cuenta las tools activas, las inactivas y las llamadas. Abierto, el bloque muestra la dirección MCP con botón de copiar, el Conectar vía MCP y una fila por tool:

Columna	Qué muestra
Herramienta	El nombre que ve el agente y, debajo, si es Recolección o Entrega, con la sigla de la Definición · Interfaz
Descripción	La descripción para la IA, truncada — el texto completo aparece al pasar el mouse
Llamadas	Cuántas llamadas llegaron a la tool, y cuántas fallaron
Credencial	La última credencial que llamó; el +N abre el uso separado por credencial
Último uso	Cuándo fue la última llamada, y si falló
Estado	Activa o inactiva, con el botón de activar y desactivar

El ícono de la fila abre el Contrato de entrada. Nombre, descripción, límite y parámetros se siguen editando en el registro de la Definición — esta pantalla responde “qué puede llamar la IA ahora”.

La pantalla abre en Activas. Las desactivadas quedan en Inactivas y Todas — es allí donde se reactiva una tool sin abrir el formulario. Se puede filtrar por una o más Aplicaciones, y la búsqueda busca por tool, descripción, Definición, Interfaz o Aplicación.

Encender y apagar desde aquí

Activar o desactivar en esta pantalla es lo mismo que marcar o desmarcar la llave en el registro, y el cambio entra en el historial de cambios de la Definición. La confirmación dice el efecto de antemano: al desactivar, la tool desaparece para los agentes y las llamadas pasan a ser rechazadas, pero nombre, descripción y parámetros siguen guardados. Al activar una Entrega, el aviso recuerda que el agente podrá enviar mensajes por ella hasta el destino.

Activar vuelve a aplicar las mismas validaciones del formulario — nombre, descripción, límite, parámetros, nombre único en la Aplicación. Una Recolección sin Parámetros de Entrada se rechaza: nunca aparecería para la IA.

Una tool activa puede, aun así, ser invisible para el agente. La fila avisa No aparece para la IA y dice por qué: la Definición está inactiva, o la Recolección no tiene Parámetros de Entrada.

Qué cuenta como llamada

Cada llamada (tools/call) que llega a la tool cuenta una vez, separada por credencial — API Key, Credencial de Entrada o token MCP. Una llamada rechazada por argumento inválido o por el límite por minuto cuenta como falla, igual que la Entrega que el destino rechazó.

El contador es propio, y no un conteo de mensajes: el mensaje desaparece con la retención de la Interfaz, y una Recolección genera varios mensajes en una sola llamada. Empezó a contar en la versión que trajo esta pantalla — las llamadas anteriores no aparecen.

El contrato de entrada

El popup de contrato muestra lo que el agente recibe al listar las tools: el comportamiento (Entrega síncrona o asíncrona, Recolección con o sin devolución de contenido), y una fila por parámetro, con tipo, obligatorio, valor por defecto, restricción (rango o lista de valores) y la descripción para la IA. Ver el JSON Schema enviado a la IA muestra el inputSchema exacto — el mismo que el servidor entrega en el tools/list, y no una reconstrucción.

Permiso

La pantalla tiene Herramienta propia, Servidores MCP (/mcp-servers), con dos niveles: consultar y activar/desactivar. La lista respeta las Interfaces permitidas del usuario, y activar una tool de una Interfaz que él no ve se rechaza. En una instalación nueva, el perfil CMS_Developer ya viene con el nivel de edición — quien construye la integración ya activa la tool desde el formulario; aquí es el mismo campo, en lote.

Dónde aparece la llamada después

En las pantallas de Mensajes, el mensaje creado por una tool MCP lleva un ícono de robot violeta — en la grilla, en el popup y en la página del mensaje —, con el nombre de la tool y de la credencial al pasar el mouse.
En el botón Configuraciones de la Definición, la pestaña API Keys gana la línea Expuesta como tool MCP, con el nombre y la dirección.

Seguridad

Marcado humano, por Definición. Nada es tool sin que alguien la marque; la escritura física pide confirmación al guardar.
Validación antes de que exista el mensaje. Alias desconocido, obligatorio faltante o valor fuera del rango configurado se vuelven un error para que el agente corrija, sin crear mensaje.
Límite por minuto por tool y credencial.
Alcance por la credencial. La tool nunca da más acceso del que la credencial ya tiene por la API. Se puede tener una API Key solo de lectura y otra solo de escritura — recomendado para escritura física.
El secreto nunca sale, y el contenido cifrado nunca se descifra para el agente. El barrido de secretos corre antes de que la respuesta se vuelva texto, y no solo en su versión estructurada.

El modelo del otro lado es del cliente. Lo que una Recolección devuelve entra en su contexto; si la misma sesión tiene una tool de escritura, un texto malicioso en los datos podría inducir una escritura. Separe las credenciales de lectura y de escritura.

Encender y apagar el servidor

En Configuración › IA, la llave Servidor MCP de integraciones enciende o apaga toda la dirección, separada de la llave del servidor de configuración. Viene encendida — como nada queda expuesto sin marcar una Definición, el control real es la marcación. Con ella apagada, la pantalla Servidores MCP muestra una franja que avisa que ninguna tool responde hasta que el servidor se vuelva a encender.