Trabajar con datos mediante la CLI de Dataverse (versión preliminar)

La CLI de Dataverse es una herramienta de línea de comandos multiplataforma para Microsoft Dataverse. Úselo para administrar perfiles de autenticación, consultar y modificar datos, detectar e invocar API, trabajar con entornos vinculados de Finanzas y Operaciones (ERP) y ejecutar un servidor de Protocolo de contexto de modelo (MCP) que permita a los asistentes de IA interactuar con su entorno.

La CLI se distribuye como paquete @microsoft/dataverse npm. Entre las funcionalidades clave se incluyen las siguientes:

• Autenticación basada en perfiles compatible con los perfiles de autenticación de Microsoft Power Platform CLI.
• Comandos de entorno (org / env) para ver la organización actual y enumerar los entornos accesibles.
• Comandos de datos para consultar, obtener, crear, actualizar, upsert, eliminar y contar registros; cargar archivos en columnas de archivo; y asociar o desasociar registros relacionados.
• Comandos dinámicos api para descubrir, describir e invocar API personalizadas de Dataverse y puntos de conexión de servicios invocables de ERP, o para enviar solicitudes HTTP autenticadas sin procesar.
• skill comandos para cargar, descargar, enumerar y eliminar aptitudes de Dataverse que usan los agentes de IA.
• Un servidor MCP para clientes de IA, como Claude Desktop.
• --json salida de los comandos compatibles para scripts.

Para obtener una lista completa de comandos y sus parámetros, consulte la referencia de la CLI de Dataverse.

Requisitos previos

Para instalar y ejecutar la CLI, necesita Node.js (que incluye npm) instalado en una plataforma compatible.

Para poder autenticarse y conectarse a un entorno de Dataverse con el servidor MCP, un administrador debe completar los tres pasos de configuración siguientes:

1. Otorgue el consentimiento de administrador (administrador del inquilino de Azure). Un administrador de inquilinos de Azure concede el consentimiento del administrador para la aplicación de la herramienta de la CLI de MCP de Dataverse; para ello, vaya a https://login.microsoftonline.com/{your-tenant-id}/adminconsent?client_id=0c412cc3-0dd6-449b-987f-05b053db9457, inicie sesión y acepte los permisos solicitados. Sustituya {your-tenant-id} por el identificador real del inquilino de Azure.

2. Habilite el servidor MCP (administrador de Dataverse). Un administrador de la organización de Dataverse habilita la característica de servidor MCP para el entorno. Consulte Habilitar Dataverse MCP (producción) o Habilitar Dataverse MCP (versión preliminar).

3. Autorizar la herramienta de línea de comandos de MCP (administración de Dataverse). Un administrador de la organización de Dataverse agrega la herramienta de la CLI de MCP de Dataverse a la lista de aplicaciones cliente permitidas siguiendo configurar la lista de clientes de MCP y agregando la aplicación con el identificador 0c412cc3-0dd6-449b-987f-05b053db9457de aplicación . Aparece como herramienta de la CLI de MCP de Dataverse en la interfaz de usuario.

   Como alternativa, un usuario con permisos de administrador de Dataverse puede agregar la aplicación mediante el mcp allow comando .

Plataformas compatibles

La CLI de Dataverse admite las siguientes plataformas:

• Windows (x64, Arm64)
• macOS (x64, Arm64 / Apple silicon)
• Linux (x64, Arm64)

Instalación de la CLI de Dataverse

Instale la CLI globalmente mediante npm:

npm install -g @microsoft/dataverse

Como alternativa, ejecute la CLI sin instalarla mediante npx:

npx @microsoft/dataverse <command> [options]

Para instalar una versión específica o para actualizar a la versión más reciente, use el install comando :

dataverse install latest
dataverse install 1.0.0

La CLI comprueba automáticamente npm para las versiones más recientes al ejecutar un comando. Si hay disponible una versión más reciente, le notifica para que pueda actualizar.

Uso con Claude Desktop

Puede ejecutar la CLI como un servidor MCP para que Claude Desktop pueda interactuar con el entorno de Dataverse.

La forma más rápida de agregarla es con la CLI de Claude:

claude mcp add dataverse -t stdio -- npx -y @microsoft/dataverse mcp https://yourorg.crm.dynamics.com

Para configurar Claude Desktop manualmente, edite el archivo de configuración de MCP:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Agregue el servidor a la mcpServers sección :

