Ir al contenido

Conectar una IA por MCP

MCP permite que una IA descubra herramientas del ERP y las invoque con entradas y salidas estructuradas. La conexión usa el mismo tenant, usuario efectivo y permisos que la API.

Campo Valor
Transporte Streamable HTTP, sin sesión persistente
URL https://TU_AMBIENTE/api/v1/mcp
Autenticación OAuth, Authorization Code + PKCE para personas
Resource/audience La misma URL completa del MCP
Scope inicial data:read
Alta de la aplicación Previa, por un administrador; no hay registro dinámico público
  1. Obtené del cliente de IA su URL de callback y el tipo de autenticación OAuth que admite.
  2. El administrador crea una nueva aplicación externa para ese cliente con el callback exacto, grant authorization_code, PKCE y data:read. Si requiere renovación, autoriza también refresh_token y offline_access.
  3. Configurá la URL MCP y el client_id en el cliente. Cada usuario inicia sesión con su cuenta de Mopdow y presta su consentimiento.
  4. Pedí a la IA que ejecute erp_identity_get, compruebe el tenant y liste los objetos disponibles antes de consultar registros.

Cada persona necesita API habilitada (api.enabled) y debe estar permitida por la política de la aplicación. Si aparece api_access_disabled, un administrador debe asignar ese permiso; repetir el login o solicitar más scopes no lo resuelve.

Una sola aplicación puede atender a varios usuarios. El token es individual. No copies un token de administrador para que lo usen todos. La compatibilidad depende de que el cliente admita Streamable HTTP y OAuth con aplicaciones previamente registradas; un cliente que sólo admita registro dinámico necesitará incorporar ese modo.

Las aplicaciones creadas antes de esta entrega pueden no tener autorizada la audiencia MCP. Registrá una nueva aplicación para MCP; no reutilices un token REST. No hace falta modificar las conexiones REST existentes.

El catálogo tools/list se filtra por la release, los módulos habilitados, los paquetes activos y compatibles, los scopes del token y de la aplicación, y los permisos requeridos. Estos controles se repiten al ejecutar; también se verifican campos, registros, sharing y reglas de negocio.

Las capacidades y campos editables de erp_objects_list y erp_objects_describe describen esta conexión. Combinan los scopes concedidos, la publicación del objeto y los permisos reales del usuario. Usá erp_integration_capabilities y erp_integration_openapi para consultar el contrato efectivo. Las conexiones existentes no reciben permisos nuevos automáticamente: un administrador debe habilitarlos en la aplicación y el usuario debe volver a autorizar los scopes necesarios.

Estos son ejemplos de herramientas de lectura. El catálogo común enlazado debajo incluye también operaciones de escritura de la plataforma y los módulos reutilizables.

Herramientas Scopes
erp_identity_get Identidad de la conexión válida
erp_objects_list, erp_objects_describe data:read
erp_records_list, erp_records_get, erp_records_history data:read
erp_records_transitions_list actions:read
erp_metadata_retrieve, erp_metadata_deployments_list, erp_metadata_deployments_get setup:read
erp_metadata_validate metadata:deploy y permiso de lectura de metadata

Cada herramienta declara JSON Schema de entrada y salida. Los argumentos usan path, query y body cuando corresponden:

{ "path": { "objectApiName": "NOMBRE_OBTENIDO_DE_OBJECTS_LIST" }, "query": { "take": 5, "includeTotal": true } }

La respuesta exitosa tiene structuredContent: {data, meta}; meta.requestId permite correlacionar auditoría y meta.etag aparece en lecturas individuales. También se incluye su representación JSON en content. Los resultados se limitan a 2 MB: reducí selección o paginá si aparece result_too_large.

El catálogo MCP común contiene los esquemas de CRUD, acciones registradas, archivos, analítica, cargas masivas, calendario, notificaciones, agentes y metadata. Las operaciones de paquetes se descubren con autenticación, según sus requisitos y permisos. Los nombres se generan desde el identificador de operación: records.create se convierte en erp_records_create. Las rutas internas del ERP y el código arbitrario no forman parte de este catálogo.

Antes de escribir, la IA debe obtener autorización explícita del usuario y describir el tenant y la modificación. Después envía confirmed: true y headers.idempotency-key. Este reconocimiento de intención no acredita identidad humana ni reemplaza las aprobaciones del ERP. Un agente no debe aprobar sus propias acciones. Las restricciones de principales BOT y de aprobadores humanos se conservan.

{
"path": { "objectApiName": "OBJETO_DESCUBIERTO" },
"body": { "name": "Registro de ejemplo autorizado" },
"headers": { "idempotency-key": "intencion-unica-20260928-001" },
"confirmed": true
}

Conservá la misma clave y argumentos al reintentar la misma intención. Para ediciones condicionales, enviá el meta.etag de una lectura reciente en headers.if-match. No generes otra clave ante un timeout sin consultar primero el resultado. meta.httpStatus conserva el estado REST y meta.replayed indica una respuesta de idempotencia. Los trabajos asíncronos requieren consultar su estado final.

Los errores mantienen el código público y httpStatus: por ejemplo 403 por permisos, 409 por conflicto, 412 por ETag vencido y 429 por límite de solicitudes. Son rechazos esperados, no confirmaciones de una escritura.

Las subidas usan file: {"name":"archivo.txt","mimeType":"text/plain","base64":"..."} junto con path, los campos de metadata en body, headers y confirmed. Las descargas devuelven data.base64, mimeType, byteSize y contentDisposition. El límite de archivo MCP es 1 MiB, o el límite menor configurado para la operación; para archivos mayores usá REST o CLI dentro de sus límites. Cada campo de metadata de la subida admite hasta 8 KiB. MCP no descarga URLs proporcionadas por la IA ni lee rutas del servidor. Las respuestas JSON conservan el límite de 2 MB.

Usá el nombre exacto que exponga tu cliente. Algunos clientes agregan un prefijo: Gemini CLI puede mostrar mcp_mopdow_erp_erp_identity_get para la herramienta erp_identity_get del servidor. No inventes variantes del nombre.

En la identidad, principal.appUserId identifica al usuario efectivo y client.name identifica a la aplicación conectada. No presentes el nombre de la aplicación como si fuera el nombre de la persona.

Ante una solicitud sin autenticación, el servidor responde 401 con WWW-Authenticate apuntando a /.well-known/oauth-protected-resource/api/v1/mcp. Esa metadata indica el recurso y el authorization server. El cliente debe solicitar el resource en el flujo OAuth y enviar Authorization en cada solicitud.

resources/list ofrece mopdow://integration-manifest, con instrucciones y enlaces a los contratos del ambiente. El prompt explore_erp ayuda a seguir el orden identidad → objetos → campos → consulta.

Los clientes web deben usar un origen registrado en sus callbacks o el origen del ERP. GET y DELETE en la URL MCP responden 405; las interacciones se realizan con POST conforme al transporte Streamable HTTP sin sesiones.