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

Panoramica del Model Context Protocol (MCP) in Apigee

Questa pagina si applica ad Apigee e ad Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Questa pagina descrive come utilizzare Apigee per esporre le tue API come strumenti MCP alle applicazioni agentiche. MCP in Apigee è disponibile per le organizzazioni con abbonamento, pagamento a consumo e valutazione, incluse quelle con residenza dei dati abilitata. A partire dalla versione 1.17.0 di Apigee hybrid, MCP è disponibile anche per Apigee hybrid: il piano dati di runtime viene eseguito all'interno del tuo cluster Kubernetes anziché sull'infrastruttura gestita da Google. Consulta Abilita MCP in Apigee hybrid per il flusso di installazione e configurazione specifico per Hybrid.

Che cos'è l'MCP?

Model Context Protocol (MCP) è un protocollo open source sviluppato da Anthropic che standardizza il modo in cui le applicazioni AI si connettono a origini dati, workflow e strumenti.

Le applicazioni di AI possono utilizzare MCP per accedere ai servizi Google Cloud e Apigee come strumenti. In questo contesto, è utile comprendere i seguenti termini MCP:

Host MCP: l'applicazione o l'ambiente AI che interagisce con l'utente. L'host MCP utilizza modelli linguistici di grandi dimensioni (LLM) per elaborare le richieste che potrebbero richiedere dati o strumenti esterni.
Client MCP: un componente all'interno dell'host MCP che aiuta l'LLM e il server MCP a comunicare tra loro. Traduce le richieste dell'LLM per il server MCP e converte le risposte del server MCP per l'LLM. Inoltre, trova e utilizza i server MCP disponibili.
Server MCP: il servizio esterno che fornisce contesto, dati o funzionalità all'LLM, fungendo da proxy tra l'LLM e il client MCP.

Come funziona l'MCP in Apigee

Gli endpoint MCP per Google, Google Cloude Apigee implementano la specifica del server MCP. In questo modo, i client MCP conformi possono accedervi per:

Scopri gli endpoint disponibili.
Elenca gli strumenti disponibili in un endpoint.
Esegui l'autenticazione su un endpoint.
Chiamare gli strumenti in base alle policy di accesso definite.

Qualsiasi client MCP che supporta endpoint MCP remoti su HTTP/S può accedere a questi strumenti. Poiché gli endpoint sono gestiti, non è necessario installare o gestire server MCP locali, server MCP remoti o un'infrastruttura aggiuntiva per consentire alle applicazioni agentiche di accedere ai tuoi servizi.

MCP in Apigee offre il supporto JSON-RPC per i metodi tools/list e tools/call. Puoi personalizzare l'endpoint MCP con parametri per la rilevabilità, la sicurezza, la disponibilità della rete e l'osservabilità.

Modelli di deployment

MCP è disponibile in due modelli di deployment di Apigee:

Apigee (SaaS): il piano dati MCP è ospitato su un'infrastruttura gestita da Google. Esegui il deployment del proxy di rilevamento MCP e l'endpoint è immediatamente disponibile.
Apigee hybrid (self-hosted, a partire da Apigee hybrid 1.17.0): il piano dati MCP viene eseguito all'interno del tuo cluster Kubernetes. Il control plane di Apigee genera la configurazione dello strumento MCP dalla specifica OpenAPI e il cluster recupera la configurazione in base alla propria pianificazione. Il traffico delle richieste MCP non lascia mai il tuo cluster. Consulta Abilita MCP in Apigee hybrid.

Architettura del piano dati MCP in Apigee hybrid

Il seguente diagramma mostra come i componenti MCP sono distribuiti tra il control plane Apigee e il cluster Apigee Hybrid.

MCP nell'architettura Apigee hybrid: i client MCP chiamano l'ingress Apigee esistente tramite HTTPS, che esegue il routing al processore di messaggi e poi al nuovo piano dati MCP nel cluster. La configurazione dello strumento MCP viene generata dal control plane di Apigee e recuperata dal tuo cluster; il control plane di Apigee non chiama mai il tuo cluster.

Due proprietà di questa architettura sono importanti per la pianificazione e la revisione della sicurezza:

Il traffico delle richieste MCP rimane all'interno del cluster. I client MCP raggiungono il tuo ingresso Apigee esistente allo stesso URL che utilizzerebbero per qualsiasi altro proxy Apigee. Il processore di messaggi indirizza quindi la richiesta al piano dati MCP nello stesso cluster. Nessuna richiesta o risposta MCP attraversa il confine con Google Cloud al momento della richiesta.
La configurazione viene estratta, non inviata. La configurazione dello strumento MCP viene generata dal control plane Apigee e recuperata da un componente del cluster in base a una pianificazione. Il control plane di Apigee non avvia mai una connessione al tuo cluster. Consulta i requisiti di rete in uscita per gli endpoint esatti che il traffico in uscita del cluster deve consentire.

