Utiliser des données à l’aide de l’interface CLI Dataverse (préversion)

L’interface CLI Dataverse est un outil en ligne de commande multiplateforme pour Microsoft Dataverse. Utilisez-le pour gérer les profils d’authentification, interroger et modifier des données, découvrir et appeler des API, travailler avec des environnements ERP (Finance and Operations) liés et exécuter un serveur MCP (Model Context Protocol) qui permet aux assistants IA d’interagir avec votre environnement.

L’interface CLI est distribuée en tant que @microsoft/dataverse package npm. Les fonctionnalités clés sont les suivantes :

• Authentification basée sur un profil compatible avec Microsoft Power Platform profils d'authentification CLI.
• Commandes d’environnement (org / env) pour afficher l’organisation actuelle et répertorier les environnements accessibles.
• Commandes de données pour interroger, obtenir, créer, mettre à jour, upsert, supprimer et compter les enregistrements ; charger des fichiers dans des colonnes de fichiers ; et associer ou dissocier les enregistrements associés.
• Commandes dynamiques api permettant de découvrir, décrire et appeler des API personnalisées Dataverse et des points de terminaison de service ERP invocables, ou pour envoyer des requêtes HTTP authentifiées brutes.
• skill commandes permettant de charger, télécharger, répertorier et supprimer des compétences Dataverse utilisées par les agents IA.
• Un serveur MCP pour les clients IA tels que Claude Desktop.
• --json sortie sur les commandes prises en charge pour l’écriture de scripts.

Pour obtenir la liste complète des commandes et de leurs paramètres, consultez la référence de l’interface CLI Dataverse.

Prerequisites

Pour installer et exécuter l’interface CLI, vous devez Node.js (y compris npm) installé sur une plateforme prise en charge.

Avant de pouvoir vous authentifier et vous connecter à un environnement Dataverse avec le serveur MCP, un administrateur doit effectuer les trois étapes de configuration suivantes :

1. Accordez le consentement de l’administrateur (administrateur de locataire Azure). Un administrateur de locataire Azure accorde le consentement de l’administrateur pour l’application de l’outil CLI MCP Dataverse en accédant àhttps://login.microsoftonline.com/{your-tenant-id}/adminconsent?client_id=0c412cc3-0dd6-449b-987f-05b053db9457, en vous connectant et en acceptant les autorisations demandées. Remplacez {your-tenant-id} par votre ID de locataire Azure réel.

2. Activez le serveur MCP (Administrateur Dataverse). Un administrateur d’organisation Dataverse active la fonctionnalité de serveur MCP pour l’environnement. Consultez Activer Dataverse MCP (production) ou Activer Dataverse MCP (préversion).

3. Autoriser l’outil CLI MCP (Administrateur Dataverse). Un administrateur d’organisation Dataverse ajoute l’outil CLI Dataverse MCP à la liste des applications clientes autorisées en suivant configurer la liste des clients MCP et en ajoutant l’application avec l’ID d’application 0c412cc3-0dd6-449b-987f-05b053db9457. Il apparaît en tant qu’outil CLI MCP Dataverse dans l’interface utilisateur.

   Vous pouvez également ajouter l’application à un utilisateur disposant d’autorisations d’administrateur Dataverse à l’aide de la mcp allow commande.

Plateformes prises en charge

L’interface CLI Dataverse prend en charge les plateformes suivantes :

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

Installer l’interface CLI Dataverse

Installez l’interface CLI globalement à l’aide de npm :

npm install -g @microsoft/dataverse

Vous pouvez également exécuter l’interface CLI sans l’installer à l’aide de npx:

npx @microsoft/dataverse <command> [options]

Pour installer une version spécifique ou pour effectuer une mise à jour vers la dernière version, utilisez la install commande :

dataverse install latest
dataverse install 1.0.0

L’interface CLI vérifie automatiquement npm pour les versions plus récentes lorsque vous exécutez une commande. Si une version plus récente est disponible, elle vous avertit afin de pouvoir la mettre à jour.

Utiliser avec Claude Desktop

Vous pouvez exécuter l’interface CLI en tant que serveur MCP afin que Claude Desktop puisse interagir avec votre environnement Dataverse.

