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:

• 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 strumento: i nomi degli strumenti devono corrispondere a [A-Za-z0-9_.-]{1,128} ed essere univoci nella specifica.
• Descrizione: ogni strumento deve risolversi in 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 definito in components.securitySchemes. Lo schema può essere uno schema JWT o una 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 del metodo MCP chiamato:

• Ciclo di vita del protocollo: i metodi initialize e notifications/initialized sono non autenticati.
• Richiamo dello strumento (tools/call): riutilizza le norme 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.
• 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. Puoi autenticare tools/list con un JWT o una chiave API.

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.

Attivazione 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 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 chiave 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 Utilizzare 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 e fai il deployment della 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 su un gateway.

5. Verificare 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. Se hai configurato tools-list.security, aggiungi le credenziali corrispondenti, 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 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 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:

Gli errori dell'applicazione di backend in genere vengono visualizzati come 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