🧭 D365FO permite enseñar semántica al ERP MCP desde X++

Microsoft ha abierto una nueva superficie de extensibilidad para el servidor dinámico Dynamics 365 ERP MCP: los desarrolladores pueden añadir en X++ descripciones orientadas a IA a una entidad de datos, a sus campos y a un formulario. El servidor incorpora ese texto a sus respuestas para que cualquier agente autorizado reciba contexto de negocio junto a la metadata estructural.

Hasta ahora, nombres, tipos y etiquetas permitían descubrir qué existe, pero no siempre cómo debe utilizarse. Un agente podía encontrar una entidad de cabecera sin saber que las líneas viven en otra colección, intentar escribir un campo calculado o interpretar mal un estado. Las nuevas descripciones permiten declarar esas relaciones y restricciones cerca del propio artefacto X++.

No son instrucciones privadas de un agente ni una nueva barrera de seguridad. Son metadata compartida por todos los clientes que consulten el ERP MCP con acceso al objeto. Por eso cambian el contrato de extensibilidad: el conocimiento técnico deja de duplicarse en cada prompt y puede versionarse con el modelo de F&O.

Estado a 28 de octubre de 2026: Microsoft publicó la guía técnica el 27 de octubre, con fecha documental del 26 de octubre. No la etiqueta como preview, pero tampoco publica una versión mínima específica ni un calendario de despliegue para esta API. Sí exige los requisitos generales del servidor dinámico ERP MCP. Antes de depender de ella en producción, valida que tu entorno devuelve AiDescription y FormAiDescription.

Qué ha cambiado

Una clase o entidad puede declarar un método proveedor con el atributo McpAiDescriptionProviderAttribute. En tiempo de ejecución, el servidor localiza los proveedores del objeto y de sus extensiones, los ejecuta y combina su texto en la respuesta MCP.

Objeto descrito	Herramienta que lo devuelve	Propiedad de respuesta
Entidad de datos	data_get_entity_metadata	AiDescription
Campo de entidad	data_get_entity_metadata	Fields.<FieldName>.AiDescription
Formulario	form_open_menu_item	Context.FormAiDescription

El texto puede explicar:

• cuándo debe utilizarse una entidad o formulario;
• qué otras entidades contienen registros relacionados y con qué clave se enlazan;
• el significado operativo de estados o tipos;
• qué campos asigna o calcula el sistema y no debe modificar un agente.

No cambia qué entidades, campos, formularios o acciones están disponibles. Tampoco eleva permisos. La identidad autenticada y los roles de F&O siguen determinando la superficie visible.

Arquitectura: contexto junto al artefacto

La descripción se despliega dentro del mismo modelo que la entidad o su extensión. No existe un registro central que mantener.

1. El desarrollador implementa un proveedor X++.
2. El servidor ERP MCP descubre los métodos válidos del objeto y sus extensiones.
3. Ejecuta cada proveedor de forma aislada y concatena los fragmentos.
4. La herramienta MCP filtra la metadata según los permisos de lectura.
5. El orquestador usa el contexto para seleccionar entidades, campos o formularios.

Esto separa dos tipos de conocimiento:

Descripciones de IA	Instrucciones del agente
Hechos estables sobre entidades, campos, formularios y relaciones	Proceso, política, aprobaciones y secuencia de trabajo
Aplican a todos los agentes autorizados del entorno	Aplican solo al agente configurado
Las mantiene el equipo de desarrollo de F&O	Las mantiene el maker o propietario del escenario

Una regla útil es: describe el modelo en X++; describe el proceso en el agente.

Requisitos y disponibilidad

La documentación exige un entorno que ya cumpla los requisitos del servidor dinámico ERP MCP:

• Finance and Operations 10.0.47 o posterior, 10.0.46 PQU-2 o posterior, o 10.0.45 PQU-7 o posterior;
• característica Dynamics 365 ERP Model Context Protocol server habilitada cuando no lo esté por defecto;
• cliente registrado en Allowed MCP Clients;
• entorno Tier 2 o superior, o Unified Developer Environment;
• entorno de desarrollo X++ en el que compilar y desplegar el modelo.

Cloud Hosted Environments no están soportados por el servidor. Microsoft no relaciona todavía McpAiDescriptionProviderAttribute con un PQU concreto. Los mínimos anteriores habilitan el ERP MCP en general, no prueban que la extensión esté desplegada en cada región. Usa una consulta de metadata real como criterio de aceptación.

