Strumenti MCP per database: rendere disponibili i set di dati BigQuery ai client MCP

1. Introduzione

In questo codelab utilizzerai la cassetta degli attrezzi MCP per i database per rendere disponibili i tuoi set di dati BigQuery.

Nel codelab, utilizzerai un approccio passo passo come segue:

1. Identifica un set di dati BigQuery specifico ("Note di rilascio di Google Cloud") dal programma per i set di dati BigQuery pubblici.
2. Configura MCP Toolbox per i database, che si connette al set di dati BigQuery.
3. Esplora vari client MCP e verifica che siano in grado di accedere all'interfaccia MCP del set di dati BigQuery.

Attività previste

• Configura MCP Toolbox for Databases in modo da esporre le note di rilascio di Google Cloud, un set di dati BigQuery pubblico, come interfaccia MCP per altri client MCP (IDE, strumenti e così via).

Cosa imparerai a fare

• Esplora i set di dati pubblici BigQuery e scegli un set di dati specifico.
• Configura Toolbox MCP per i database per il set di dati pubblico BigQuery che vogliamo rendere disponibile per i client MCP.
• Testa la configurazione della cassetta degli attrezzi MCP per i database nell'ambiente locale.

Che cosa ti serve

• Browser web Chrome.
• Un ambiente di sviluppo Python locale.
• Un ambiente Node.js locale con npm 5.2.0 o versioni successive.

2. Prima di iniziare

Crea un progetto

1. Nella console Google Cloud, nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud.
2. Verifica che la fatturazione sia attivata per il tuo progetto Cloud. Scopri come verificare se la fatturazione è attivata in un progetto .
3. Utilizzerai Cloud Shell, un ambiente a riga di comando in esecuzione in Google Cloud precaricato con bq. Fai clic su Attiva Cloud Shell nella parte superiore della console Google Cloud.

4. Una volta connesso a Cloud Shell, verifica di aver già eseguito l'autenticazione e che il progetto sia impostato sul tuo ID progetto utilizzando il seguente comando:

gcloud auth list

5. Esegui il seguente comando in Cloud Shell per verificare che il comando gcloud conosca il tuo progetto.

gcloud config list project

6. Se il progetto non è impostato, utilizza il seguente comando per impostarlo:

gcloud config set project <YOUR_PROJECT_ID>

Consulta la documentazione per i comandi e l'utilizzo di gcloud.

3. Set di dati delle note di rilascio di Google e clienti MCP

Innanzitutto, diamo un'occhiata alle note di rilascio di Google Cloud, che vengono aggiornate regolarmente nella pagina web ufficiale delle note di rilascio di Google Cloud, di cui è riportato uno screenshot di seguito:

Potresti iscriverti all'URL del feed, ma che ne dici se potremmo semplicemente chiedere nella chat con l'agente di queste note di rilascio? Ad esempio, una semplice query come "Aggiornami sulle note di rilascio di Google Cloud".

Ecco lo screenshot del mio Visual Studio Code in cui è in esecuzione CoPilot e sono in modalità agente, mentre chiedo informazioni sulle note di rilascio di Google Cloud:

Vediamo come procedere e, nel frattempo, scopriamo come esporre i set di dati BigQuery in vari client MCP a tua scelta.

4. MCP Toolbox for Databases

MCP Toolbox for Databases è un server MCP open source per i database. È stato progettato per garantire qualità di produzione e di livello enterprise. Ti consente di sviluppare strumenti in modo più semplice, rapido e sicuro gestendo complessità come il pooling delle connessioni, l'autenticazione e altro ancora.

Toolbox ti aiuta a creare strumenti di IA generativa che consentono ai tuoi agenti di accedere ai dati nel tuo database. Toolbox fornisce:

