Agente dati come server del protocollo Model Context Protocol

Il protocollo MCP (Model Context Protocol) è uno standard emergente nel panorama dell'intelligenza artificiale che consente ai sistemi di intelligenza artificiale di connettersi con strumenti e dati all'esterno di se stessi. Definisce in che modo un modello di intelligenza artificiale può scoprire cosa è disponibile e interagire con esso in modo coerente. Invece di creare integrazioni una tantum, MCP offre un modo standard per collegare gli elementi che funzionano in app e servizi diversi. Questo approccio rende molto più semplice per i sistemi di intelligenza artificiale andare oltre le proprie conoscenze predefinite mantenendo al tempo stesso le cose coerenti. Aiuta anche i team a spostarsi più velocemente, poiché non devono reinventare le stesse connessioni ogni volta.

MCP ha due parti principali: il client e il server.

Un client MCP è l'app o l'esperienza con cui l'utente interagisce. È qui che si pongono domande o si attivano azioni. Il client raggiunge i server MCP per trovare gli strumenti e usarli. Ad esempio, Visual Studio Code può fungere da client MCP quando si connette a strumenti esterni per recuperare i dati oppure consente di scrivere ed eseguire codice.

Un server MCP espone strumenti, dati o servizi in modo che i client possano usarli. Indica al client cosa è disponibile e come usarlo. Ad esempio, un agente dati Fabric può fungere da server MCP esponendo i dati aziendali e le query che un sistema di intelligenza artificiale può usare.

Insieme, il client e il server semplificano la connessione dei sistemi di intelligenza artificiale con dati e azioni reali, senza creare integrazioni personalizzate ogni volta.

Prerequisiti

• Una capacità di Fabric a pagamento di livello F2 o superiore, o una capacità Power BI Premium per capacità (P1 o superiore) con Microsoft Fabric abilitato.
• Elaborazione e archiviazione tra aree geografiche per l'IA abilitate, in base ai requisiti definiti nelle impostazioni del tenant di Fabric Data Agent.
• Almeno un'origine dati che contenga dati: un warehouse, una lakehouse, un modello semantico Power BI, un database KQL, un database con mirroring o un'ontologia. È necessario disporre dell'accesso in lettura all'origine dati.
• Un agente di dati pubblicato. Il server MCP funziona solo dopo che pubblichi l'agente dati. Per altre informazioni, vedere Creare un agente dati di Fabric.

Come funziona

Quando pubblichi un data agent Fabric, questo diventa un server MCP che espone un singolo strumento MCP. Tale strumento rappresenta l'agente dati stesso, quindi un client MCP invia una domanda allo strumento e restituisce una risposta che viene messa a punto nei dati a cui l'agente dati ha accesso in Fabric OneLake.

Poiché il client decide quando chiamare lo strumento, la descrizione dell'agente dati è importante. Quando si pubblica un agente dati, la relativa descrizione diventa la descrizione dello strumento annunciata dal server MCP. Clienti e organizzatori leggono quella descrizione per decidere quando e come chiamare l'agente dei dati, quindi scrivano una descrizione chiara, dettagliata e specifica che spieghi ciò che l'agente sa e i tipi di domande a cui può rispondere.

Puoi utilizzare il server MCP del data agent da qualsiasi client MCP, non solo da uno strumento o editor specifici. Finché il tuo client supporta MCP su HTTP streamable e può autenticarsi con Fabric e allegare un token Fabric valido alle sue richieste, può connettersi al server. Le sezioni seguenti mostrano due client: uno script Python e Visual Studio Code. Puoi usare lo stesso approccio endpoint e autenticazione con qualsiasi altro client MCP che costruisci o adotti.

Tutto ciò che comunica con il server MCP deve parlare MCP, quindi per definizione funge da client MCP. Il termine "client MCP" non significa un prodotto o un SDK specifico. Significa qualsiasi codice che segue il protocollo. L'endpoint non è una semplice API REST a cui è possibile inviare una richiesta arbitraria. Una connessione segue il flusso del messaggio MCP: un initialize handshake, una tools/list chiamata per individuare lo strumento e una tools/call richiesta di porre una domanda. Un SDK come MCP Python SDK gestisce automaticamente tale flusso, ma è anche possibile implementarlo tramite HTTP normale, purché le richieste seguano il protocollo. Un client HTTP generico che ignora l'handshake e il formato del messaggio non funzioneranno.

