Condividi tramite

Connettersi a Dataverse con il protocollo del contesto modello nei clienti non Microsoft

È possibile connettersi a Microsoft Dataverse usando un client MCP (Model Context Protocol) non Microsoft, ad esempio Claude Desktop o Claude Code. Esistono due approcci per la connessione di client non Microsoft a un server MCP dataverse:

  • Proxy locale: usare il @microsoft/dataverse pacchetto npm per eseguire un proxy locale che si connette al server MCP Dataverse per conto dell'utente.
  • Endpoint remoto: connettersi direttamente all'endpoint remoto del server Dataverse MCP (/api/mcp) registrando un'app Microsoft Entra personalizzata.

Prerequisiti

Connettersi tramite il proxy locale

Il @microsoft/dataverse pacchetto npm fornisce un proxy locale che gestisce l'autenticazione e la comunicazione con il server MCP Dataverse. Questo approccio è consigliato per la maggior parte dei client MCP non Microsoft che possono eseguire server MCP locali.

Un amministratore tenant deve concedere il consenso dell'amministratore per l'app CLI di Dataverse prima che gli utenti possano eseguire l'autenticazione. Passare all'URL seguente in un browser, sostituendo {your-tenant-id} con l'ID tenant di Microsoft Entra:

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

Accedere con un account amministratore tenant e accettare il prompt delle autorizzazioni. Questo passaggio deve essere completato una sola volta per ogni tenant.

Abilitare il client CLI di Dataverse nel centro di amministrazione di Power Platform

Prima di potersi connettere tramite il proxy locale, il client dell'interfaccia della riga di comando di Dataverse deve essere abilitato come client MCP consentito nell'ambiente in uso.

  1. Vai a Interfaccia di amministrazione di Power Platform. Selezionare Gestisci>Ambienti.
  2. Selezionare l'ambiente in cui si vuole abilitare il client e quindi selezionare Impostazioni.
  3. In Impostazioni selezionare Funzionalità prodotto>. Scorrere verso il basso per individuare Dataverse Model Context Protocol e selezionare Impostazioni avanzate.
  4. Individuare il client della Dataverse CLI (ID app 0c412cc3-0dd6-449b-987f-05b053db9457) e impostare Abilitato su Sì.
  5. Selezionare Salva e chiudi.

Annotazioni

Se la voce CLI di Dataverse non appare nell'elenco dei client disponibili, si può aggiungerla manualmente. Crea una nuova voce client con qualsiasi nome e specifica l'ID app 0c412cc3-0dd6-449b-987f-05b053db9457, quindi abilitalo.

Installare il proxy locale

È possibile installare il @microsoft/dataverse pacchetto a livello globale o eseguirlo direttamente con npx.

Per eseguire l'installazione a livello globale, eseguire il comando seguente in un terminale:

npm install -g @microsoft/dataverse

In alternativa, è possibile usare npx per eseguire il proxy senza installarlo a livello globale:

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

Suggerimento

Per connettersi all'endpoint di anteprima () anziché all'endpoint disponibile a livello generale (/api/mcp_preview/api/mcp), aggiungere il --preview parametro al comando . Ad esempio: npx @microsoft/dataverse mcp https://yourorg.crm.dynamics.com --preview. L'endpoint di anteprima deve essere abilitato nell'ambiente in uso. Altre informazioni: Usare gli strumenti di anteprima e le funzionalità future nel server MCP dataverse

Configurare il proxy locale in Claude Desktop