{
  "mcpServers": {
    "dataverse": {
      "command": "npx",
      "args": ["-y", "@microsoft/dataverse", "mcp", "https://yourorg.crm.dynamics.com"],
      "type": "stdio"
    }
  }
}

Para capturar diagnósticos detallados, agregue las opciones --log-level Debug y --log-file al array args. Para usar el punto de conexión MCP en versión preliminar, agregue la opción --preview. Reinicie Claude Desktop después de cambiar la configuración.

Para obtener más información sobre cómo iniciar el servidor, consulte el mcp comando .

Autenticación

La CLI usa el Biblioteca de autenticación de Microsoft (MSAL) para la autenticación. Almacena en caché los perfiles de autenticación y los tokens localmente. Estos perfiles funcionan con perfiles de autenticación de la CLI de Microsoft Power Platform.

Cree un perfil la primera vez que se conecte mediante el auth create comando :

dataverse auth create --environment https://myorg.crm.dynamics.com

Este comando abre un cuadro de diálogo de autenticación del sistema o explorador. Después de iniciar sesión, se guarda el perfil. Los comandos posteriores, incluidos mcp, usan los tokens almacenados en caché sin preguntarle de nuevo.

Para trabajar con más de un entorno, cree un perfil con nombre para cada uno. Cambie entre ellos mediante el auth select comando :

dataverse auth create --environment https://dev.crm.dynamics.com --name dev
dataverse auth create --environment https://prod.crm.dynamics.com --name prod
dataverse auth select --name dev

Para escenarios desatendidos como CI/CD, autentíquese con una entidad de servicio:

dataverse auth create --applicationId <appId> --clientSecret <secret> --tenant <tenantId> --environment https://myorg.crm.dynamics.com

Para entornos sin explorador, use el flujo de código del dispositivo agregando la --deviceCode opción . Para ver todas las opciones de autenticación, incluido el certificado, la identidad administrada y la autenticación federada, ejecute dataverse auth create --help. Para revisar, enumerar y quitar perfiles, consulte los auth whocomandos , auth listy auth remove .

Obtención de ayuda

Cada comando y subcomando admiten la --help opción . Enumera el uso, las opciones y los ejemplos. Por ejemplo:

dataverse --help
dataverse auth --help
dataverse auth create --help
dataverse org --help
dataverse mcp --help
dataverse data query --help

Operaciones de MCP admitidas

El servidor MCP admite las siguientes operaciones:

• Herramientas: enumerar y llamar a herramientas de Dataverse.
• Indicaciones: listar y recuperar indicaciones.
• Recursos: enumerar y leer recursos de Dataverse.

Cuando la dirección URL del entorno corresponde a un host de Finance and Operations (ERP), como https://myorg.operations.dynamics.com, el comando mcp se dirige automáticamente al servidor MCP de ERP.

Troubleshooting

Validación de la configuración

Antes de iniciar el servidor, valide la autenticación y la configuración de MCP mediante la --validate opción :

dataverse mcp https://yourorg.crm.dynamics.com --validate

Esta opción comprueba los puntos de conexión de disponibilidad general y versión preliminar y comprueba que la autenticación funciona, el servidor MCP está habilitado y la herramienta de la CLI de MCP se encuentra en la lista de aplicaciones permitidas. Si se produce un error en la validación, la salida identifica qué paso de requisito previo se va a completar.

Habilitar registro

Si tiene problemas, habilite el registro de archivos para capturar información detallada de diagnóstico:

dataverse mcp https://yourorg.crm.dynamics.com --log-level Debug --log-file

Los archivos de registro se escriben en el directorio temporal del sistema. La ubicación exacta se muestra cuando se inicia el registro.

Problemas comunes

No se encontró ningún binario compatible para la plataforma

La CLI admite Windows (x64, Arm64), macOS (x64, Arm64) y Linux (x64, Arm64). Otras plataformas no son compatibles con los archivos binarios creados previamente.

Errores de autenticación

• Confirme que tiene acceso al entorno de Dataverse.
• Confirme que la dirección URL del entorno es correcta.
• Borre la caché de tokens y vuelva a autenticarse mediante el auth create comando .

Problemas de conexión de MCP en Claude Desktop

• Compruebe que la sintaxis JSON de configuración es correcta.
• Compruebe que se puede acceder a la dirección URL del entorno.
• Agregue la --log-file opción para capturar mensajes de error detallados.
• Reinicie Claude Desktop después de cambiar la configuración.

Véase también

Referencia de la CLI de Dataverse