Ottenere i dettagli del server MCP

Dopo aver pubblicato l'agente dati, aprire le impostazioni e passare alla scheda Protocollo contesto modello . Questa scheda mostra:

• Nome del server MCP dell'agente dati
• URL del server MCP (copiare questo valore; usarlo in ogni client)
• Nome dello strumento MCP dell'agente dati
• Descrizione dello strumento server MCP

È anche possibile scaricare il file mcp.json da questa scheda per configurare i client che leggono tale formato, ad esempio Visual Studio Code.

Puoi anche costruire tu stesso l'URL a partire dall'ID dell'area di lavoro e dall'ID dell'agente dati:

https://api.fabric.microsoft.com/v1/mcp/workspaces/{WorkspaceId}/dataagents/{DataAgentId}/agent

Un URL compilato manualmente funziona solo dopo la pubblicazione dell'agente dati. Se l'agente non viene pubblicato, l'endpoint restituisce un errore anche quando l'URL è corretto.

Authentication

Ogni richiesta all'endpoint MCP deve essere autenticata in Fabric. Il client allega un token bearer nell'intestazione Authorization e il token deve disporre delle autorizzazioni necessarie per accedere allo spazio di lavoro di destinazione e all'agente dati. Il token può rappresentare un'identità utente o un'entità servizio.

Il modo in cui si ottiene il token dipende dal client. Visual Studio Code chiede di eseguire l'accesso in modo interattivo. In uno script Python si acquisisce il token tramite una libreria, azure-identity ad esempio e lo si aggiunge alle intestazioni della richiesta manualmente. Qualunque sia il client, richiedi il token per l'ambito https://api.fabric.microsoft.com/.default.

Richieste di lunga durata e compiti MCP

Alcune domande richiedono più tempo per essere risposte di altre. Una domanda che scansiona una tabella grande o esegue più query può richiedere più tempo di quanto un client o un intermediario di rete mantenga una connessione aperta. In questi casi, il server MCP dell'agente dati supporta le attività.

Un compito permette al server di rispondere senza tenere aperta la connessione. Quando l'agente dati inizia a lavorare su una domanda, restituisce un identificatore per quell'opera invece della risposta. Il tuo cliente usa l'identificatore per chiedere il risultato quando è pronto. Se la connessione si interrompe o il client si riavvia, il client mantiene l'identificatore e riprende da dove aveva lasciato.

I compiti seguono l'estensione io.modelcontextprotocol/tasks prevista nella specifica MCP. Il tuo cliente chiede il risultato con tasks/get e continua a chiedere finché il compito non segnala che il lavoro è finito. Per fermare un lavoro che non è più necessario, il tuo cliente invia tasks/cancel. L'annullamento non è istantaneo, quindi un'attività può risultare ancora in esecuzione per un breve periodo dopo che ne hai richiesto l'annullamento e un'operazione quasi completata può comunque essere portata a termine.

I client che supportano l'estensione delle attività ricevono un compito. Per ogni altro cliente, nulla cambia. L'agente dati risponde tramite la stessa connessione, come mostrato altrove in questo articolo.

Per il formato del messaggio e l'intero ciclo di vita del compito, vedi l'estensione MCP delle attività.

Connettersi da Python

Questo esempio si connette all'endpoint MCP dell'agente dati da uno script di Python autonomo, individua lo strumento, invia una domanda e stampa la risposta. Usa MCP Python SDK e la azure-identity libreria.

Prerequisiti per il client Python

• Python 3.10 o versione successiva.
• Pacchetti mcp e azure-identity.
• Un modo per accedere a Fabric. In questo esempio viene utilizzata la interfaccia della riga di comando di Azure. Installare il interfaccia della riga di comando di Azure, quindi eseguire az login e accedere con un account che abbia accesso all'area di lavoro e all'agente dati.

Installare i pacchetti:

pip install mcp azure-identity

Compilare il client passo dopo passo

Le sezioni seguenti compilano lo script un pezzo alla volta. Ogni blocco continua lo stesso file, in modo da poterlo incollare in un singolo .py file ed eseguirlo.

Importare le librerie e impostare i valori. Sostituire l'ID dell'area di lavoro, l'ID dell'agente dati e la domanda con i propri valori. mcp_url segue il formato dell'endpoint descritto in precedenza.

import asyncio

from azure.identity import AzureCliCredential
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