Implementación paso a paso

1. Elegir qué conocimiento debe vivir en metadata

Prioriza ambigüedades que puedan producir una selección incompleta o una escritura incorrecta:

• relaciones cabecera/línea repartidas entre entidades;
• campos con número de secuencia;
• estados que controla lógica de negocio;
• campos calculados o de solo lectura;
• formularios parecidos con responsabilidades distintas.

No incluyas datos de clientes, secretos, ejemplos reales ni instrucciones de aprobación. Las descripciones se devuelven a todos los agentes con acceso al objeto.

2. Describir una entidad propia

El método debe ser public static void, aceptar exactamente un McpIAiDescriptionBuilder y llevar el atributo. Usa la interfaz, no la clase concreta.

[McpAiDescriptionProviderAttribute]
public static void describeForAgents(McpIAiDescriptionBuilder _builder)
{
    _builder.appendDescription(
        'Rental agreement headers. Lines are stored in ContosoRentalAgreementLines. ' +
        'Join both entities by AgreementId.');

    _builder.appendFieldDescription(
        fieldStr(ContosoRentalAgreementEntity, AgreementId),
        'System-assigned agreement number. Leave empty when creating a record.');

    _builder.appendFieldDescription(
        fieldStr(ContosoRentalAgreementEntity, Status),
        'Lifecycle state controlled by the application. Do not update directly.');
}

appendDescription() añade contexto al objeto completo. appendFieldDescription() solo aplica a campos de entidades. Utiliza fieldStr() para que el compilador detecte renombrados o campos inexistentes.

3. Extender una entidad estándar

No es necesario modificar el objeto de Microsoft. Añade un proveedor en una extensión de clase de la entidad:

[ExtensionOf(dataEntityViewStr(CustCustomerV3Entity))]
public final class CustCustomerV3Entity_ContosoRental_Extension
{
    [McpAiDescriptionProviderAttribute]
    public static void describeRentalRelation(McpIAiDescriptionBuilder _builder)
    {
        _builder.appendDescription(
            'Customers with rental activity have agreements in ContosoRentalAgreements.');

        _builder.appendFieldDescription(
            fieldStr(CustCustomerV3Entity, CustomerAccount),
            'Use this value to filter ContosoRentalAgreements by CustomerAccount.');
    }
}

El servidor no reemplaza la descripción base: combina todos los proveedores válidos. Esta composición hace posible que varios ISV añadan contexto, pero también convierte la longitud total en un recurso compartido.

4. Describir un formulario

Los formularios solo admiten descripción de nivel superior:

[ExtensionOf(formStr(ContosoRentalAgreement))]
public final class ContosoRentalAgreementForm_Extension
{
    [McpAiDescriptionProviderAttribute]
    public static void describeForAgents(McpIAiDescriptionBuilder _builder)
    {
        _builder.appendDescription(
            'Use this form to review rental agreements and record equipment returns.');
    }
}

La resolución se realiza por nombre de formulario, no por nombre del menu item. Cualquier menu item que abra ese formulario recibe la misma descripción.

5. Compilar, desplegar y verificar

Después del despliegue:

1. llama a data_get_entity_metadata con el nombre público de la colección;
2. comprueba AiDescription en la raíz y en los campos esperados;
3. abre un menu item mediante form_open_menu_item;
4. comprueba Context.FormAiDescription;
5. ejecuta una prueba conversacional que obligue al agente a elegir entre objetos ambiguos;
6. conserva la respuesta de metadata como evidencia de versión y despliegue.

Una respuesta abreviada debería tener esta forma:

{
  "AiDescription": "Rental agreement headers. Lines are stored in ContosoRentalAgreementLines.",
  "Fields": {
    "Status": {
      "AiDescription": "Lifecycle state controlled by the application. Do not update directly."
    }
  }
}

Límites que condicionan el diseño

Firma inválida y fallos silenciosos

Si el método no cumple exactamente la firma o carece del atributo, el servidor lo omite sin error. Una descripción ausente debe investigarse primero en compilación, atributo, parámetro y ubicación del proveedor.