Funzionalità principali di MCP in Apigee

MCP in Apigee offre funzionalità per il rilevamento, la sicurezza e la governance degli strumenti. Queste funzionalità ti aiutano a gestire il modo in cui le applicazioni agentiche interagiscono con i tuoi servizi.

Rilevamento semplificato degli strumenti con l'hub API

Puoi scoprire gli endpoint MCP disponibili per i servizi Apigee utilizzando un servizio di directory accessibile tramite un'interfaccia REST. Ogni endpoint MCP supporta anche il metodo MCP tools/list, che consente ai client MCP di scoprire gli strumenti disponibili in quell'endpoint.

Inoltre, MCP si integra con l'hub delle API Apigee. Quando viene eseguito il deployment di un proxy di rilevamento MCP, l'hub API importa automaticamente la sua specifica OpenAPI, gli assegna lo stile API MCP e mappa le operazioni API ai singoli strumenti MCP. In questo modo, gli sviluppatori possono filtrare facilmente le API abilitate per MCP nell'hub API e utilizzare la ricerca semantica con query in linguaggio naturale per trovare gli strumenti pertinenti per le loro applicazioni basate su agenti.

Posizionamento dell'argomento dello strumento nella richiesta di backend

Quando un client MCP chiama uno strumento, Apigee crea una richiesta al tuo backend dagli argomenti forniti dal client. Il valore in dichiarato da ogni parametro nella specifica OpenAPI determina la posizione dell'argomento nella richiesta in uscita.

Valore `in` OpenAPI	Dove viene inviato l'argomento nella richiesta di backend
`header`	Come intestazione della richiesta. Il nome del parametro viene utilizzato come nome dell'intestazione esattamente come scritto nella specifica.
`cookie`	Nell'intestazione della richiesta `Cookie`, come coppia `name=value`. Se un'operazione dichiara più parametri dei cookie, questi vengono inviati in un'intestazione `Cookie`, separati da `;` (un punto e virgola e uno spazio).
`query`	Nella stringa di query.
`path`	Sostituito nel percorso dell'URL della richiesta.

Ogni parametro viene visualizzato nel inputSchema dello strumento, indipendentemente dal suo valore in, quindi un client MCP li fornisce tutti nello stesso modo. Il valore in cambia solo in base alla posizione del valore nella richiesta al backend.

Ad esempio, la seguente operazione dichiara un parametro in ciascuna delle tre posizioni:

paths:
  /orders:
    get:
      operationId: listOrders
      parameters:
        - name: X-Session-Id
          in: header
          schema:
            type: string
        - name: tenantId
          in: cookie
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer

Una richiesta tools/call che fornisce tutti e tre gli argomenti produce una richiesta di backend con la seguente forma:

GET /orders?limit=25
X-Session-Id: sess-abc-123
Cookie: tenantId=tenant-xyz-789

Tieni presente il seguente comportamento:

Un argomento associato a un'intestazione o a un cookie non viene aggiunto anche alla stringa di query e non è incluso nel corpo della richiesta.
Un argomento non fornito dal client viene ignorato. Al suo posto non viene inviata alcuna intestazione, cookie o parametro di query vuoto.
Un'intestazione associata sostituisce qualsiasi intestazione con lo stesso nome già presente nella richiesta di backend. Le altre intestazioni della richiesta di backend vengono trasmesse invariate.
I valori vengono codificati in percentuale (RFC 3986) quando vengono inseriti nella richiesta di backend, quindi un valore contenente uno spazio o un carattere riservato raggiunge il backend nella sua forma codificata. Decodificala se hai bisogno dell'originale.
Se un'operazione e il relativo percorso dichiarano entrambi un parametro con lo stesso nome e lo stesso valore in, si applica la dichiarazione a livello di operazione, come richiesto dalla specifica OpenAPI.
Assegna nomi distinti ai parametri della stessa operazione, anche se dichiarano valori in diversi. OpenAPI identifica un parametro in base alla coppia di nome e posizione, ma uno strumento MCP accetta un singolo valore per nome dell'argomento. Se una specifica dichiara due parametri con lo stesso nome con valori in diversi, il client fornisce un valore e questo valore viene inviato a entrambe le posizioni dichiarate nella richiesta di backend: un sessionId dichiarato sia in: cookie sia in: query arriva nell'intestazione Cookie e nella stringa di query. Controlla se il tuo backend ha una logica che dipende dalla provenienza di un valore.
I nomi degli argomenti sono sensibili alle maiuscole, quindi UserID e userid sono due argomenti diversi. Per i parametri header, assicurati che i nomi non differiscano solo per l'uso delle maiuscole: i nomi delle intestazioni HTTP non fanno distinzione tra maiuscole e minuscole, quindi due parametri di intestazione i cui nomi differiscono solo per l'uso delle maiuscole vengono risolti nella stessa intestazione della richiesta di backend e viene mantenuto solo uno dei due valori.