Le moyen le plus rapide de l’ajouter est avec l’interface CLI Claude :

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

Pour configurer Claude Desktop manuellement, modifiez le fichier de configuration MCP :

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

Ajoutez le serveur à la mcpServers section :

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

Pour capturer des diagnostics détaillés, ajoutez les options et --log-file les --log-level Debug options au args tableau. Pour utiliser le point de terminaison MCP en préversion, ajoutez l’option --preview . Redémarrez Claude Desktop après avoir modifié la configuration.

Pour plus d’informations sur le démarrage du serveur, consultez la mcp commande.

Authentification

L’interface CLI utilise le Microsoft Authentication Library (MSAL) pour l’authentification. Il met en cache les profils d’authentification et les jetons localement. Ces profils fonctionnent avec Microsoft Power Platform profils d’authentification CLI.

Créez un profil la première fois que vous vous connectez à l’aide de la auth create commande :

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

Cette commande ouvre une boîte de dialogue d’authentification système ou de navigateur. Une fois connecté, le profil est enregistré. Les commandes suivantes, notamment mcp, utilisent les jetons mis en cache sans vous inviter à nouveau.

Pour utiliser plusieurs environnements, créez un profil nommé pour chacun d’eux. Basculez entre eux à l’aide de la auth select commande :

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

Pour les scénarios sans assistance tels que CI/CD, authentifiez-vous auprès d’un principal de service :

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

Pour les environnements sans navigateur, utilisez le flux de code de l’appareil en ajoutant l’option --deviceCode . Pour afficher toutes les options d’authentification, notamment le certificat, l’identité managée et l’authentification fédérée, exécutez dataverse auth create --help. Pour consulter, répertorier et supprimer des profils, consultez les commandes auth listet auth remove les auth whocommandes.

Obtenir de l’aide

Chaque commande et sous-commande prend en charge l’option --help . Il répertorie l’utilisation, les options et les exemples. Par exemple:

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

Opérations MCP prises en charge

Le serveur MCP prend en charge les opérations suivantes :

• Outils : répertorier et appeler des outils Dataverse.
• Invites : répertorier et récupérer des invites.
• Ressources : répertorier et lire les ressources Dataverse.

Lorsque l’URL de l’environnement est un hôte Finance and Operations (ERP), par https://myorg.operations.dynamics.comexemple, la mcp commande est automatiquement acheminée vers le serveur ERP MCP.

Troubleshooting

Valider votre configuration

Avant de démarrer le serveur, validez l’authentification et la configuration MCP à l’aide de l’option --validate :

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

Cette option vérifie les points de terminaison en disponibilité générale et en préversion et vérifie que l’authentification fonctionne, que le serveur MCP est activé et que l’outil CLI MCP figure dans la liste des applications autorisées. En cas d’échec de la validation, la sortie identifie l’étape requise à effectuer.

Activer la journalisation

Si vous rencontrez des problèmes, activez la journalisation des fichiers pour capturer des informations de diagnostic détaillées :

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

Les fichiers journaux sont écrits dans le répertoire temporaire de votre système. L’emplacement exact s’affiche au démarrage de la journalisation.

Problèmes courants

Aucun binaire compatible trouvé pour votre plateforme

L’interface CLI prend en charge Windows (x64, Arm64), macOS (x64, Arm64) et Linux (x64, Arm64). Les autres plateformes ne sont pas prises en charge par les fichiers binaires prédéfinis.

Échecs d’authentification

• Vérifiez que vous avez accès à l’environnement Dataverse.
• Vérifiez que l’URL de l’environnement est correcte.
• Effacez votre cache de jetons et ré-authentifiez-le à l’aide de la auth create commande.

Problèmes de connexion MCP dans Claude Desktop

• Vérifiez que la syntaxe JSON de configuration est correcte.
• Vérifiez que l’URL de l’environnement est accessible.
• Ajoutez l’option --log-file permettant de capturer des messages d’erreur détaillés.
• Redémarrez Claude Desktop après avoir modifié la configuration.

Voir aussi

Informations de référence sur l’interface CLI Dataverse