MCP Toolbox for Databases con AlloyDB: un percorso pratico

I large language model vengono utilizzati sempre più spesso a contatto con i database. Gli sviluppatori chiedono loro di scrivere SQL, spiegare schemi o rispondere a domande analitiche. Nella pratica, molti di questi flussi si basano ancora su una semplice generazione text-to-SQL, in cui il modello produce una query a partire da un prompt sperando che corrisponda allo schema e ai dati reali.

Questo approccio funziona per piccole demo, ma mostra rapidamente i suoi limiti. Spesso il modello ha una conoscenza incompleta dello schema, nessuna visibilità sui permessi e nessuna consapevolezza di come una query venga eseguita. Dal punto di vista del database, ciò rende difficile fidarsi dei risultati o integrare in sicurezza questi strumenti in ambienti reali.

Il Model Context Protocol, o MCP, segue un'altra strada. Invece di chiedere al modello di indovinare, MCP consente agli strumenti AI di interagire con i sistemi tramite operazioni esplicite e ben definite. Un database può esporre come strumenti capacità come l'elenco delle tabelle, la descrizione degli schemi, l'esecuzione di query o il recupero dei piani di esecuzione. Il client AI invoca questi strumenti e lavora con output reali, non con supposizioni.

MCP Toolbox for Databases è un'implementazione open source di questa idea da parte di Google. Espone le funzionalità del database tramite MCP e offre un framework agnostico rispetto al database per l'interazione con gli strumenti AI, mentre i singoli database sono supportati tramite strumenti MCP specifici. In questa guida, AlloyDB viene utilizzato come esempio compatibile con PostgreSQL. Ogni operazione è gestita come un'invocazione concreta di uno strumento, il che rende le interazioni più prevedibili, osservabili e facili da controllare.

In questo articolo illustro una configurazione pratica con AlloyDB for PostgreSQL e Gemini CLI. L'attenzione è su come tutto questo si traduce concretamente. Esploriamo lo schema di un database senza scrivere SQL, rispondiamo a domande di business in linguaggio naturale supportate da query reali e analizziamo come quelle query vengono eseguite. L'obiettivo non è promuovere l'automazione, ma mostrare come MCP cambi il modo in cui gli strumenti AI interagiscono con i database, in una forma comprensibile e affidabile per chi lavora sui database.

Prima di esaminare le singole query e gli esempi, è utile capire come si incastrano i componenti di questa configurazione. Pur con diversi elementi in gioco, l'architettura complessiva è semplice e volutamente stratificata.

Ad alto livello, Gemini CLI funge da interfaccia rivolta all'utente: è il punto in cui si inseriscono i prompt e in cui vengono visualizzate le risposte. Quando arrivano prompt relativi al database, Gemini non interagisce direttamente con AlloyDB, ma si affida a MCP per scoprire e invocare in modo strutturato le funzionalità del database.

L'integrazione AlloyDB per Gemini CLI include MCP Toolbox for Databases. In questa configurazione, MCP Toolbox viene eseguito implicitamente come parte dell'estensione di Gemini CLI: non serve installare o gestire un processo MCP server separato quando si utilizza Gemini CLI con l'estensione AlloyDB. Quando ci si connette da altri IDE o client MCP, MCP Toolbox viene tipicamente eseguito come server autonomo. All'avvio di Gemini CLI, viene caricata l'estensione AlloyDB, che registra i server MCP ed espone un set di strumenti per il database.

Questi strumenti rientrano in due grandi categorie. Una riguarda le operazioni amministrative e infrastrutturali, come l'elenco di cluster o istanze. L'altra si concentra sulle operazioni a livello di database: introspezione dello schema, esecuzione di query e metadati relativi alle prestazioni. Ogni operazione è esposta come uno strumento distinto, con input e output ben definiti.

Quando un prompt richiede un'interazione con il database, Gemini seleziona lo strumento MCP appropriato e lo invoca. Il server MCP esegue la richiesta su AlloyDB e restituisce risultati strutturati, che Gemini utilizza poi per produrre una risposta in linguaggio naturale. Il modello non sta indovinando i dettagli dello schema né inventando risultati: lavora con dati reali restituiti da chiamate esplicite agli strumenti.

Autenticazione e autorizzazione sono gestite al di fuori del flusso del prompt. L'accesso alle API di Google Cloud usa le Application Default Credentials, che mappano l'identità dell'utente locale ai permessi IAM. L'accesso al database utilizza credenziali PostgreSQL standard. AlloyDB rimane un sistema standard compatibile con PostgreSQL: MCP non cambia il funzionamento del database, cambia il modo in cui gli strumenti AI interagiscono con esso.

La configurazione mostrata in questo articolo segue l'approccio di integrazione AlloyDB documentato da Google, che descrive come Gemini CLI utilizza MCP Toolbox per connettersi alle istanze AlloyDB: https://docs.cloud.google.com/alloydb/docs/connect-ide-using-mcp-toolbox.

