Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Configura Model Context Protocol

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

Prima di iniziare

Assicurati di avere 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:

Posizione: 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 dello strumento: i nomi degli strumenti devono corrispondere a [A-Za-z0-9_.-]{1,128} ed essere univoci nella specifica.
Descrizione: ogni strumento deve avere una descrizione non vuota (presa 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 assegnare un nome a un solo schema di sicurezza definito in components.securitySchemes. Lo schema può essere uno schema JWT o uno schema di chiave API. Se utilizzi uno schema JWT, devi anche assegnargli un nome nel requisito security di primo livello della specifica.

Modello di autenticazione

API Gateway applica regole di autenticazione diverse a seconda della chiamata al metodo MCP:

Ciclo di vita del protocollo: i metodi initialize e notifications/initialized non sono autenticati.
Chiamata dello strumento (tools/call): riutilizza le policy di autenticazione definite per l'operazione sottostante nella specifica OpenAPI. Applica gli stessi requisiti di chiave API o JWT della chiamata diretta all'endpoint REST.
Tool Discovery (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. Puoi autenticare tools/list con un JWT o una chiave API.

Passaggi per configurare l'MCP

Segui questi passaggi per esporre l'API come strumenti MCP:

1. Identifica 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 l'MCP a livello globale per tutte le operazioni idonee o configurarlo per singola operazione.

Abilitazione globale

Attiva l'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

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 è l'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 per la sicurezza, ti consigliamo vivamente di applicare l'autenticazione configurando tools-list.security in x-google-api-management.mcp. Puoi assegnare un nome a uno schema JWT o a uno schema di chiavi API.

L'esempio seguente richiede un JWT:

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

L'esempio seguente richiede una chiave API. I client devono inviare la chiave nell'intestazione HTTP x-api-key; tools/list non legge le chiavi API dai parametri di ricerca. Una richiesta senza una chiave valida riceve un errore JSON-RPC e nessun elenco di strumenti. Per scoprire come creare una chiave API, consulta Utilizza le chiavi API.

x-google-api-management:
  mcp:
    tools-list:
      security:
        api_key: []
components:
  securitySchemes:
    api_key:
      type: apiKey
      name: x-api-key
      in: header

4. Crea ed esegui il deployment della configurazione API

Crea una configurazione API dalla specifica annotata ed eseguine il deployment in un gateway utilizzando il flusso standard. Per maggiori dettagli, consulta Deployment di un'API in un gateway. Per modificare gli strumenti in un secondo momento, consulta Aggiorna gli strumenti MCP esposti.

5. Verifica l'assistenza MCP

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

Handshake

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"}
  }
}'

Conferma l'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. Se hai configurato tools-list.security, aggiungi la credenziale corrispondente, ad esempio un'intestazione Authorization: Bearer per un JWT o un'intestazione x-api-key per una chiave API:

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 gli argomenti vengono mappati alla richiesta REST

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

Parametri di percorso e di 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, passi {"body": {"fieldName": "value"}}.
Intestazioni: diventano anche proprietà di primo livello. Il gateway li inserisce come intestazioni HTTP standard nella chiamata al backend.

La richiesta di backend transcodificata non è distinguibile da una richiesta REST diretta al tuo servizio di backend. I servizi di backend non possono distinguere in modo programmatico tra una chiamata REST diretta e una transcodificata da MCP.

Richiama 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"}
  }
}'

Aggiorna gli strumenti MCP esposti

Le configurazioni API in API Gateway sono immutabili, quindi non puoi modificare la definizione dell'API in una configurazione API esistente. Di conseguenza, la risposta tools/list è statica per ogni configurazione API di cui è stato eseguito il deployment.

Per aggiungere, rimuovere, rinominare o aggiornare gli strumenti MCP esposti o le impostazioni di sicurezza di tools/list, crea una nuova configurazione API ed eseguine il deployment nel gateway:

