Conectar-se ao Dataverse com o protocolo de contexto de modelo em clientes que não são da Microsoft

Pode ligar-se ao Microsoft Dataverse usando um cliente de protocolo de contexto modelo (MCP) que não seja Microsoft, como o Claude desktop ou Claude Code. Existem duas abordagens para ligar clientes não Microsoft a um servidor MCP Dataverse:

• Proxy local: Use o @microsoft/dataverse pacote npm para executar um proxy local que se ligue ao servidor MCP do Dataverse em seu nome.
• Endpoint remoto: Conecte-se diretamente ao endpoint remoto do servidor MCP do Dataverse (/api/mcp) registando uma aplicação Microsoft Entra personalizada.

Pré-requisitos

• O servidor MCP do Dataverse deve estar ativado para o ambiente. Para obter mais informações: Configurar e gerenciar o servidor Dataverse MCP para um ambiente
• Para a abordagem do proxy local: Node.js (versão 18 ou posterior) instalado na sua máquina.
• Para a abordagem do ponto final remoto: aceda para registar uma aplicação no Microsoft Entra ID.

Ligue-se usando o proxy local

O @microsoft/dataverse pacote npm fornece um proxy local que gere a autenticação e comunicação com o servidor MCP do Dataverse. Esta abordagem é recomendada para a maioria dos clientes MCP não Microsoft que conseguem executar servidores MCP locais.

Conceder consentimento administrativo do inquilino

Um administrador de inquilinos deve conceder consentimento de administrador para a aplicação CLI do Dataverse antes de os utilizadores poderem autenticar-se. Navegue até ao seguinte URL num navegador, substituindo {your-tenant-id} pelo seu ID de tenant Microsoft Entra:

https://login.microsoftonline.com/{your-tenant-id}/adminconsent?client_id=0c412cc3-0dd6-449b-987f-05b053db9457

Inicie sessão com uma conta de administrador do inquilino e aceite o pedido de permissões. Este passo só precisa de ser completado uma vez por inquilino.

Ativar o cliente CLI do Dataverse no centro de administração do Power Platform

Antes de poderes ligar-te usando o proxy local, o cliente CLI do Dataverse deve estar ativado como cliente MCP permitido no teu ambiente.

1. Aceda ao Centro de administração da Power Platform. Selecione Gerenciar>ambientes.
2. Seleciona o ambiente onde queres ativar o cliente e depois seleciona Definições.
3. Em Configurações, selecione Funcionalidades> do Produto. Desça para localizar o Protocolo de Contexto do Modelo Dataverse e selecione Definições Avançadas.
4. Localiza o cliente CLI do Dataverse (ID 0c412cc3-0dd6-449b-987f-05b053db9457da aplicação) e define Está Ativado para Sim.
5. Selecione Guardar e Fechar.

Instalar o proxy local

Pode instalar o @microsoft/dataverse pacote globalmente ou executá-lo diretamente com npx.

Para instalar globalmente, execute o seguinte comando num terminal:

npm install -g @microsoft/dataverse

Alternativamente, pode usar npx para executar o proxy sem o instalar globalmente:

npx @microsoft/dataverse mcp https://yourorg.crm.dynamics.com

Configurar o proxy local no ambiente de trabalho Claude

Esta secção descreve como configurar o proxy local do servidor MCP Dataverse no desktop Claude. Se ainda não o fez, transfira e instale o Claude desktop.

1. Abre o ambiente de trabalho do Claude e vai a Ficheiro>Definições>Desenvolvedor.

2. Selecione Editar Configuração para abrir o claude_desktop_config.json ficheiro.