L'autenticazione è un tassello fondamentale di questa configurazione, anche se una volta impostata resta perlopiù invisibile. Gemini CLI e MCP Toolbox si autenticano su Google Cloud tramite le Application Default Credentials, comunemente note come ADC. Le Application Default Credentials offrono un metodo standard agli strumenti e alle applicazioni locali per ottenere credenziali Google Cloud basate sull'identità dell'utente e sull'ambiente configurato.

ADC consente agli strumenti locali di autenticarsi alle API di Google Cloud usando l'identità dello sviluppatore. Niente chiavi API o file di service account incorporati. I permessi sono gestiti tramite ruoli IAM standard, che determinano quali operazioni a livello di infrastruttura gli strumenti MCP possono eseguire.

L'accesso al database è gestito a parte. L'esecuzione SQL utilizza l'autenticazione PostgreSQL standard con un utente del database. Questa separazione consente di gestire in modo indipendente i permessi cloud e quelli del database, in linea con il modo in cui la maggior parte dei team già opera.

Questo modello evita di incorporare segreti nei prompt o nei file di configurazione e rende le azioni tracciabili tramite il logging cloud e di database già esistente. Per i flussi di lavoro database assistiti dall'AI, questa separazione tra identità, autorizzazione ed esecuzione è essenziale.

Una volta predisposto l'ambiente, la prima funzionalità utile da testare è l'introspezione del database. Anziché basarsi su conoscenze inferite, MCP consente al database di esporre i metadati direttamente tramite gli strumenti.

Un semplice prompt che richiede una panoramica del database attiva l'operazione MCP database_overview, che restituisce informazioni in tempo reale come la versione del motore, l'uptime e le statistiche di connessione.

Il passaggio successivo è la scoperta dello schema. Chiedere l'elenco di tutte le tabelle porta Gemini a invocare lo strumento MCP appropriato, che interroga direttamente i cataloghi di sistema.

Una volta disponibile la scoperta di base dello schema, comprendere le relazioni tra le tabelle diventa fondamentale. È qui che molti approcci basati sul linguaggio naturale faticano, se non hanno accesso diretto ai metadati.

Con MCP, Gemini può descrivere una tabella interrogando direttamente lo schema del database. In questo esempio viene descritta la tabella orders, con le sue colonne, la chiave primaria e le relazioni di chiave esterna.

Poiché queste informazioni provengono direttamente dal database, restano accurate man mano che lo schema evolve. Questo livello di consapevolezza dello schema è un prerequisito per generare query analitiche corrette.

Acquisita la consapevolezza dello schema, è possibile rispondere a domande analitiche di livello superiore in linguaggio naturale. In questa configurazione, le query in linguaggio naturale vengono tradotte in operazioni SQL esplicite ed eseguite tramite gli strumenti MCP.

Il primo esempio individua i primi cinque clienti per valore totale degli ordini. Gemini genera una query SQL che mette in join clienti, ordini e dettagli degli ordini, aggrega i ricavi e ordina i risultati. La query viene eseguita direttamente su AlloyDB.

Un secondo esempio introduce una query più complessa, ricca di join, che calcola i ricavi per prodotto e fornitore.

Il punto chiave è la trasparenza: la query SQL generata è visibile, l'esecuzione è reale e i risultati provengono direttamente dal database.

Oltre ai risultati, capire come una query viene eseguita è essenziale nei sistemi reali. MCP può esporre i piani di esecuzione delle query e i metadati correlati.

Quando si chiede di spiegare come viene eseguita una query, Gemini invoca uno strumento MCP che recupera il piano di esecuzione da AlloyDB. Il database genera il piano usando la sua normale logica PostgreSQL e Gemini lo spiega in linguaggio naturale.

Su piccoli dataset di demo sono prevedibili scansioni sequenziali e hash join. Su dataset più ampi, lo stesso flusso di lavoro può evidenziare l'utilizzo degli indici, l'esecuzione parallela e le opportunità di tuning. MCP non ottimizza automaticamente le query: aiuta a interpretare ciò che il database sta già facendo.

L'SQL tradizionale basato su prompt si affida al modello che indovina i dettagli dello schema e la struttura della query. MCP sostituisce questo approccio con operazioni esplicite e supportate da strumenti.

Poiché informazioni sullo schema, esecuzione delle query e metadati sulle prestazioni provengono direttamente dal database, i risultati sono più facili da convalidare e interpretare. I flussi di lavoro basati su MCP risultano così più adatti agli ambienti reali, dove correttezza e controllo contano.

MCP Toolbox è particolarmente indicato per esplorazione dello schema, analisi, produttività degli sviluppatori e analisi assistita delle query. Non sostituisce i percorsi applicativi transazionali né l'automazione senza vincoli. Il suo punto di forza è rendere le interazioni AI con il database osservabili e ancorate a operazioni reali.

Questi esempi si concentrano sui flussi di esplorazione e analisi. In ambienti di produzione, controlli di accesso, permessi e salvaguardie operative vanno applicati allo stesso modo di qualsiasi altra interazione con il database.