Aggiorna la specifica OpenAPI 3.x, incluse le operazioni, i valori operationId, i riepiloghi, i parametri e le estensioni x-google-api-management.mcp e x-google-mcp-tool.
Crea una nuova configurazione API con un nuovo ID configurazione API:
```
gcloud api-gateway api-configs create NEW_CONFIG_ID \
    --api=API_ID \
    --openapi-spec=API_DEFINITION \
    --project=PROJECT_ID \
    --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL
```
Sostituisci quanto segue:
- NEW_CONFIG_ID: un nuovo ID per la configurazione API aggiornata
- API_ID: l'ID dell'API API Gateway
- API_DEFINITION: il percorso della specifica OpenAPI 3.x aggiornata
- PROJECT_ID: il tuo ID progetto Google Cloud
- SERVICE_ACCOUNT_EMAIL: l'indirizzo email del account di servizio utilizzato per firmare i token per i backend con autenticazione configurata. Ometti questo flag se nessuno dei tuoi backend richiede l'autenticazione.
Per saperne di più, consulta Crea una configurazione API.
Aggiorna ogni gateway che gestisce l'API in modo che utilizzi la nuova configurazione API:
```
gcloud api-gateway gateways update GATEWAY_ID \
    --api=API_ID \
    --api-config=NEW_CONFIG_ID \
    --location=GCP_REGION \
    --project=PROJECT_ID
```
Sostituisci quanto segue:
- GATEWAY_ID: l'ID del gateway da aggiornare
- GCP_REGION: la regione in cui è stato eseguito il deployment del gateway
Per saperne di più, consulta Aggiorna un gateway.
Chiama tools/list per controllare il set di strumenti aggiornato. Per un esempio di richiesta, consulta Scopri gli strumenti.
Quando nessun gateway utilizza la configurazione API precedente, elimina la configurazione API sostituita:
```
gcloud api-gateway api-configs delete OLD_CONFIG_ID \
    --api=API_ID \
    --project=PROJECT_ID
```
Sostituisci OLD_CONFIG_ID con l'ID della configurazione API sostituita. Non eliminare una configurazione API mentre è ancora utilizzata da un gateway. Se la nuova configurazione API rinomina o rimuove le metriche delle quote, i gateway che gestiscono ancora una configurazione API precedente possono restituire errori HTTP 500 fino all'aggiornamento (consulta Le quote si applicano all'intera API). Per saperne di più, consulta Elimina una configurazione API.

Quando aggiorni gli strumenti MCP, tieni presente i seguenti comportamenti di implementazione e del client:

Implementazione senza tempi di inattività: API Gateway aggiorna i gateway senza tempi di inattività. Durante la propagazione della nuova configurazione API, alcune richieste potrebbero raggiungere brevemente la configurazione API precedente. Se il deployment dell'API è stato eseguito su più gateway o regioni, aggiorna ogni gateway separatamente.
Cache degli strumenti client: poiché API Gateway gestisce l'MCP su un trasporto HTTP stateless, il gateway non emette notifiche notifications/tools/list_changed. Al termine dell'aggiornamento del gateway, i client MCP che memorizzano nella cache le definizioni degli strumenti devono chiamare di nuovo tools/list per rilevare gli strumenti aggiornati.
Limiti di configurazione API: ogni API è limitata a 100 configurazioni API, quindi elimina le configurazioni API sostituite dopo aver aggiornato i gateway. Crea le configurazioni API una alla volta. Se avvii una seconda configurazione API per la stessa API prima che la prima sia terminata, una o entrambe potrebbero non essere utilizzabili da un gateway. Per saperne di più, consulta Quote e limiti.

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 (che 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 gli errori di protocollo e applicazione, poiché le risposte diverse da 200 possono causare errori di molti client MCP a livello di trasporto.

La tabella seguente descrive i sintomi e le soluzioni più 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 il protocollo 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 nella configurazione API di cui è stato eseguito il deployment. Aggiorna la cache dello strumento client o consulta Aggiorna gli strumenti MCP esposti.
Argomenti dello strumento non validi	`-32602`	`200`	Gli argomenti sono mancanti o non validi. Verifica l'nidificazione della chiave `body`.
Corpo troppo grande	`-32000`	`200`	Il payload della risposta ha superato i limiti di dimensioni.
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 del backend non analizzabile. Controlla i log.
Non autorizzato/Vietato	n/a	`401`/`403`	Errore di autenticazione. La risposta contiene un'intestazione `WWW-Authenticate` che rimanda ai metadati della risorsa protetta.

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