3. Adicione o seguinte excerto JSON ao ficheiro. Substitua <friendly name> por um nome que se lembre facilmente (por exemplo, MyDataverseMCPServer) e substitua <your org URL> pelo URL do ambiente Dataverse (por exemplo, https://contoso.crm.dynamics.com).

   {
     "mcpServers": {
       "<friendly name>": {
         "command": "npx",
         "args": [
           "-y",
           "@microsoft/dataverse",
           "mcp",
           "<your org URL>"
         ]
       }
     }
   }
   

4. Salve o arquivo.

Verifique a ligação no ambiente de trabalho Claude

1. Sai do ambiente de trabalho Claude selecionando Ficheiro>Sair e depois abre-o novamente para aplicar as alterações.
2. Inicie sessão com as suas credenciais quando solicitado para autenticar no seu ambiente Dataverse.
3. Selecione Pesquisa e ferramentas para verificar se o servidor MCP do Dataverse e as suas ferramentas estão disponíveis. Deves ver o nome amigável que configuraste (por exemplo, MyDataverseMCPServer).
4. Selecione o nome do servidor MCP para ver a lista de ferramentas suportadas pelo servidor.

Configurar o proxy local no Claude Code

Esta secção descreve como configurar o proxy local do servidor Dataverse MCP no Claude Code. Se ainda não o fizeste, descarrega e instala o Claude Code.

Execute o seguinte comando para adicionar o servidor MCP do Dataverse. Substitua https://yourorg.crm.dynamics.com pelo URL do ambiente Dataverse.

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

Verificar e interagir com a ligação em Claude Code

1. Reinicie o Claude Code para aplicar as alterações.
2. Inicie sessão com as suas credenciais quando solicitado para autenticar no seu ambiente Dataverse.
3. Verifique se o servidor MCP do Dataverse e as suas ferramentas estão disponíveis. Deves ver o nome amigável que configuraste (por exemplo, MyDataverseMCPServer).
4. Selecione o nome do servidor MCP para ver a lista de ferramentas suportadas pelo servidor.

Se tiveres dados no ambiente Dataverse, podes testar a configuração perguntando tabelas de listas no Dataverse, descrever a conta da tabela ou quantas contas tenho. Mais informações: Adicionar e remover dados de amostra

Ligue-se usando o endpoint remoto

Pode ligar clientes MCP que não sejam Microsoft diretamente ao endpoint remoto do servidor MCP da Dataverse sem usar um proxy local. Esta abordagem exige que registe uma aplicação personalizada no Microsoft Entra ID e adiciones o seu ID de cliente à lista de clientes permitidos no centro de administração do Power Platform.

Registe uma aplicação Microsoft Entra personalizada

Registar uma aplicação no Microsoft Entra ID para usar na autenticação ao ligar-se ao servidor MCP do Dataverse. Para informações gerais sobre registo de aplicações, consulte Registar uma aplicação na Microsoft Identity Platform.

Siga estes passos para registar uma aplicação para utilização no servidor MCP do Dataverse:

1. Entre no centro de administração do Microsoft Entra.
2. Vá a Identidade>Aplicações>Registos de Aplicações e depois selecione Novo registo.
3. Introduza um nome para a sua aplicação (por exemplo, Cliente MCP Dataverse), configure os tipos de conta suportados para o seu cenário e depois selecione Registar.
4. Na página de Visão Geral , note o ID da Aplicação (cliente). Precisa deste valor para configurar o cliente permitido no centro de administração do Power Platform e para configurar o seu cliente MCP.

Configurar permissões API para o servidor MCP do Dataverse

Depois de registares a aplicação, deves conceder-lhe permissões para aceder ao servidor MCP do Dataverse.

1. No registo da aplicação, selecione permissões da API no painel de navegação esquerdo.
2. Selecione Adicionar uma permissão.
3. Selecione as APIs da Microsoft e depois selecione Dynamics CRM.
4. Selecione a permissão mcp.tools e depois selecione Adicionar permissões.

Adicionar a aplicação personalizada à lista de clientes permitidos

Depois de registares a aplicação Entra, adiciona o ID do cliente à lista de clientes MCP permitidos para o teu ambiente.

1. Aceda ao Centro de administração da Power Platform. Selecione Gerenciar>ambientes.
2. Seleciona o ambiente onde queres permitir o cliente e depois seleciona Definições.
3. Em Configurações, selecione Funcionalidades> do Produto. Desça para localizar o Protocolo de Contexto do Modelo Dataverse e selecione Definições Avançadas.
4. Adicione uma nova entrada de cliente. Introduza um nome para o cliente e especifique o ID da Aplicação (cliente) no registo da sua aplicação Entra.
5. Defina Está Ativado para Sim.
6. Selecione Guardar e Fechar.

Liga-te ao endpoint remoto

Configure o seu cliente MCP para se ligar ao servidor MCP da Dataverse na seguinte URL:

https://<your org URL>/api/mcp

Por exemplo: https://contoso.crm.dynamics.com/api/mcp

Use o ID da Aplicação (cliente) do seu registo na aplicação Entra para autenticação. Consulte a documentação do seu cliente MCP para passos de configuração específicos.

Artigos relacionados

Conectar-se ao Dataverse com o Model Context Protocol