Google Cloud: trasforma una REST API in strumenti MCP per agenti

Che cosa fa il gateway e dove si ferma

Il vantaggio è riusare il percorso in cui hai già configurato autenticazione, quote e logging per le operazioni REST. Un assistente può scoprire strumenti come la ricerca dello stato di un ordine o la consultazione di una disponibilità, se decidi di esporli. Non significa che un agente riceva accesso automatico a tutta l'infrastruttura: la specifica e le regole del gateway costituiscono il confine da progettare e testare.

La funzione è una preview soggetta alle condizioni Pre-GA di Google Cloud. La documentazione segnala che per ora non sono disponibili resources o prompts MCP, trasporto stdio e chiamate in streaming o di lunga durata. OpenAPI 2.0 non è supportato; serve una specifica 3.x. Se il tuo caso richiede una capacità esclusa, l'integrazione non è pronta per quel flusso senza un'architettura aggiuntiva.

Passo 1: scegli gli endpoint prima di annotarli

Fai l'inventario delle operazioni API e distingui letture da scritture. Per la prima integrazione scegli una singola GET che restituisce dati limitati, come lo stato di una spedizione usando un codice già noto. Escludi cancellazioni, pagamenti, rimborsi, invii e modifiche di account. Una descrizione come «legge lo stato corrente e la data stimata per un ordine identificato» aiuta sia la persona che revisiona lo schema sia l'agente che dovrà scegliere il tool.

Controlla che la specifica abbia un operationId univoco, parametri con nomi e tipi chiari e il backend corretto. L'estensione globale x-google-api-management.mcp può includere tutte le operazioni idonee; se la abiliti, usa x-google-mcp-tool: false per escludere quelle che non vuoi rendere strumenti. Puoi anche definire nome e descrizione per singola operazione. Non esporre un endpoint solo perché è presente nell'OpenAPI: la visibilità dovrebbe corrispondere a un caso d'uso approvato.

Seleziona un'operazione e verifica l'effetto della richiesta con il team responsabile dell'API. Le chiamate MCP vengono inoltrate al backend secondo il mapping OpenAPI, quindi errori di permessi o di validazione possono raggiungere gli stessi sistemi usati dall'applicazione ordinaria. Un tool che sembra una semplice domanda può in realtà eseguire una scrittura. Documenta metodo HTTP, dati coinvolti e conseguenze prima di renderlo disponibile.

Passo 2: proteggi scoperta e invocazione

La scoperta dei tool merita un controllo distinto dalla loro esecuzione. Nella preview, tools/list non richiede autenticazione per impostazione predefinita e può mostrare nomi, descrizioni e schemi degli strumenti. Google consiglia di proteggere tools/list con un meccanismo JWT. La configurazione usa uno schema di sicurezza JWT definito nella specifica; l'autenticazione con chiave API non è accettata per questa specifica chiamata di scoperta.

Per tools/call il gateway riapplica invece i requisiti di autenticazione dell'operazione REST sottostante, che possono includere JWT o chiavi API. Verifica entrambi i percorsi: impedire l'invocazione non basta se chiunque può enumerare la superficie dei tool, e nascondere la lista non deve sostituire le autorizzazioni del backend. Se configuri tools-list.security, ricorda che l'oggetto MCP abilita la modalità globale: usa esclusioni esplicite quando vuoi pubblicare solo alcune operazioni.

Mantieni le credenziali nel sistema di gestione dei segreti e limita ciascuna identità al minimo necessario. Configura le quote così che un agente non consumi tutto il budget API con richieste ripetute. Controlla i log del gateway e del backend per collegare ogni chiamata all'identità e alla richiesta. Le quote e l'audit aiutano a rilevare anomalie, ma non impediscono a un agente autorizzato di compiere un'azione sbagliata se l'endpoint gli concede quel potere.

Passo 3: deploy, collega un client e testa senza scritture

Dopo aver aggiornato lo schema, crea una configurazione API e deployala sul gateway seguendo la procedura standard. L'endpoint MCP usa il percorso /mcp, eventualmente preceduto dal prefisso della tua API. Invia initialize con il protocol version supportato e il nome del client, poi conferma l'handshake. Per le richieste successive invia l'intestazione MCP-Protocol-Version richiesta dalla documentazione.

Collega un client MCP di prova con l'indirizzo del gateway e la credenziale necessaria. Inizia con tools/list: controlla che compaia solo il tool approvato, che i parametri corrispondano all'OpenAPI e che la descrizione spieghi bene quando usarlo. Poi invoca una GET di sola lettura con un identificativo fittizio o non sensibile. Confronta la risposta MCP con la richiesta REST diretta e verifica la stessa autenticazione, il codice di risposta, i log e il consumo della quota.

Prima di aumentare la superficie, prova credenziale scaduta, parametro errato, record inesistente e superamento della quota. Se in futuro aggiungi una scrittura, sviluppa un flusso distinto con autorizzazione esplicita, conferma umana e chiave di idempotenza, così un retry non crea due modifiche. Registra chi ha approvato il tool, quali ambienti lo usano e come revocare l'accesso. Solo dopo questi controlli valuta una preview più ampia; il test riuscito di una GET non convalida tutte le operazioni.