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

Configurare Model Context Protocol

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

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: []

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

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.

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.