Trabalhar com dados usando a CLI do Dataverse (versão prévia)

A CLI do Dataverse é uma ferramenta de linha de comando multiplataforma para Microsoft Dataverse. Use-o para gerenciar perfis de autenticação, consultar e modificar dados, descobrir e invocar APIs, trabalhar com ambientes vinculados de Finanças e Operações (ERP) e executar um servidor MCP (Model Context Protocol) que permite que os assistentes de IA interajam com seu ambiente.

A CLI é distribuída como o @microsoft/dataverse pacote npm. As principais funcionalidades incluem:

• Autenticação baseada em perfil compatível com perfis de autenticação da CLI Microsoft Power Platform.
• Comandos de ambiente (org / env) para exibir a organização atual e listar ambientes acessíveis.
• Comandos de dados para consultar, obter, criar, atualizar, upsert, excluir e contar registros; carregar arquivos em colunas de arquivo; e associar ou desassociar registros relacionados.
• Comandos dinâmicos api para descobrir, descrever e invocar APIs personalizadas do Dataverse e pontos de extremidade de serviço invocados por ERP ou enviar solicitações HTTP autenticadas brutas.
• skill comandos para carregar, baixar, listar e excluir habilidades do Dataverse usadas por agentes de IA.
• Um servidor MCP para clientes de IA, como o Claude Desktop.
• --json saída em comandos com suporte para script.

Para obter uma lista completa de comandos e seus parâmetros, consulte a referência da CLI do Dataverse.

Pré-requisitos

Para instalar e executar a CLI, você precisa Node.js (que inclui npm) instalado em uma plataforma com suporte.

Antes de autenticar e se conectar a um ambiente do Dataverse com o servidor MCP, um administrador deve concluir as três etapas de instalação a seguir:

1. Conceder consentimento do administrador (Azure administrador do locatário). Um administrador de locatários do Azure concede consentimento do administrador para o aplicativo de ferramentas da CLI do Dataverse MCP navegando atéhttps://login.microsoftonline.com/{your-tenant-id}/adminconsent?client_id=0c412cc3-0dd6-449b-987f-05b053db9457, entrando e aceitando as permissões solicitadas. Substitua {your-tenant-id} pela ID do locatário Azure real.

2. Habilite o servidor MCP (administrador do Dataverse). Um administrador de organização do Dataverse habilita o recurso de servidor MCP para o ambiente. Consulte Enable Dataverse MCP (produção) ou Enable Dataverse MCP (versão prévia).

3. Permitir a ferramenta da CLI do MCP (administrador do Dataverse). Um administrador de organização do Dataverse adiciona a ferramenta CLI do Dataverse MCP à lista de aplicativos cliente permitidos seguindo Configurar a lista de clientes MCP e adicionar o aplicativo com a ID 0c412cc3-0dd6-449b-987f-05b053db9457do aplicativo. Ele aparece como uma ferramenta da CLI do DATAverse MCP na interface do usuário.

   Como alternativa, um usuário com permissões de administrador do Dataverse pode adicionar o aplicativo usando o mcp allow comando.

Plataformas com suporte

A CLI do Dataverse dá suporte às seguintes plataformas:

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

Instalar a CLI do Dataverse

Instale a CLI globalmente usando npm:

npm install -g @microsoft/dataverse

Como alternativa, execute a CLI sem instalá-la usando npx:

npx @microsoft/dataverse <command> [options]

Para instalar uma versão específica ou atualizar para a versão mais recente, use o install comando:

dataverse install latest
dataverse install 1.0.0

A CLI verifica automaticamente npm para versões mais recentes quando você executa um comando. Se uma versão mais recente estiver disponível, ela notificará você para que você possa atualizar.

Usar com o Claude Desktop

Você pode executar a CLI como um servidor MCP para que o Claude Desktop possa interagir com seu ambiente do Dataverse.

A maneira mais rápida de adicioná-lo é com a CLI claude:

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

Para configurar o Claude Desktop manualmente, edite o arquivo de configuração do MCP:

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

Adicione o servidor à mcpServers seção:

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

Para capturar diagnósticos detalhados, adicione a matriz e --log-file as --log-level Debug opçõesargs. Para usar o ponto de extremidade do MCP de visualização, adicione a opção --preview . Reinicie o Claude Desktop depois de alterar a configuração.

Para obter mais informações sobre como iniciar o servidor, consulte o mcp comando.

Autenticação

A CLI usa o Biblioteca do Microsoft Authenticator (MSAL) para autenticação. Ele armazena em cache perfis de autenticação e tokens localmente. Esses perfis funcionam com perfis de autenticação da CLI Microsoft Power Platform.

Crie um perfil na primeira vez que você se conectar usando o auth create comando:

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

Esse comando abre uma caixa de diálogo de autenticação de navegador ou sistema. Depois que você entrar, o perfil será salvo. Os comandos subsequentes, incluindo mcp, usam os tokens armazenados em cache sem solicitar novamente.

Para trabalhar com mais de um ambiente, crie um perfil nomeado para cada um deles. Alterne entre eles usando o 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 cenários autônomos, como CI/CD, autentique-se com uma entidade de serviço:

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

Para ambientes sem um navegador, use o fluxo de código do dispositivo adicionando a opção --deviceCode . Para ver todas as opções de autenticação, incluindo certificado, identidade gerenciada e autenticação federada, execute dataverse auth create --help. Para examinar, listar e remover perfis, consulte o auth who, auth liste auth remove os comandos.

Obter ajuda

Cada comando e subcomando dá suporte à opção --help . Ele lista o uso, as opções e os exemplos. Por exemplo:

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

Operações MCP com suporte

O servidor MCP dá suporte às seguintes operações:

• Ferramentas: listar e chamar ferramentas do Dataverse.
• Prompts: listar e recuperar prompts.
• Recursos: listar e ler recursos do Dataverse.

Quando a URL do ambiente é um host ERP (Finanças e Operações), como https://myorg.operations.dynamics.com, o mcp comando é roteado automaticamente para o servidor ERP MCP.

Resolução de problemas

Validar a configuração

Antes de iniciar o servidor, valide a autenticação e a configuração do MCP usando a opção --validate :

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

Essa opção verifica os pontos de extremidade ga e de visualização e verifica se a autenticação funciona, o servidor MCP está habilitado e a ferramenta mcp CLI está na lista de aplicativos permitidos. Se a validação falhar, a saída identificará qual etapa de pré-requisito será concluída.

Habilitar registro de log

Se você encontrar problemas, habilite o log de arquivos para capturar informações detalhadas de diagnóstico:

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

Os arquivos de log são gravados no diretório temporário do sistema. O local exato é exibido quando o registro em log é iniciado.

Problemas comuns

Nenhum binário compatível encontrado para sua plataforma

A CLI dá suporte a Windows (x64, Arm64), macOS (x64, Arm64) e Linux (x64, Arm64). Não há suporte para outras plataformas pelos binários predefinidos.

Falhas de autenticação

• Confirme se você tem acesso ao ambiente do Dataverse.
• Confirme se a URL do ambiente está correta.
• Limpe o cache de tokens e autentique novamente usando o auth create comando.

Problemas de conexão do MCP no Claude Desktop

• Verifique se a sintaxe JSON de configuração está correta.
• Verifique se a URL do ambiente está acessível.
• Adicione a opção --log-file para capturar mensagens de erro detalhadas.
• Reinicie o Claude Desktop depois de alterar a configuração.

Consulte também

Referência da CLI do Dataverse