I cookie sono l'unico caso in cui l'associazione può rimuovere un elemento dalla richiesta anziché aggiungerlo. A differenza di altre intestazioni HTTP, che contengono coppie nome/valore indipendenti che possono essere impostate singolarmente, tutti i cookie condividono una singola intestazione Cookie. Apigee non unisce i cookie che associ ai cookie arrivati nella richiesta del client MCP: quando una chiamata fornisce un argomento cookie, l'intestazione Cookie viene sostituita interamente solo con i cookie associati.

Pertanto, il fatto che un cookie arrivato con la richiesta HTTP del client MCP raggiunga o meno il tuo backend dipende dalla singola chiamata dello strumento:

Se l'operazione non dichiara parametri cookie, l'intestazione Cookie viene inoltrata al backend senza modifiche.
Se l'operazione dichiara parametri cookie, ma la chiamata non ne fornisce nessuno, l'intestazione Cookie viene nuovamente inoltrata al backend senza modifiche.
Non appena la chiamata fornisce almeno un argomento cookie, l'intestazione Cookie viene sostituita solo dai cookie associati. Qualsiasi cookie arrivato con la richiesta del client e non dichiarato come parametro cookie viene ignorato.

Poiché il terzo caso è basato sugli argomenti forniti da una determinata chiamata, un'operazione con parametri dei cookie facoltativi può trasmettere i cookie in una chiamata ed eliminarli in quella successiva. Non esiste un'impostazione che conserva un cookie non dichiarato. Se il tuo backend dipende da un cookie, dichiaralo come parametro cookie in ogni operazione che lo richiede, in modo che il suo valore venga sempre fornito dalla chiamata dello strumento anziché essere ereditato dalla richiesta del client.

Sicurezza

MCP in Apigee include più livelli di sicurezza per proteggere i tuoi servizi. Puoi controllare l'accesso utilizzando l'autenticazione, l'autorizzazione, i confini di rete e l'analisi dei contenuti.

Autenticazione

Gli endpoint MCP ospitati da Apigee supportano OAuth 2.1 e OpenID Connect (OIDC) per l'autenticazione. In questo modo, solo gli agenti, i client MCP e gli utenti finali con identità stabilite possono accedere agli endpoint MCP e chiamare gli strumenti MCP. I metadati delle risorse protette consentono ai client di rilevare i server di autorizzazione OAuth.

Policy di autorizzazione granulari

Puoi limitare l'accesso ai tuoi strumenti MCP in base alle identità client OAuth. Ad esempio, puoi configurare una policy nel proxy MCP Discovery per specificare che solo gli agenti designati con identità client note possono accedere a uno strumento MCP per un servizio di pagamento.

Responsabilità del client per le chiamate allo strumento

Le applicazioni client MCP sono responsabili dell'applicazione della supervisione umana delle chiamate degli strumenti, ad esempio chiedendo all'utente prima di eseguire operazioni di mutazione dello stato. Per saperne di più, consulta la documentazione di Model Context Protocol.

Osservabilità e analisi

Per gli endpoint ospitati da Apigee, puoi utilizzare Apigee Analytics per visualizzare informazioni dettagliate sull'utilizzo degli strumenti MCP. Analytics ti consente di segmentare il traffico specifico di MCP dal traffico API standard e di visualizzare le metriche a livello di singolo strumento, ad esempio il volume delle richieste di tools/list (discovery) rispetto a quelle di tools/call (esecuzione). Le metriche sul rendimento ti aiutano anche a distinguere tra l'overhead del proxy e il tempo di risposta della destinazione, consentendoti di individuare i colli di bottiglia in modo più efficace.

Affidabilità e risoluzione dei problemi

Per migliorare la risoluzione dei problemi e fornire maggiore visibilità sul processo di deployment, Apigee mostra errori specifici di infrastruttura e configurazione nell'interfaccia utente. Se un deployment non va a buon fine a causa di una specifica OpenAPI non valida o di un problema dell'infrastruttura regionale, l'interfaccia utente fornirà un feedback utile per aiutarti a risolvere il problema senza richiedere l'intervento dell'assistenza.

