Configurare Model Context Protocol

Anteprima

Questa funzionalità è soggetta ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

Questo documento descrive come configurare API Gateway in modo che funga da server Model Context Protocol (MCP) remoto.

Prima di iniziare

• Assicurati di disporre di una specifica OpenAPI 3.x valida per la tua API. MCP non è supportato per OpenAPI 2.0.
• Assicurati di comprendere le nozioni di base di API Gateway.

Convalida della configurazione

Quando carichi la specifica OpenAPI, API Gateway esegue le seguenti convalide per la configurazione MCP:

• Località: l'estensione x-google-mcp-tool deve essere specificata solo a livello di singola operazione.
• Metodo HTTP: solo le operazioni GET, POST, PUT, PATCH e DELETE possono essere esposte come strumenti MCP.
• Nome strumento: i nomi degli strumenti devono corrispondere a [A-Za-z0-9_.-]{1,128} ed essere univoci in tutta la specifica.
• Descrizione: ogni strumento deve restituire una descrizione non vuota (estratta dalla descrizione, dal riepilogo o dall'override dell'operazione). Le operazioni senza una descrizione risolvibile vengono rifiutate.
• Sicurezza: se configuri l'autenticazione per tools/list, devi denominare esattamente uno schema di sicurezza JWT definito in components.securitySchemes. La sicurezza delle chiavi API non è supportata per tools/list in Anteprima pubblica.

Modello di autenticazione

API Gateway applica regole di autenticazione diverse a seconda del metodo MCP chiamato:

• Ciclo di vita del protocollo: i metodi initialize e notifications/initialized sono non autenticati.
• Richiamo dello strumento (tools/call): riutilizza i criteri di autenticazione definiti per l'operazione sottostante nella specifica OpenAPI. Applica gli stessi requisiti di chiave API o JWT della chiamata diretta all'endpoint REST.
• Rilevamento degli strumenti (tools/list): per impostazione predefinita, questo metodo non è autenticato. Tuttavia, come best practice di sicurezza, ti consigliamo vivamente di proteggere il rilevamento degli strumenti attivando l'autenticazione per questo metodo utilizzando tools-list.security. Se scegli di abilitare l'autenticazione, devi utilizzare uno schema di sicurezza JWT. L'autenticazione tramite chiave API non è supportata per tools/list.

Passaggi per configurare MCP

Segui questi passaggi per esporre la tua API come strumenti MCP:

1. Identificare le operazioni da esporre

Esamina la specifica OpenAPI e decidi quali operazioni devono essere disponibili per gli agenti AI.

2. Aggiorna la specifica OpenAPI

Puoi attivare MCP a livello globale per tutte le operazioni idonee o configurarlo per ogni operazione.

Abilitazione globale

Attiva MCP a livello globale aggiungendo il campo mcp a x-google-api-management a livello di documento:

openapi: 3.0.3
info:
  title: Bookstore API
  version: 1.0.0
x-google-api-management:
  mcp: true
  backends:
    bookstore-backend:
      address: https://bookstore-backend-12345678.us-central1.run.app

Nota: assicurati che le operazioni abbiano un backend configurato (utilizzando x-google-backend a livello di operazione o utilizzando i valori predefiniti globali) per essere idonee come strumenti MCP.

Se abilitate a livello globale, tutte le operazioni idonee (in base al metodo e al percorso HTTP) vengono esposte come strumenti MCP. Per impostazione predefinita, il nome dello strumento è operationId dell'operazione e la descrizione è la descrizione o il riepilogo dell'operazione.

Configurazione per operazione

Puoi eseguire l'override delle impostazioni globali o esporre selettivamente le operazioni utilizzando x-google-mcp-tool:

paths:
  /v1/shelves/{shelf}:
    delete:
      operationId: deleteShelf
      summary: Delete a shelf.
      x-google-backend: bookstore-backend
      x-google-mcp-tool:
        name: delete_shelf
        description: "Permanently delete a shelf and every book on it."

Puoi anche disattivare un'operazione quando è abilitata a livello globale impostando x-google-mcp-tool: false.

3. Autentica tools/list (consigliato)

Per impostazione predefinita, il metodo tools/list (che enumera gli strumenti disponibili) non è autenticato. Come best practice di sicurezza, ti consigliamo vivamente di applicare l'autenticazione configurando tools-list.security in x-google-api-management/mcp. Devi utilizzare uno schema JWT; le chiavi API non sono supportate per questo metodo.

x-google-api-management:
  mcp:
    tools-list:
      security:
        myJWT: []

Nota: la configurazione dell'estensione mcp come oggetto (ad esempio, per attivare l'autenticazione per tools/list) attiva anche MCP a livello globale per tutte le operazioni idonee. Se vuoi configurare la sicurezza di tools/list, ma non vuoi esporre tutte le operazioni idonee, devi disattivare esplicitamente queste operazioni impostando x-google-mcp-tool: false.