workspace_id = "<your-workspace-id>"
data_agent_id = "<your-data-agent-id>"
question = "<your question>"

mcp_url = (
    f"https://api.fabric.microsoft.com/v1/mcp/workspaces/{workspace_id}"
    f"/dataagents/{data_agent_id}/agent"
)

Acquisire un token e compilare l'intestazione di autenticazione. AzureCliCredential utilizza lo stesso accesso di az login. Il componente helper richiede un token per l'ambito Fabric e lo restituisce sotto forma di intestazione Authorization, inclusa in ogni richiesta.

credential = AzureCliCredential()


def get_auth_headers():
    token = credential.get_token("https://api.fabric.microsoft.com/.default")
    return {"Authorization": f"Bearer {token.token}"}

Aprire la connessione, individuare lo strumento e porre la domanda. Questa funzione apre una connessione HTTP per lo streaming con l'header di autorizzazione, esegue l'handshake MCP con initialize, elenca i tool e legge l'unico tool che l'agente dati espone. Individua il nome dell'argomento della domanda dallo schema di input dello strumento, così non devi codificarlo esplicitamente, quindi chiama lo strumento e raccoglie il testo dalla risposta.

async def query_data_agent(question):
    headers = get_auth_headers()

    async with streamablehttp_client(mcp_url, headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # The data agent exposes a single tool. Discover it, then call it.
            tools = await session.list_tools()
            tool = tools.tools[0]
            question_arg = next(iter(tool.inputSchema["properties"]))

            result = await session.call_tool(tool.name, {question_arg: question})

            answers = [block.text for block in result.content if block.type == "text"]
            return "\n".join(answers)

Eseguilo e stampa il risultato. query_data_agent è una coroutine, quindi asyncio.run lo spinge al completamento e restituisce il risultato.

answer = asyncio.run(query_data_agent(question))
print(answer)

Poiché lo script legge il primo strumento che il server annuncia e trova l'argomento della domanda dallo schema di input dello strumento, continua a funzionare anche se il nome dello strumento o il nome dell'argomento cambia. Non è necessario codificare in modo statico nessuno dei due valori.

Connettersi da Visual Studio Code

Visual Studio Code può fungere da client MCP. I passaggi seguenti aggiungono il server MCP del data agent e consentono di fare domande dall'editor. Questi passaggi sono un esempio; l'endpoint e il token sono gli stessi usati da qualsiasi altro client MCP.

Aggiungere il server MCP

1. Aprire Visual Studio Code e selezionare una cartella in cui lavorare.

2. Creare una cartella vscode nella cartella selezionata.

3. All'interno di .vscode creare un file denominato mcp.json.

4. Visual Studio Code mostra un pulsante blu Aggiungi server in basso a destra della finestra.

   

5. Selezionare Aggiungi server e quindi HTTP. Quando viene richiesto un URL, incollare l'URL del server MCP copiato in precedenza.

   

   

6. Premere INVIO e specificare un nome per il server. Visual Studio Code usa questo nome per visualizzare il server.

7. Visual Studio Code tenta di eseguire l'autenticazione. Selezionare Consenti e accedi con le credenziali.

Il server viene creato.

Abilitare la modalità agente

Dopo aver aggiunto il server, attiva la modalità agente in modo che Visual Studio Code possa indirizzare le tue domande all'agente dati:

1. Aprire il riquadro comandi (CTRL+MAIUSC+P o CMD+MAIUSC+P).

2. Cercare Abilita modalità agente e selezionarlo.

3. Confermare le richieste di attivazione della modalità.

   

Quando la modalità agente è attiva, selezionare un agente di orchestrazione per gestire le domande. L'orchestratore gestisce il flusso tra le tue domande nell'editor e il server MCP dell'agente dati. Gli orchestratori disponibili includono GPT-5, GPT-4.1, Claude Sonnet 4.5, Gemini 2.5 Pro e altri.

Domande

Con la modalità agente attivata e un orchestratore selezionato, fai domande direttamente dall'editor. L'orchestratore instrada ogni domanda al server MCP dell'agente dati e l'agente restituisce una risposta basata sui dati a cui ha accesso in OneLake. Si rimane nell'editor mentre si apportano conoscenze organizzative ai flussi di lavoro di intelligenza artificiale.

Contenuti correlati

• Creare un agente dei dati di Fabric
• SDK Python dell'agente dati di Fabric
• Impostazioni del tenant dell'agente di dati Fabric