Utilizzo di MCP con Apigee

Puoi esporre le tue API Apigee esistenti come strumenti MCP e renderle accessibili tramite endpoint MCP. Questi endpoint possono essere configurati a livello di singolo host o di gruppo di ambienti. Ad esempio, se la tua organizzazione cymbal ha otto nomi host (ad es. api.cymbal.com, partners.cymbal.com), ciascuno associato a un gruppo di ambienti diverso, puoi ospitare un server MCP dedicato per ogni nome host.

Un endpoint di destinazione gestito (ORG_NAME.mcp.apigee.internal) viene distribuito utilizzando un proxy di rilevamento MCP specializzato nella tua organizzazione Apigee, dove vengono resi disponibili i tuoi server MCP.

Nota (solo Apigee hybrid): in Apigee hybrid, l'endpoint di destinazione si risolve nel servizio del piano dati MCP in-cluster (etichettato app=apigee-mcp-server) all'interno del cluster, non in un endpoint gestito da Google. Sono supportati due URL target equivalenti:

https://ORG_NAME.mcp.apigee.internal/mcp (consigliata)
https://mcp.apigee.internal/mcp (compatibile con le versioni precedenti)

Entrambi vengono risolti nello stesso piano dati MCP in-cluster. Il control plane di Apigee genera anche l'endpoint di destinazione del proxy di rilevamento MCP utilizzando il formato con ambito dell'organizzazione (ORG_NAME.mcp.apigee.internal); preferisci questo formato in qualsiasi codice proxy o client personalizzato in modo che l'URL che crei corrisponda all'URL generato dalla piattaforma e che i log e le tracce rendano esplicito il confine del tenant.

La tabella seguente mostra un esempio di come i clienti, tra cui l'organizzazione fittizia Cymbal, possono configurare più endpoint MCP utilizzando Apigee.

Cliente	Nome host e percorso di base MCP	Endpoint di destinazione del server MCP	Proxy API	Ambiente / Gruppo di ambienti
piatti	`api.cymbal.com/mcp`	`cymbal.mcp.apigee.internal` (progetto tenant di Cymbal Org)	`mcp-api-proxy1`	`prod`/`prod-env-group`
	`api-internal.cymbal.com/mcp`	`cymbal.mcp.apigee.internal` (progetto tenant di Cymbal Org)	`mcp-api-proxy2`	`internal`/`internal-env-group`
	`api-service.cymbal.com/mcp`	`cymbal.mcp.apigee.internal` (progetto tenant di Cymbal Org)	`mcp-api-proxy3`	`dev`/`dev-env-group`

Limitazioni

A MCP in Apigee si applicano le seguenti limitazioni:

Il numero di strumenti MCP in un'organizzazione Apigee è limitato a 1000.
Il deployment dell'infrastruttura MCP potrebbe essere soggetto a limitazioni di capacità nelle seguenti regioni:
- europe-central2
- europe-southwest1
- europe-west9
- me-central2
Se visualizzi un errore di provisioning o lo stato del provisioning non cambia mai in Eseguito il deployment, il problema potrebbe essere dovuto a limiti temporanei della capacità dell'infrastruttura nella regione selezionata. Prova a eseguire il deployment del proxy in un ambiente in un'altra regione.
MCP in Apigee supporta le seguenti versioni di OpenAPI: 3.0.0, 3.0.1, 3.0.2., 3.0.3.
Gli insight sulle API nell'hub delle API Apigee non sono disponibili per le API e gli strumenti MCP di cui è stato eseguito il deployment nelle organizzazioni Apigee con VPC-SC abilitato.
Le chiamate GET sulle risposte di errore MCP restituiranno un errore 405, poiché il server MCP al momento non supporta gli stream Server-Sent Events (SSE).
Gli insight sulle API dell'hub delle API Apigee non mostreranno le API in stile MCP o il traffico per le risorse MCP finché la versione 1-17-0-apigee-6 di Apigee non sarà completamente implementata in tutte le regioni disponibili.
Non puoi modificare l'attributo dello stile dell'API in MCP per una risorsa API con operazioni API esistenti.

Limitazioni specifiche di Apigee hybrid

A MCP in Apigee hybrid si applicano le seguenti limitazioni:

Gli argomenti dello strumento dichiarati in: header o in: cookie vengono inviati nella stringa di query. Il routing per località descritto in Posizionamento degli argomenti dello strumento nella richiesta di backend non è ancora disponibile in Apigee hybrid. Fino ad allora, un parametro che dichiara una di queste località raggiunge il backend come parametro di query, che è il comportamento che precedeva questa funzionalità. Le righe in: query e in: path di questa tabella si applicano ad Apigee hybrid così come sono scritte.
Il numero di strumenti MCP è limitato dalle dimensioni, non da un numero fisso. A differenza di Apigee (che applica un numero massimo fisso di strumenti MCP per organizzazione), Apigee Hybrid limita la capacità degli strumenti tramite quattro limiti di dimensioni: dimensione del file di specifica OpenAPI, dimensione del bundle del proxy MCP, dimensione della risposta tools/list per nome host e numero di nomi host per gruppo di ambienti. Per la maggior parte delle specifiche OpenAPI, in genere puoi prevedere di inserire 10.000 strumenti MCP per organizzazione con il limite di dimensioni della risposta predefinito. La capacità effettiva varia in base alla forma specifica della specifica (dominata dal numero di parametri e dalle proprietà del corpo della richiesta, oltre alla lunghezza della descrizione); gli schemi di risposta non vengono conteggiati nel budget. Per stimare la capacità per le tue specifiche OpenAPI e per visualizzare i quattro limiti rigidi e le relative modalità di errore, consulta Stima la capacità dello strumento MCP.
L'attivazione o la disattivazione di MCP attiva una versione canary in più fasi dei pod del processore di messaggi. L'operator Apigee aggiorna la specifica del pod del processore di messaggi quando attivi o disattivi l'MCP e il controller del processore di messaggi ApigeeDeployment esegue la modifica tramite una versione canary in più fasi anziché un riavvio in sequenza di Kubernetes standard. La release viene attivata solo durante le transizioni di attivazione e disattivazione, non durante l'attività di deployment MCP in corso o il traffico MCP in stato stabile. Pianifica l'attivazione iniziale e le successive operazioni di disattivazione durante un periodo di manutenzione approvato.
Il dimensionamento delle risorse dei pod MCP è gestito dal cliente. I pod MCP vengono eseguiti con le richieste e i limiti di risorse impostati dai valori predefiniti integrati nei grafici Helm di Apigee hybrid. Se il tuo workload richiede più capacità, regola la CPU e la memoria in overrides.yaml. Per i campi disponibili, consulta il riferimento dei campi overrides.yaml.
Un piano dati MCP per organizzazione Apigee, per cluster. Nella versione 1.17.0, l'operatore Apigee esegue il provisioning di un piano dati MCP per ogni organizzazione Apigee installata nel cluster. Un cluster che ospita più organizzazioni Apigee esegue un piano dati MCP per organizzazione; i piani dati sono indipendenti e non condividono la configurazione.
L'attivazione uniforme in un gruppo di ambienti è obbligatoria. Abilita MCP in modo uniforme in tutti i cluster che gestiscono lo stesso gruppo di ambienti Apigee. Se MCP è abilitato su alcuni cluster e non su altri all'interno di un gruppo, le richieste MCP indirizzate a un cluster senza MCP abilitato riceveranno una risposta 503 Service Unavailable.
TLS unidirezionale tra il processore di messaggi e il piano dati MCP. La versione 1.17.0 utilizza TLS unidirezionale tra il processore di messaggi e il piano dati MCP.
Il piano dati MCP si basa sul processore di messaggi per l'identità del chiamante. Il piano dati MCP nel cluster non autentica in modo indipendente i chiamanti in 1.17.0; considera attendibili le richieste che lo raggiungono e che sono già state autenticate da un proxy Apigee in esecuzione nel processore di messaggi. Ogni richiesta MCP che deve essere autenticata deve arrivare tramite un proxy MCP Apigee che applica una policy di autenticazione (consulta Gestisci l'accesso allo strumento MCP). I clienti di produzione devono applicare i controlli in entrata del cluster in modo che solo i pod del processore di messaggi (etichetta Kubernetes app=apigee-runtime nello stesso spazio dei nomi Kubernetes in cui è installato Apigee Hybrid) possano raggiungere il servizio MCP su TCP 443. Utilizza il motore di policy supportato dalla tua piattaforma (Kubernetes NetworkPolicy, Cilium, Calico, Istio AuthorizationPolicy) per applicare questa limitazione.

Passaggi successivi

Scopri come iniziare a utilizzare Apigee e MCP.
Per Apigee Hybrid, attiva prima MCP nel tuo cluster, quindi segui la guida rapida.
Per accedere ad altri prodotti Google e Google Cloud tramite gli strumenti MCP, consulta la panoramica dei server MCP di Google Cloud

Panoramica del Model Context Protocol (MCP) in Apigee Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.