Toolbox MCP per i database: rendere disponibili i set di dati BigQuery per i clienti MCP
Informazioni su questo codelab
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:
- Identifica un set di dati BigQuery specifico ("Note di rilascio di Google Cloud") dal programma per i set di dati BigQuery pubblici.
- Configura MCP Toolbox per i database, che si connette al set di dati BigQuery.
- Sviluppare un agente utilizzando l'Agent Development Kit (ADK) che utilizzerà la cassetta degli attrezzi MCP per rispondere alle query dell'utente sulle note di rilascio di Google Cloud
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.
- Progetta e sviluppa un agente utilizzando l'Agent Development Kit (ADK) per rispondere alle query degli utenti.
- Testa la cassetta degli attrezzi dell'agente e dell'MCP per i database nell'ambiente locale.
Che cosa ti serve
- Browser web Chrome.
- Un ambiente di sviluppo Python locale.
2. Prima di iniziare
Crea un progetto
- Nella console Google Cloud, nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud.
- Verifica che la fatturazione sia attivata per il tuo progetto Cloud. Scopri come verificare se la fatturazione è attivata in un progetto .
- 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.
- 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
- Esegui il seguente comando in Cloud Shell per verificare che il comando gcloud conosca il tuo progetto.
gcloud config list project
- 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 chiedessimo semplicemente nella chat con l'agente di queste note di rilascio? Ad esempio, una semplice query come "Aggiornami sulle note di rilascio di Google Cloud".
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:
- MCP Toolbox è disponibile come immagine container binaria o puoi crearla dal codice sorgente.
- 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.
- 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. Svilupperemo quindi un agente utilizzando l'Agent Development Kit (ADK) che si integrerà con l'endpoint Toolbox MCP e ci consentirà di inviare query naturali per chiedere informazioni sul nostro set di dati. Pensala come un'applicazione agente che stai sviluppando e che sa come comunicare con il tuo set di dati BigQuery ed eseguire 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.7.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:
- 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-sourcee devi fornire l'ID progetto Google Cloud. Per ulteriori informazioni, consulta la sezione di riferimento Origini. - 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 BigQuerymy-bq-sourceche 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. - 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"
In caso di esecuzione corretta, dovresti vedere l'avvio del server con un output di esempio simile a quello riportato di seguito:
2025-06-17T07:48:52.989710733Z INFO "Initialized 1 sources."
2025-06-17T07:48:52.989805642Z INFO "Initialized 0 authServices."
2025-06-17T07:48:52.989847035Z INFO "Initialized 1 tools."
2025-06-17T07:48:52.989889742Z INFO "Initialized 2 toolsets."
2025-06-17T07:48:52.990357879Z INFO "Server ready to serve!"
Per impostazione predefinita, il server MCP Toolbox viene eseguito sulla porta 5000. Se la porta 5000 è già in uso, non esitare a utilizzare un'altra porta (ad esempio 7000) come indicato nel comando di seguito. Utilizza 7000 anziché la porta 5000 nei comandi successivi.
./toolbox --tools-file "tools.yaml" --port 7000
Utilizziamo Cloud Shell per testarlo.
Fai clic su Anteprima web in Cloud Shell come mostrato di seguito:
Fai clic su Cambia porta e imposta la porta su 5000 come mostrato di seguito, poi fai clic su Cambia e visualizza anteprima.
Dovresti visualizzare il seguente output:
Nell'URL del browser, aggiungi quanto segue alla fine dell'URL:
/api/toolset
Dovresti visualizzare gli strumenti attualmente configurati. Di seguito è riportato un output di esempio:
{
"serverVersion": "0.7.0+binary.linux.amd64.714d990c34ee990e268fac1aa6b89c4883ae5023",
"tools": {
"search_release_notes_bq": {
"description": "Use this tool to get information on Google Cloud Release Notes.\n",
"parameters": [],
"authRequired": []
}
}
}
MCP Toolkit for Databases descrive un modo in Python per convalidare e testare gli strumenti, la cui documentazione è disponibile qui. Salteremo questo passaggio e passeremo direttamente all'Agent Development Kit (ADK) nella sezione successiva, che utilizzerà questi strumenti.
9. Scrittura del nostro agente con Agent Development Kit (ADK)
Installa l'Agent Development Kit (ADK)
Apri una nuova scheda del terminale in Cloud Shell e crea una cartella denominata my-agents come segue. Vai anche alla cartella my-agents.
mkdir my-agents
cd my-agents
Ora crea un ambiente Python virtuale utilizzando venv come segue:
python -m venv .venv
Attiva l'ambiente virtuale come segue:
source .venv/bin/activate
Installa i pacchetti ADK e MCP Toolbox for Databases insieme alla dipendenza langchain come segue:
pip install google-adk toolbox-core
Ora potrai richiamare l'utilità adk nel seguente modo.
adk
Verrà visualizzato un elenco di comandi.
$ adk
Usage: adk [OPTIONS] COMMAND [ARGS]...
Agent Development Kit CLI tools.
Options:
--help Show this message and exit.
Commands:
api_server Starts a FastAPI server for agents.
create Creates a new app in the current folder with prepopulated agent template.
deploy Deploys agent to hosted environments.
eval Evaluates an agent given the eval sets.
run Runs an interactive CLI for a certain agent.
web Starts a FastAPI server with Web UI for agents.
Creazione della prima applicazione agente
Ora utilizzeremo adk per creare uno scheletro per l'applicazione dell'agente di Google Cloud Release Notes tramite il comando adk create con un nome dell'app **(gcp-releasenotes-agent-app)**come indicato di seguito.
adk create gcp-releasenotes-agent-app
Segui i passaggi e seleziona quanto segue:
- Modello Gemini per la scelta di un modello per l'agente principale.
- Scegli Vertex AI per il backend.
- Verranno visualizzati l'ID progetto Google e la regione predefiniti. Seleziona il valore predefinito.
Choose a model for the root agent:
1. gemini-2.0-flash-001
2. Other models (fill later)
Choose model (1, 2): 1
1. Google AI
2. Vertex AI
Choose a backend (1, 2): 2
You need an existing Google Cloud account and project, check out this link for details:
https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-cloud-vertex-ai
Enter Google Cloud project ID [YOUR_GOOGLE_PROJECT_ID]:
Enter Google Cloud region [us-central1]:
Agent created in ../my-agents/gcp-releasenotes-agent-app:
- .env
- __init__.py
- agent.py
Controlla la cartella in cui sono stati creati un modello predefinito e i file richiesti per l'agente.
Innanzitutto, il file .env. I cui contenuti sono riportati di seguito:
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_GOOGLE_PROJECT_REGION
I valori indicano che utilizzeremo Gemini tramite Vertex AI, insieme ai rispettivi valori per l'ID progetto e la posizione di Google Cloud.
Poi abbiamo il file __init__.py che contrassegna la cartella come modulo e contiene un'unica istruzione che importa l'agente dal file agent.py.
from . import agent
Infine, diamo un'occhiata al file agent.py. I contenuti sono riportati di seguito:
from google.adk.agents import Agent
root_agent = Agent(
model='gemini-2.0-flash-001',
name='root_agent',
description='A helpful assistant for user questions.',
instruction='Answer user questions to the best of your knowledge',
)
Si tratta dell'agente più semplice che puoi scrivere con ADK. Nella pagina della documentazione ADK, un agente è un'unità di esecuzione autosufficiente progettata per agire in modo autonomo al fine di raggiungere obiettivi specifici. Gli agenti possono eseguire attività, interagire con gli utenti, utilizzare strumenti esterni e coordinarsi con altri agenti.
Nello specifico, un LLMAgent, comunemente noto come Agent, utilizza i modelli linguistici di grandi dimensioni (LLM) come motore principale per comprendere il linguaggio naturale, ragionare, pianificare, generare risposte e decidere dinamicamente come procedere o quali strumenti utilizzare, il che lo rende ideale per attività flessibili incentrate sul linguaggio. Scopri di più sugli agenti LLM qui.
La struttura per generare un agente di base utilizzando l'Agent Development Kit (ADK) è completata. Ora collegheremo il nostro agente alla cassetta degli attrezzi MCP, in modo che possa utilizzare questo strumento per rispondere alle query dell'utente (in questo caso, le note di rilascio di Google Cloud).
10. Collegamento del nostro agente agli strumenti
Ora collegheremo questo agente agli strumenti. Nel contesto di ADK, uno strumento rappresenta una funzionalità specifica fornita a un agente AI, che gli consente di eseguire azioni e interagire con il mondo oltre le sue capacità di ragionamento e generazione di testo di base.
Nel nostro caso, ora doteremo il nostro agente degli strumenti che abbiamo configurato nella cassetta degli attrezzi MCP per i database.
Modifica il file agent.py con il seguente codice. Tieni presente che nel codice utilizziamo la porta predefinita 5000, ma se utilizzi un numero di porta alternativo, utilizzalo.
from google.adk.agents import Agent
from toolbox_core import ToolboxSyncClient
toolbox = ToolboxSyncClient("http://127.0.0.1:5000")
# Load all the tools
tools = toolbox.load_toolset('my_bq_toolset')
root_agent = Agent(
name="gcp_releasenotes_agent",
model="gemini-2.0-flash",
description=(
"Agent to answer questions about Google Cloud Release notes."
),
instruction=(
"You are a helpful agent who can answer user questions about the Google Cloud Release notes. Use the tools to answer the question"
),
tools=tools,
)
Ora possiamo testare l'agente che recupererà i dati reali dal nostro set di dati BigQuery configurato con la Toolbox MCP per i database.
Per farlo, segui questa sequenza:
In un terminale di Cloud Shell, avvia MCP Toolbox per i database. Potresti già averlo eseguito localmente sulla porta 5000, come abbiamo testato in precedenza. In caso contrario, esegui il seguente comando (dalla cartella mcp-toolbox) per avviare il server:
./toolbox --tools_file "tools.yaml"
Idealmente, dovresti vedere un output che indica che il server è stato in grado di connettersi alle nostre origini dati e ha caricato lo strumento e gli strumenti. Di seguito è riportato un output di esempio:
./toolbox --tools-file "tools.yaml"
2025-06-17T07:48:52.989710733Z INFO "Initialized 1 sources."
2025-06-17T07:48:52.989805642Z INFO "Initialized 0 authServices."
2025-06-17T07:48:52.989847035Z INFO "Initialized 1 tools."
2025-06-17T07:48:52.989889742Z INFO "Initialized 2 toolsets."
2025-06-17T07:48:52.990357879Z INFO "Server ready to serve!"
Una volta avviato correttamente il server MCP, in un altro terminale avvia l'agente tramite il comando adk run (dalla cartella my-agents) mostrato di seguito. Se vuoi, puoi anche utilizzare il comando adk web.
$ adk run gcp-releasenotes-agent-app/
Log setup complete: /tmp/agents_log/agent.20250423_170001.log
To access latest log: tail -F /tmp/agents_log/agent.latest.log
Running agent gcp_releasenotes_agent, type exit to exit.
[user]: get me the google cloud release notes
[gcp_releasenotes_agent]: Here are the Google Cloud Release Notes.
Google SecOps SOAR: Release 6.3.49 is being rolled out to the first phase of regions. This release contains internal and customer bug fixes. Published: 2025-06-14
Compute Engine: Dynamic NICs let you add or remove network interfaces to or from an instance without having to restart or recreate the instance. You can also use Dynamic NICs when you need more network interfaces. The maximum number of vNICs for most machine types in Google Cloud is 10; however, you can configure up to 16 total interfaces by using Dynamic NICs. Published: 2025-06-13
Compute Engine: General purpose C4D machine types, powered by the fifth generation AMD EPYC processors (Turin) and Google Titanium, are generally available. Published: 2025-06-13
Google Agentspace: Google Agentspace Enterprise: App-level feature management. As an Agentspace administrator, you can choose to turn the following features on or off for your end users in the web app: Agents gallery, Prompt gallery, No-code agent, NotebookLM Enterprise. Published: 2025-06-13
Cloud Load Balancing: Cloud Load Balancing supports load balancing to multi-NIC instances that use Dynamic NICs. This capability is in Preview. Published: 2025-06-13
Virtual Private Cloud: Dynamic Network Interfaces (NICs) are available in Preview. Dynamic NICs let you update an instance to add or remove network interfaces without having to restart or recreate the instance. Published: 2025-06-13
Security Command Center: The following Event Threat Detection detectors for Vertex AI have been released to Preview:
- `Persistence: New Geography for AI Service`
- `Privilege Escalation: Anomalous Multistep Service Account Delegation for AI Admin Activity`
- `Privilege Escalation: Anomalous Multistep Service Account Delegation for AI Data Access`
- `Privilege Escalation: Anomalous Service Account Impersonator for AI Admin Activity`
- `Privilege Escalation: Anomalous Service Account Impersonator for AI Data Access`
- `Privilege Escalation: Anomalous Impersonation of Service Account for AI Admin Activity`
- `Persistence: New AI API Method`
......
......
Tieni presente che l'agente utilizza lo strumento che abbiamo configurato nella cassetta degli attrezzi MCP per i database (search_release_notes_bq), recupera i dati dal set di dati BigQuery e formatta la risposta di conseguenza.
11. Complimenti
Congratulazioni, hai configurato correttamente Toolbox MCP per i database e un set di dati BigQuery per l'accesso all'interno dei client MCP.