4. Crea e distribuisci la configurazione API

Crea una configurazione API dalla specifica annotata ed eseguine il deployment su un gateway utilizzando il flusso standard. Per maggiori dettagli, vedi Deployment di un'API in un gateway.

5. Verifica l'assistenza MCP

Una volta eseguito il deployment, puoi verificare che il gateway gestisca le richieste MCP.

Stretta di mano

Invia una richiesta di inizializzazione per stabilire la versione e le funzionalità del protocollo:

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {"name": "demo-client", "version": "1.0.0"}
  }
}'

Nota: i client devono inviare l'intestazione MCP-Protocol-Version in ogni richiesta dopo l'inizializzazione. Se l'intestazione non è presente, il gateway torna alla versione 2025-03-26.

Conferma handshake

Conferma l'inizializzazione. Il gateway risponde con HTTP 202 Accepted:

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc": "2.0", "method": "notifications/initialized"}'

Scopri gli strumenti

Elenca gli strumenti disponibili:

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

Come vengono mappati gli argomenti alla richiesta REST

Gli argomenti passati a uno strumento vengono mappati alla richiesta REST sottostante in base alla specifica OpenAPI:

• Parametri di percorso e query: diventano proprietà di primo livello nell'oggetto arguments, con chiave in base ai nomi dei parametri OpenAPI.
• Corpo della richiesta: nidificato in una singola proprietà denominata body. Ad esempio, per creare una risorsa, devi passare {"body": {"fieldName": "value"}}.
• Intestazioni: diventano anche proprietà di primo livello. Il gateway li inserisce come intestazioni HTTP standard nella chiamata di backend.

Nota: non puoi associare parametri a intestazioni di sistema riservate o a intestazioni che iniziano con x-google-.

La richiesta di backend transcodificata non è distinguibile da una richiesta REST diretta al servizio di backend. I servizi di backend non possono distinguere a livello di programmazione tra una chiamata REST diretta e una transcodificata da MCP.

Richiamare uno strumento

Richiamare uno strumento specifico. Assicurati di includere tutti i token di autenticazione richiesti se l'operazione REST sottostante li richiede:

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "delete_shelf",
    "arguments": {"shelf": "sci-fi"}
  }
}'

Osservabilità

Le richieste MCP generano metriche e log standard di API Gateway. Puoi distinguere il traffico MCP dal traffico REST standard esaminando il percorso della richiesta (in genere termina con /mcp) o configurando metriche personalizzate.

Risoluzione dei problemi relativi agli errori MCP

MCP distingue tra errori di trasporto ed errori di protocollo. Il gateway restituisce HTTP 200 con un oggetto di errore JSON-RPC per errori di protocollo e applicazione, poiché le risposte non 200 possono causare l'errore di molti client MCP a livello di trasporto.

La tabella seguente descrive i sintomi e le soluzioni comuni:

Sintomo	Codice JSON-RPC	Stato HTTP	Significato e correzione tipica
Metodo non consentito	n/a	405	Una richiesta non POST ha raggiunto /mcp. È supportato solo HTTP POST.
Errore di analisi JSON	-32700	400	Il corpo della richiesta non è un JSON valido.
Metodo o ID mancante/non valido	-32600	200	Il corpo è un JSON valido, ma non una richiesta JSON-RPC valida. Controlla i campi obbligatori (jsonrpc, method, id).
Il metodo non è supportato	-32601	200	Il metodo non rientra nell'ambito supportato (ad es. ping).
Versione del protocollo non supportata	-32602	200	protocolVersion indica una versione non supportata dal gateway.
Versione del protocollo mancante	-32602	200	I parametri initialize omettono protocolVersion o non sono una stringa.
Strumento sconosciuto	-32602	200	Nome dello strumento non trovato. Svuota la cache del client o verifica il deployment.
Argomenti dello strumento non validi	-32602	200	Gli argomenti sono mancanti o non validi. Verifica l'annidamento della chiave body.
Corpo troppo grande	-32000	200	Il payload della risposta ha superato i limiti di dimensione.
Corpo del trasporto troppo grande	n/a	413	Il corpo della richiesta HTTP non elaborata ha superato i limiti di trasporto del gateway.
Errore del server	-32000	200	Risposta di backend non analizzabile. Controlla i log.
Non autorizzato / Vietato	n/a	401/403	Errore di autenticazione. La risposta contiene un'intestazione WWW-Authenticate che punta ai metadati della risorsa protetta.

Gli errori dell'applicazione di backend in genere vengono visualizzati come una risposta JSON-RPC riuscita (HTTP 200) con result.isError: true contenente il corpo dell'errore di backend.

Passaggi successivi

• Panoramica del Model Context Protocol
• Estensioni OpenAPI 3.x
• Limitazioni delle funzionalità di OpenAPI 3.x