Si un proveedor lanza una excepción, el servidor registra el fallo y sigue devolviendo el texto de los demás. La tool call no falla. Esto mejora la resiliencia, pero exige observabilidad: un agente puede operar con contexto parcial.

Composición sin orden garantizado

Todos los fragmentos se añaden en líneas separadas, pero el orden de ejecución no está garantizado. Cada texto debe tener sentido de forma independiente. El builder no ofrece reemplazo ni eliminación de contenido aportado por otro proveedor.

Los proveedores de clases padre y sus extensiones no se heredan. Solo cuentan los definidos en el objeto objetivo y en sus propias extensiones.

Límites de longitud

El servidor trunca sin aviso ni puntos suspensivos:

Descripción combinada	Máximo predeterminado
Entidad o formulario	1.500 caracteres
Cada campo	500 caracteres

Como el límite se aplica después de combinar proveedores, una extensión puede consumir el espacio de otra. Coloca primero la información decisiva y prueba el resultado final, no solo tu fragmento.

Seguridad, gobierno y costes

La descripción de un campo solo aparece si el usuario autenticado puede leerlo. El filtrado reduce exposición, pero el texto en sí no debe contener información confidencial, personal ni específica de un cliente.

La metadata no convierte un campo en solo lectura. Frases como «no actualizar directamente» orientan al modelo, pero la protección real debe permanecer en permisos, validaciones X++, separación de funciones y confirmaciones del cliente. Trata el texto como ayuda de orquestación, no como control de seguridad.

Las descripciones se incluyen en las respuestas que procesa el modelo y, por tanto, consumen contexto. Microsoft no documenta una tarifa adicional para esta capacidad; se mantienen las reglas de facturación del ERP MCP: en Copilot Studio, la llamada forma parte de Agent Action; en otros clientes, la ejecución del servidor se factura según los Copilot Credits publicados. Un contexto más preciso puede reducir búsquedas y reintentos, pero debe medirse.

Gobierna estas descripciones como código:

• revisión técnica y funcional en pull request;
• reglas de estilo y longitud;
• pruebas de metadata en el pipeline o sandbox;
• propietario por dominio de datos;
• revisión al renombrar entidades, campos o estados;
• regresión conversacional antes de promover el paquete.

Matriz de pruebas recomendada

Caso	Evidencia esperada
Entidad propia	AiDescription visible tras desplegar
Extensión de entidad estándar	Texto base y extensión combinados
Campo no autorizado	Campo y descripción ausentes
Proveedor con excepción	Resto del contexto disponible y error registrado
Varios modelos ISV	Fragmentos autónomos, sin depender del orden
Texto excesivo	Truncado detectado antes de producción
Formulario con varios menu items	Mismo FormAiDescription
Tarea ambigua	El agente elige todas las entidades relacionadas
Escritura controlada	El agente evita campos calculados, y F&O sigue validando

Recomendaciones prácticas

Empieza por pocas entidades de alto riesgo y compara trazas antes y después. Una buena descripción responde «cuándo usar», «cómo se relaciona» y «qué no tocar» sin repetir etiquetas o tipos que ya devuelve la metadata.

Evita convertir las descripciones en manuales de proceso. Si una aprobación depende de importe, compañía o rol, debe vivir en instrucciones y controles deterministas. Mantén en X++ solo hechos estables del modelo de aplicación.

Por último, no supongas disponibilidad por la versión funcional. Hasta que Microsoft publique un mínimo específico, incluye en el despliegue una prueba que compruebe las propiedades de respuesta. Esa evidencia protege frente a diferencias de rollout, PQU o región.

Conclusión

Las descripciones de IA convierten el modelo X++ en una fuente semántica para los agentes. La novedad es importante porque permite que relaciones, campos calculados y significado de estados viajen con la solución y se reutilicen desde Copilot Studio o cualquier otro cliente autorizado del ERP MCP.

El diseño sigue necesitando límites claros: texto conciso, sin secretos, independiente del orden y respaldado por seguridad real. Aplicada así, esta extensión reduce conocimiento duplicado en prompts y hace más determinista la selección de herramientas sin confundir orientación al modelo con autorización.

Referencias oficiales

• Add AI descriptions for the Dynamics 365 ERP MCP server
• Cambio oficial publicado el 27 de octubre de 2026
• Use Model Context Protocol for finance and operations apps
• Class extension model in X++
• Security in the Dynamics 365 ERP MCP server