Questa sezione descrive come configurare il proxy locale del server MCP dataverse in Claude desktop. Se non è già stato fatto, scaricare e installare Claude desktop.

  1. Apri Claude Desktop e passa a File>Impostazioni>Sviluppatore.

  2. Selezionare Modifica configurazione per aprire il claude_desktop_config.json file.

  3. Aggiungere il frammento JSON seguente al file. Sostituire <friendly name> con un nome che è possibile ricordare facilmente (ad esempio, MyDataverseMCPServer) e sostituire <your org URL> con l'URL dell'ambiente Dataverse (ad esempio, https://contoso.crm.dynamics.com).

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

  4. Salva il file.

Verificare la connessione in Claude Desktop

  1. Uscire da Claude desktop selezionando File>Uscita, e quindi riaprirlo per applicare le modifiche.
  2. Accedere con le credenziali quando viene richiesto di eseguire l'autenticazione nell'ambiente Dataverse.
  3. Selezionare Cerca e strumenti per verificare che il server McP Dataverse e i relativi strumenti siano disponibili. Verrà visualizzato il nome descrittivo configurato, ad esempio MyDataverseMCPServer.
  4. Selezionare il nome del server MCP per visualizzare l'elenco degli strumenti supportati dal server.

Suggerimento

È possibile abilitare e disabilitare singoli strumenti per ogni server MCP registrato con Claude desktop. In questo modo è possibile controllare quali strumenti sono disponibili per l'uso.

Configurare il proxy locale in Claude Code

Questa sezione descrive come configurare il proxy locale del server MCP Dataverse in Claude Code. Se non è già stato fatto, scaricare e installare Claude Code.

Eseguire il comando seguente per aggiungere il server MCP Dataverse. Sostituire https://yourorg.crm.dynamics.com con l'URL dell'ambiente Dataverse.

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

Verificare e interagire con la connessione in Claude Code

  1. Riavviare Claude Code per applicare le modifiche.
  2. Accedere con le credenziali quando viene richiesto di eseguire l'autenticazione nell'ambiente Dataverse.
  3. Verificare che il server MCP Dataverse e i relativi strumenti siano disponibili. Verrà visualizzato il nome descrittivo configurato, ad esempio MyDataverseMCPServer.
  4. Selezionare il nome del server MCP per visualizzare l'elenco degli strumenti supportati dal server.

Se si dispone di dati nell'ambiente Dataverse, è possibile testare la configurazione richiedendo elencare le tabelle in Dataverse, descrivere la tabella account o quanti account ho. Ulteriori informazioni: Aggiungere e rimuovere dati di esempio

Suggerimento

Se sono presenti altri server MCP registrati con Claude Code, includere Dataverse nel prompt per specificare il server MCP da usare.

Connettersi usando l'endpoint remoto

È possibile connettere i client mcp non Microsoft direttamente all'endpoint remoto del server MCP dataverse senza usare un proxy locale. Questo approccio richiede di registrare un'applicazione personalizzata in Microsoft Entra ID e di aggiungerne l'ID client all'elenco dei client consentiti nell'interfaccia di amministrazione di Power Platform.

Registrare un'app Microsoft Entra personalizzata

Registrare un'applicazione in Microsoft Entra ID da usare per l'autenticazione durante la connessione al server MCP dataverse. Per informazioni generali sulla registrazione delle app, vedere Registrare un'applicazione con Microsoft Identity Platform.

Seguire questa procedura per registrare un'app da usare con il server MCP Dataverse:

  1. Accedi all'interfaccia di amministrazione di Microsoft Entra.
  2. Passare a Identità>Applicazioni>Registrazioni delle app, e quindi selezionare Nuova registrazione.
  3. Immettere un nome per l'applicazione, ad esempio Dataverse MCP Client, configurare i tipi di account supportati per lo scenario e quindi selezionare Registra.
  4. Nella pagina Panoramica dell'app prendi nota del valore di ID applicazione (client). Questo valore è necessario per configurare il client consentito nell'interfaccia di amministrazione di Power Platform e per configurare il client MCP.

Configurare le autorizzazioni API per il server MCP dataverse

Dopo aver registrato l'app, è necessario concedere le autorizzazioni per accedere al server MCP dataverse.

  1. Nella registrazione dell'app selezionare Autorizzazioni API nel riquadro di spostamento a sinistra.
  2. Seleziona Aggiungi autorizzazione.
  3. Selezionare API Microsoft e quindi Dynamics CRM.
  4. Selezionare l'autorizzazione mcp.tools e quindi selezionare Aggiungi autorizzazioni.

Annotazioni

Il flusso di autenticazione usato dall'app Entra dipende dal client MCP in uso. Per i metodi di autenticazione supportati, vedere la documentazione del client MCP.

Aggiungere l'app personalizzata all'elenco dei client consentiti

Dopo aver registrato l'app Entra, aggiungere l'ID client all'elenco dei client MCP consentiti per l'ambiente.

  1. Vai a Interfaccia di amministrazione di Power Platform. Selezionare Gestisci>Ambienti.
  2. Selezionare l'ambiente in cui si vuole consentire il client e quindi selezionare Impostazioni.
  3. In Impostazioni selezionare Funzionalità prodotto>. Scorrere verso il basso per individuare Dataverse Model Context Protocol e selezionare Impostazioni avanzate.
  4. Aggiunta di una nuova voce client. Immetti un nome per il client e specifica l'ID applicazione (client) dalla registrazione dell'app Entra.
  5. Impostare è abilitato su Sì.
  6. Selezionare Salva e chiudi.

Connettersi all'endpoint remoto

Configurare il client MCP per connettersi al server MCP Dataverse all'URL seguente:

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

Ad esempio: https://contoso.crm.dynamics.com/api/mcp

Usare l'ID applicazione (client) della registrazione dell'app Entra per l'autenticazione. Per i passaggi di configurazione specifici, vedere la documentazione del client MCP.

Connettersi a Dataverse con il protocollo di contesto del modello

  • Last updated on