• Sviluppo semplificato: integra gli strumenti nell'agente in meno di 10 righe di codice, riutilizza gli strumenti tra più agenti o framework ed esegui più facilmente il deployment di nuove versioni degli strumenti.
• Miglioramento delle prestazioni: best practice come il pooling delle connessioni, l'autenticazione e altro ancora.
• Maggiore sicurezza: autenticazione integrata per un accesso più sicuro ai dati
• Osservabilità end-to-end: metriche e monitoraggio immediati con il supporto integrato di OpenTelemetry.
• Toolbox semplifica la connessione dei database a qualsiasi assistente AI compatibile con MCP, anche quelli presenti nel tuo IDE.

Toolbox si trova tra il framework di orchestrazione dell'applicazione e il database e fornisce un piano di controllo utilizzato per modificare, distribuire o richiamare gli strumenti. Semplifica la gestione degli strumenti fornendoti un luogo centralizzato per archiviarli e aggiornarli, consentendoti di condividerli tra agenti e applicazioni e di aggiornarli senza necessariamente eseguire nuovamente il deployment dell'applicazione.

Per riassumere in parole semplici:

1. MCP Toolbox è disponibile come immagine container binaria o puoi crearla dal codice sorgente.
2. Mette a disposizione un insieme di strumenti che puoi configurare tramite un file tools.yaml. Gli strumenti possono essere considerati come connessi alle tue origini dati. Puoi vedere le varie origini dati supportate : AlloyDB, BigQuery e così via.
3. Poiché questa cassetta degli attrezzi ora supporta MCP, hai automaticamente un endpoint del server MCP che può essere utilizzato dagli agenti (IDE) oppure puoi utilizzarlo durante lo sviluppo delle applicazioni agente utilizzando vari framework come Agent Development Kit (ADK).

In questo post del blog ci concentreremo sulle aree evidenziate di seguito:

In sintesi, creeremo una configurazione nella Toolbox MCP per i database che sappia connettersi al nostro set di dati BigQuery. Utilizzeremo quindi un IDE o qualsiasi altro IDE agente (client MCP) che comunicherà con l'endpoint MCP Toolbox e ci consentirà di inviare query in linguaggio naturale per chiedere informazioni sul nostro set di dati. Pensalo come uno strumento che stai configurando, che sa come comunicare con il tuo set di dati BigQuery ed esegue alcune query.

5. Set di dati BigQuery per le note di rilascio di Google Cloud

Il programma per i set di dati pubblici di Google Cloud è un programma che mette a disposizione una serie di set di dati per le tue applicazioni. Uno di questi set di dati è il database delle note di rilascio di Google Cloud. Questo set di dati fornisce le stesse informazioni della pagina web ufficiale delle note di rilascio di Google Cloud ed è disponibile come set di dati interrogabile pubblicamente.

Come test, convalido semplicemente il set di dati eseguendo una semplice query mostrata di seguito:

SELECT
       product_name,description,published_at
     FROM
       `bigquery-public-data`.`google_cloud_release_notes`.`release_notes`
     WHERE
       DATE(published_at) >= DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY)
     GROUP BY product_name,description,published_at
     ORDER BY published_at DESC

Viene visualizzato un elenco di record del set di dati delle note di rilascio pubblicati negli ultimi 7 giorni.

Sostituiscilo con qualsiasi altro set di dati a tua scelta e con le rispettive query e i parametri che preferisci. Ora non ci resta che configurarlo come origine dati e strumento in MCP Toolbox for Databases. Vediamo come si fa.

6. Installazione di MCP Toolbox for Databases

Apri un terminale sulla tua macchina locale e crea una cartella denominata mcp-toolbox.

mkdir mcp-toolbox

Vai alla cartella mcp-toolbox tramite il comando mostrato di seguito:

cd mcp-toolbox

Installa la versione binaria di MCP Toolbox for Databases tramite lo script riportato di seguito. Il comando riportato di seguito è per Linux, ma se utilizzi Mac o Windows, assicurati di scaricare il file binario corretto. Consulta la pagina delle release per il tuo sistema operativo e la tua architettura e scarica il file binario corretto.

export VERSION=0.6.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

Ora abbiamo la versione binaria della cassetta degli attrezzi pronta per l'uso. Il passaggio successivo consiste nel configurare la cassetta degli attrezzi con le nostre origini dati e altre configurazioni.

