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.
Configuración de la conexión
Sección titulada «Configuración de la conexión»| 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 |
- Obtené del cliente de IA su URL de callback y el tipo de autenticación OAuth que admite.
- El administrador crea una nueva aplicación externa para ese cliente con el callback exacto, grant
authorization_code, PKCE ydata:read. Si requiere renovación, autoriza tambiénrefresh_tokenyoffline_access. - Configurá la URL MCP y el
client_iden el cliente. Cada usuario inicia sesión con su cuenta de Mopdow y presta su consentimiento. - 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.
Herramientas de esta versión
Sección titulada «Herramientas de esta versión»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.
Escrituras
Sección titulada «Escrituras»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.
Archivos
Sección titulada «Archivos»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.
Descubrimiento automático
Sección titulada «Descubrimiento automático»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.