Panoramica del Model Context Protocol

Questo documento fornisce una panoramica del supporto del Model Context Protocol (MCP) in API Gateway.

API Gateway può fungere da server MCP remoto, consentendoti di esporre le tue API REST esistenti ad agenti AI e LLM senza riscrivere i tuoi servizi di backend.

Sfondo

Model Context Protocol (MCP) è uno standard aperto che ti consente di creare agenti AI direttamente sulla tua infrastruttura esistente. Invece di scrivere codice di integrazione personalizzato per ogni strumento o API, MCP fornisce un modo standard per consentire ai modelli di AI di scoprire e richiamare funzionalità nel tuo ambiente.

Se configurato come server MCP, API Gateway funge da proxy. Traduce i messaggi del protocollo JSON-RPC MCP standard inviati dai sistemi agentic in richieste REST HTTP standard verso i backend esistenti.

Funzionalità supportate

Durante l'Anteprima pubblica, API Gateway supporta le seguenti funzionalità MCP:

  • Server MCP remoto: API Gateway funge da server remoto, ricevendo richieste MCP tramite HTTP (POST).
  • Integrazione OpenAPI 3.x: la configurazione MCP viene derivata direttamente dalla specifica OpenAPI 3.x utilizzando estensioni personalizzate.
  • Metodi del ciclo di vita MCP supportati:
    • initialize: stabilisce la versione e le funzionalità del protocollo.
    • notifications/initialized: Conferma l'handshake.
    • tools/list: consente ai clienti di scoprire gli strumenti disponibili e i relativi schemi.
    • tools/call: consente ai client di richiamare uno strumento con argomenti.

Limitazioni

Le seguenti limitazioni si applicano al supporto di MCP in API Gateway:

  • Le risorse (resources/*) e i prompt (prompts/*) non sono supportati.
  • Il trasporto Stdio non è supportato.
  • OpenAPI 2.0 non è supportato.
  • Le chiamate di streaming o di strumenti a lunga esecuzione non sono supportate.
  • Esclusione reciproca del routing dei modelli: non puoi attivare sia MCP sia il routing dei modelli nella stessa configurazione API. Se x-google-api-management.mcp è abilitato, non è possibile utilizzare x-google-model-router.

Per un elenco completo dei limiti tecnici, consulta Limitazioni delle funzionalità di OpenAPI 3.x.

Casi d'uso

  • Esporre le API REST esistenti come strumenti MCP: trasforma le tue API esistenti in strumenti pronti per l'AI senza modificare il codice di backend.
  • Seleziona strumenti per operazione: scegli esplicitamente quali percorsi e metodi API vengono esposti agli agenti.
  • Proteggi la superficie dello strumento: applica le norme di sicurezza di API Gateway esistenti (come chiavi API o OAuth) all'endpoint MCP.

Flusso di richiesta

Il percorso canonico per le richieste MCP è <basepath>/mcp, dove <basepath> deriva dall'URL del gateway o dalla configurazione x-google-endpoint.

Il seguente diagramma mostra il flusso di richiesta per una richiesta tools/call MCP:

  1. Un client MCP (ad es. un agente AI) invia una richiesta JSON-RPC all'endpoint MCP del gateway (ad es. POST /mcp o POST /v1/mcp se viene utilizzato un prefisso di versione).
  2. Il gateway convalida la richiesta e controlla l'autenticazione.
  3. Il gateway esamina il payload per determinare quale strumento viene chiamato.
  4. Il gateway traduce il payload MCP in una richiesta HTTP standard (percorso, parametri, corpo) in base al mapping definito nella configurazione API.
  5. Il gateway inoltra la richiesta al servizio di backend.
  6. Il backend restituisce una risposta HTTP standard.
  7. Il gateway traduce la risposta HTTP in una risposta JSON-RPC MCP e la restituisce al client.

Rilevamento tramite API Hub e Agent Registry

Se integri il tuo gateway con l'hub API, il gateway abilitato per MCP viene pubblicato nell'hub API come server MCP con metadati aggiuntivi specifici per MCP e viene visualizzato automaticamente anche in Agent Registry.

Per i gateway senza MCP abilitato, vengono pubblicati i metadati API standard. Solo i gateway con MCP abilitato mostreranno queste configurazioni MCP aggiuntive nell'hub API.

Non è necessario alcun passaggio di registrazione separato. Gli agenti possono quindi scoprire il server e i relativi strumenti tramite uno dei due cataloghi.

Per eseguire query su Agent Registry, abilita la relativa API nel tuo progetto:

gcloud services enable agentregistry.googleapis.com

Passaggi successivi