7. Configurazione della cassetta degli attrezzi MCP per i database

Ora dobbiamo definire il set di dati e gli strumenti BigQuery nel file tools.yaml necessario per la cassetta degli attrezzi MCP per il database. Il file tools.yaml è il modo principale per configurare Toolbox.

Crea un file denominato tools.yaml nella stessa cartella, ovvero mcp-toolbox, i cui contenuti sono riportati di seguito.

Puoi utilizzare l'editor nano disponibile in Cloud Shell. Il comando nano è il seguente: "nano tools.yaml".

Ricorda di sostituire il valore YOUR_PROJECT_ID con il tuo ID progetto Google Cloud.

sources:
 my-bq-source:
   kind: bigquery
   project: YOUR_PROJECT_ID

tools:
 search_release_notes_bq:
   kind: bigquery-sql
   source: my-bq-source
   statement: |
    SELECT
     product_name,description,published_at
    FROM
      `bigquery-public-data`.`google_cloud_release_notes`.`release_notes`
    WHERE
     DATE(published_at) >= DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY)
    GROUP BY product_name,description,published_at
    ORDER BY published_at DESC
   description: |
    Use this tool to get information on Google Cloud Release Notes.

toolsets:
 my_bq_toolset:
   - search_release_notes_bq

Ecco una breve descrizione del file:

1. Le origini rappresentano le diverse origini dati con cui uno strumento può interagire. Un'origine rappresenta un'origine dati con cui uno strumento può interagire. Puoi definire Origini come mappa nella sezione sources del file tools.yaml. In genere, una configurazione dell'origine contiene tutte le informazioni necessarie per connettersi al database e interagire con esso. Nel nostro caso, abbiamo definito un'origine BigQuery my-bq-source e devi fornire l'ID progetto Google Cloud. Per ulteriori informazioni, consulta la sezione di riferimento Origini.
2. Gli strumenti definiscono le azioni che un agente può intraprendere, ad esempio la lettura e la scrittura in un'origine. Uno strumento rappresenta un'azione che l'agente può intraprendere, ad esempio l'esecuzione di un'istruzione SQL. Puoi definire Strumenti come una mappa nella sezione Strumenti del file tools.yaml. In genere, uno strumento richiede un'origine su cui intervenire. Nel nostro caso, definiamo un singolo strumento search_release_notes_bq. Fa riferimento all'origine BigQuery my-bq-source che abbiamo definito nel primo passaggio. Contiene anche l'istruzione e l'istruzione che verranno utilizzate dai client dell'agente AI. Per ulteriori informazioni, consulta la sezione di riferimento Strumenti.
3. Infine, abbiamo il set di strumenti, che ti consente di definire gruppi di strumenti che vuoi poter caricare insieme. Questo può essere utile per definire gruppi diversi in base all'agente o all'applicazione. Nel nostro caso, abbiamo una definizione di set di strumenti in cui abbiamo definito solo uno strumento esistente search_release_notes_bq. Puoi avere più di un set di strumenti, che include una combinazione di strumenti diversi.

Al momento abbiamo definito un solo strumento che recupera le note di rilascio degli ultimi 7 giorni in base alla query. Tuttavia, puoi avere anche varie combinazioni con i parametri.

Consulta altri dettagli sulla configurazione ( Origine, Strumenti) nella configurazione dell'origine dati BigQuery in MCP Toolbox for Databases.

8. Test della cassetta degli attrezzi MCP per i database

Abbiamo scaricato e configurato Toolbox con il file tools.yaml nella cartella mcp-toolbox. Eseguiamolo prima localmente.

Esegui questo comando:

$ ./toolbox --tools-file="tools.yaml" --port 7000

Il server MCP Toolbox viene eseguito per impostazione predefinita sulla porta 5000, ma in questo caso abbiamo specificato che deve essere eseguito sulla porta 7000.

In caso di esecuzione corretta, dovresti vedere l'avvio del server con un output di esempio simile a quello riportato di seguito:

2025-04-25T16:05:45.603871+05:30 INFO "Initialized 1 sources."
2025-04-25T16:05:45.603943+05:30 INFO "Initialized 0 authServices."
2025-04-25T16:05:45.604092+05:30 INFO "Initialized 1 tools."
2025-04-25T16:05:45.604105+05:30 INFO "Initialized 2 toolsets."
2025-04-25T16:05:45.604706+05:30 INFO "Server ready to serve!"

Basta avviare il browser e visitare il seguente URL:

http://127.0.0.1:7000

Dovresti visualizzare il seguente output:

Nell'URL del browser, aggiungi quanto segue alla fine dell'URL:

http://127.0.0.1:7000/api/toolset

Dovresti visualizzare gli strumenti attualmente configurati. Di seguito è riportato un output di esempio:

Il server MCP, come indicato nella documentazione, è ora disponibile all'URL seguente:

http://127.0.0.1:7000/mcp/sse

L'output è mostrato di seguito:

event: endpoint
data: https://<some-url-pattern>/mcp?sessionId=bf6bfb66-36fe-48a4-8340-ac68008ee873

Nella sezione successiva testeremo il nostro server MCP con i client MCP.

9. Test del server MCP con vari client MCP

Proviamo il nostro server MCP appena creato con un paio di client MCP.

MCP Inspector con Toolbox

Il primo strumento da utilizzare è MCP Inspector con Toolbox. Per farlo, devi avere installato npx. Cloud Shell ti chiederà di installare il pacchetto. Procedi e installalo.

Devi dare il seguente comando:

npx @modelcontextprotocol/inspector

Il server verrà avviato e dovresti visualizzare un output simile al seguente:

Starting MCP inspector...
⚙️ Proxy server listening on port 6277
🔍 MCP Inspector is up and running at http://127.0.0.1:6274 🚀

Visita la pagina di MCP Inspector come indicato e la prima cosa da fare è configurare questo client per comunicare con il server MCP.

Seleziona il tipo di trasporto come SSE e fornisci il valore URL come indicato in precedenza, ad esempio http://127.0.0.1:7000/mcp/sse. Fai clic su Connect. Se tutto va bene, dovresti vedere lo stato Connesso, come mostrato di seguito:

Sul lato destro, ora puoi visualizzare l'elenco degli strumenti facendo clic su List Tools.

Poi fai clic sullo strumento search_release_notes_bq e, poiché non abbiamo parametri da passare, fai clic sul pulsante Run tool. Dovresti vedere che viene richiamata la cassetta degli attrezzi, che a sua volta si connette all'origine dati BigQuery e recupera i dati come mostrato di seguito:

VS Code in modalità agente con CoPilot

La documentazione ufficiale illustra i passaggi per connettersi a Toolbox per varie origini dati e IDE qui.

In questa sezione vedremo come configurare e utilizzare i server MCP in VS Code. Tieni presente che è disponibile in Anteprima e che la documentazione ufficiale è completa e disponibile qui.

Supponendo che tu abbia avviato VS Code, avvia Command Palette ed esegui il seguente comando:

Poi, seleziona HTTP sse perché abbiamo l'URL SSE.

Ti verrà chiesto il SSE endpoint, che forniremo allo stesso modo:

Successivamente, ti verranno confermati alcuni altri dettagli. Ho scelto di aggiungerlo alle mie impostazioni utente, quindi si aprirà il file settings.json, in cui posso vedere la configurazione:

Basta fare clic su Start che vedo sopra o posso farlo anche tramite il comando Tavolozza.

Puoi vedere che lo stato diventa Running.

Ora possiamo avviare la modalità di Chat di CoPilot e, in modalità Agent, inviare #search_release_notes_bq per indicare che vogliamo utilizzare lo strumento e poi un testo di query di esempio, come mostrato di seguito:

10. Complimenti

Congratulazioni, hai configurato correttamente Toolbox MCP per i database e un set di dati BigQuery per l'accesso all'interno dei client MCP.

Documentazione di riferimento

• MCP Toolbox per i database
• Set di dati pubblici di BigQuery