Questa pagina spiega come connettere le tue origini dati utilizzando un server Model Context Protocol (MCP) personalizzato, consentendo a Gemini Enterprise di accedere in modo sicuro ai dati privati della tua azienda.
Panoramica
Il datastore MCP personalizzato ti consente di integrare strumenti pubblici e privati, nonché sistemi di terze parti conformi a MCP, direttamente in Gemini Enterprise. Questo approccio fornisce un metodo unificato per connettere i sistemi legacy quando i connettori standard non sono disponibili. Grazie a questa integrazione, i tuoi agenti AI possono accedere a informazioni business-critical e a logiche specializzate all'interno della tua infrastruttura.
L'accesso ai server MCP pubblici viene instradato attraverso la rete gestita da Google. Per abilitare il traffico in uscita di Agent Gateway verso la tua rete privata, il server MCP personalizzato deve essere registrato nell'app Gemini Enterprise e configurato per instradare il traffico privato tramite Agent Gateway (supportato in us-central1 e europe-west1).
Limitazioni
Il server MCP personalizzato presenta le seguenti limitazioni:
Server-Sent Events (SSE): il trasporto
SSEprecedente non è supportato. Il connettore supporta esclusivamente il nuovo trasportoStreamableHTTP.Requisito del certificato TLS: configura i server MCP personalizzati con un certificato TLS firmato da un'autorità di certificazione (CA) pubblicamente attendibile, con la seguente eccezione:
- Server MCP privati con Agent Gateway: se instradi il traffico in uscita tramite Agent Gateway, puoi utilizzare CA private o certificati autofirmati configurando trust anchor TLS personalizzati (
tlsConfig) nel template di connettività dell'agente.
- Server MCP privati con Agent Gateway: se instradi il traffico in uscita tramite Agent Gateway, puoi utilizzare CA private o certificati autofirmati configurando trust anchor TLS personalizzati (
Limite di azioni: per garantire prestazioni ottimali, limita il numero di azioni attivate nel datastore del server MCP personalizzato a 100 alla volta. Per saperne di più, consulta Abilita le azioni.
Limite di associazione di Agent Gateway: un'app Gemini Enterprise si associa a un singolo Agent Gateway in uscita, ma più app Gemini Enterprise possono condividere lo stesso Agent Gateway.
Creazione con ambito app: non puoi collegare un datastore del server MCP personalizzato autonomo a un'app Gemini Enterprise. Crea il datastore direttamente all'interno dell'app in Datastore collegati.
Controlli di servizio VPC: i controlli del traffico in uscita vengono applicati tramite vincoli delle policy dell'organizzazione, come
allowedEgressFqdnseallowedDataSources, anziché tramite l'applicazione del traffico di runtime. I server MCP personalizzati sono supportati nei progetti abilitati per i Controlli di servizio VPC quando consenti esplicitamente i domini in uscita e le origini dati richiesti. Per saperne di più, consulta Esegui l'override della policy dell'organizzazione per i datastore MCP personalizzati.
Prima di iniziare
Prima di configurare la connessione al server MCP personalizzato, assicurati di eseguire le seguenti operazioni:
Ai datastore MCP personalizzati si applicano diversi vincoli delle policy dell'organizzazione. Devi:
Esegui l'override del vincolo della policy dell'organizzazione che blocca la creazione del datastore MCP personalizzato. Per saperne di più, consulta Esegui l'override della policy dell'organizzazione per i datastore MCP personalizzati.
Consenti esplicitamente i nomi di dominio completi (FQDN) per l'URL del server MCP personalizzato, l'URL di autorizzazione e l'URL del token. Per saperne di più, consulta Configura i FQDN in uscita consentiti.
Se l'applicazione forzata del progetto è abilitata o se il progetto è protetto dai Controlli di servizio VPC, devi aggiungere
custom_mcpalle origini dati consentite. Consulta Configura le origini dati consentite.Se instradi il traffico in uscita tramite Agent Gateway, assicurati che la policy dell'organizzazione del progetto consenta l'associazione dell'app Gemini Enterprise al gateway. Per saperne di più, consulta Limita l'associazione di Gemini Enterprise agli Agent Gateway approvati.
(Facoltativo) Se il tuo server MCP personalizzato è ospitato all'interno di una rete Virtual Private Cloud (VPC) privata, completa le configurazioni dei collegamenti di rete, dei gateway e dei firewall prerequisiti. Per maggiori dettagli, consulta Prerequisiti per configurare un datastore del server MCP personalizzato con connettività VPC.
Concedi il ruolo Discovery Engine Editor (
roles/discoveryengine.editor). Questo ruolo è necessario per consentire all'amministratore di creare il datastore.Per concedere questo ruolo:
Nella console Google Cloud vai alla pagina IAM.
Individua l'account utente e fai clic sull'icona edit Modifica.
Concedi il ruolo Discovery Engine Editor al tuo utente. Per saperne di più, consulta Ruoli e autorizzazioni IAM.
Registra Gemini Enterprise come applicazione client OAuth presso il tuo provider di identità (ad esempio Okta, Azure AD o Google).
Per registrare l'app:
Imposta l'URL di reindirizzamento dell'autorizzazione su
https://vertexaisearch.cloud.google.com/oauth-redirect.Concedi gli ambiti OAuth necessari all'app client.
Dopo aver registrato l'app client, ottieni
client_ideclient_secretnecessari per configurare il datastore del server MCP personalizzato nei passaggi seguenti.Se il tuo server MCP personalizzato è ospitato su Cloud Run e richiede l'autenticazione, concedi il ruolo Cloud Run Invoker (
roles/run.invoker) all'agente di servizio. Per saperne di più, consulta Configura l'autenticazione per un server MCP personalizzato su Cloud Run.
Configura l'autenticazione per un server MCP personalizzato su Cloud Run
Se il tuo server MCP personalizzato è ospitato su Cloud Run e richiede l'autenticazione, Gemini Enterprise può connettersi in modo sicuro ai servizi privati che non consentono l'accesso pubblico.
Come funziona l'autenticazione
Quando ti connetti a un servizio Cloud Run, Gemini Enterprise invia automaticamente le seguenti intestazioni di autorizzazione in ogni richiesta:
X-Serverless-Authorization: contiene un token ID firmato da Google che autentica l'agente di servizio Gemini Enterprise.Authorization: mantiene intatto il token OAuth dell'utente.
Concedi l'accesso all'agente di servizio
Per autorizzare Gemini Enterprise a richiamare il tuo servizio Cloud Run privato, concedi il ruolo Cloud Run Invoker (roles/run.invoker) all'agente di servizio Gemini Enterprise sul servizio di destinazione.
L'indirizzo email dell'agente di servizio utilizza il seguente formato:
service-PROJECT_NUMBER@gcp-sa-discoveryengine.iam.gserviceaccount.com
Sostituisci PROJECT_NUMBER con il numero di progetto del progettoGoogle Cloud che ospita la tua app Gemini Enterprise.
Per istruzioni su come concedere ruoli IAM su un servizio, consulta Autenticazione service-to-service.
Crea il datastore del server MCP personalizzato
Per impostare il flusso di configurazione:
Nella console Google Cloud , vai alla pagina Gemini Enterprise.
Nel menu di navigazione, fai clic su App e seleziona l'app che richiede la connettività al datastore MCP personalizzato.
Fai clic su Datastore connessi.
Fai clic su Nuovo datastore.
Nella pagina Seleziona un'origine dati, inserisci Server MCP personalizzato nel campo Cerca origini. Viene visualizzata la scheda Server MCP personalizzato.
Fai clic su Aggiungi server MCP. Viene visualizzata la pagina Configurazione del server MCP.
(Facoltativo) Per instradare il traffico in uscita tramite Agent Gateway, seleziona la casella di controllo Instrada il traffico in uscita tramite Agent Gateway. Seleziona questa opzione per uno dei seguenti scenari:
- Hosting di rete privata: ospiti il tuo server MCP personalizzato privatamente all'interno di una rete VPC.
- Egress con IP statico: ospiti il tuo server MCP personalizzato esternamente (ad esempio on-premise o con un provider di terze parti) e richiedi che le richieste in entrata provengano da indirizzi IP statici riservati. Il routing del traffico attraverso Agent Gateway nella tua rete VPC consente di far uscire il traffico attraverso un gateway con indirizzi IP fissi, in modo da poter configurare liste consentite del firewall basate su IP sul tuo server esterno.
Nel campo Nome risorsa motore, inserisci il nome della risorsa del motore a cui viene instradato il traffico in uscita nel seguente formato:
projects/PROJECT_NUMBER/locations/LOCATION/collections/default_collection/engines/APP_IDSostituisci quanto segue:
PROJECT_NUMBER: il tuo numero di progetto Google Cloud .LOCATION: la località della tua app, ad esempioglobal,usoeu.APP_ID: l'ID della tua app.
Come ottenere il nome risorsa del motore
Se non conosci il nome della risorsa del motore della tua app, puoi elencare i motori nel tuo progetto utilizzando l'API Discovery Engine:
curl -s -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "X-Goog-User-Project: PROJECT_ID" \ "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/collections/default_collection/engines" \ | jq -r '.engines[]? | "App Name: \(.displayName)\nEngine Resource Name: \(.name)\n"'
Sostituisci quanto segue:
PROJECT_ID: l'ID progetto.ENDPOINT_LOCATION: la località multiregionale per la richiesta API. Specifica uno dei seguenti valori:usper la multi-regione Stati Unitieuper la multiregione EUglobalper la località globale
PROJECT_NUMBER: il numero del tuo progetto Google Cloud .LOCATION: la località della tua app (ad esempioglobal,usoeu).
Output di esempio:
App Name: Cymbal Math App Engine Resource Name: projects/1234567890/locations/global/collections/default_collection/engines/chat-app-cymbal
Per saperne di più, consulta
projects.locations.collections.engines.list.Nella sezione Impostazioni di autenticazione, seleziona una delle seguenti opzioni:
OAuth 2.0: seleziona questa opzione per aggiungere l'autenticazione.
Inserisci i valori nei seguenti campi obbligatori:
Campo Descrizione URL server MCP Questo è l'endpoint su cui è ospitato il server MCP. Deve essere un URL HTTPS. Gemini Enterprise supporta solo il trasporto StreamableHTTP. L'URL spesso termina con/mcp. Ad esempio:https://mcp.cymbal.com/mcp.URL di autorizzazione L'URL di base che l'utente deve utilizzare per autorizzare Gemini Enterprise ad accedere al tuo server MCP. Ad esempio, https://mcp.cymbal.com/authorize.Parametri URL di autorizzazione Facoltativo. Eventuali parametri aggiuntivi richiesti dall'URL di autorizzazione. Ad esempio, per ottenere un token di aggiornamento da un server MCP di Google, inserisci &access_type=offline&prompt=consent.
Se il tuo server di autorizzazione richiede un parametroaudience, puoi aggiungerlo come parametro in questa impostazione. Ad esempio,&audience=https://api.cymbal.com/v1/.URL del token L'endpoint utilizzato per scambiare il codice di autorizzazione con un token di accesso durante l'autenticazione OAuth. Ad esempio, https://mcp.cymbal.com/token.ID client L'identificatore univoco dell'app OAuth che hai registrato nel tuo provider di identità per rappresentare Gemini Enterprise. Client secret La chiave riservata associata all'app OAuth che hai registrato nel tuo provider di identità per rappresentare Gemini Enterprise. Ambiti Le autorizzazioni che definiscono le azioni che Gemini Enterprise può eseguire per conto di un utente o i dati a cui può accedere sul server MCP. Gemini Enterprise richiede questi ambiti durante l'autorizzazione dell'utente. Configura la tua app OAuth in modo che supporti questi ambiti.
Quando specifichi gli ambiti, tieni presente quanto segue:- Fornisci un elenco di ambiti separati da spazi. Ad esempio, per Box, fornisci:
root_readwrite manage_managed_users manage_groups. - Assicurati che gli ambiti forniti siano sufficienti per consentire all'utente di accedere e utilizzare gli strumenti o le azioni abilitati dall'amministratore; in caso contrario, l'agente non potrà accedere alla tua app.
- Un ambito comune è
offline_access, che consente all'app di richiedere un token di aggiornamento.
Abilita il supporto PKCE Facoltativo. Seleziona questa casella di controllo per abilitare PKCE (Proof Key for Code Exchange, RFC 7636) per una maggiore sicurezza OAuth. Attiva questa impostazione se il provider OAuth del tuo server MCP supporta PKCE. Utilizza l'autenticazione di base HTTP Facoltativo. Questo tipo di annuncio sarà selezionato per impostazione predefinita. Invia l'ID client e il client secret nell'intestazione HTTP Authorizationutilizzando l'autenticazione di base anziché nel corpo della richiesta del token.- Fornisci un elenco di ambiti separati da spazi. Ad esempio, per Box, fornisci:
Fai clic su Verify Auth (Verifica autenticazione).
Fai clic su Continua.
Nessuna autenticazione: seleziona questa opzione se il server MCP non richiede l'autenticazione.
Inserisci l'URL del server MCP. Questo è l'endpoint su cui è ospitato il server MCP. Deve essere un URL HTTPS. Gemini Enterprise supporta solo il trasporto
StreamableHTTP. L'URL spesso termina con/mcp. Ad esempio:https://mcp.cymbal.com/mcp.Fai clic su Continua.
(Facoltativo) Nella sezione Opzioni avanzate, nel campo Descrizione del server MCP, descrivi cosa fa il server MCP e come gli utenti possono utilizzarlo.
Fai clic su Continua.
Nella sezione Configure your data connector (Configura il connettore dati), seleziona la Location of your data connector (Località del connettore dati) dall'elenco dei campi Multi-region (Multiregionale).
Nel campo Nome connettore dati, inserisci un nome per il datastore.
(Facoltativo) Nel campo Tag, inserisci un tag per identificare in modo univoco questo connettore dati tra le versioni. Questo tag è immutabile dopo la creazione.
(Facoltativo) Nel campo Policy di Sensitive Data Protection, inserisci il percorso della risorsa di una policy relativa ai contenuti di Sensitive Data Protection per ispezionare e bloccare i dati sensibili recuperati da Gemini Enterprise tramite questo datastore. Utilizza il formato seguente:
projects/PROJECT_ID/locations/LOCATION/contentPolicies/POLICY_ID.Fai clic su Crea. Gemini Enterprise crea il datastore e mostra i datastore nella pagina Datastore connessi.
Verifica lo stato del server MCP personalizzato
Per verificare lo stato del server MCP personalizzato, segui questi passaggi:
Fai clic sul tuo datastore nell'elenco Datastore connessi. Vengono visualizzati i dettagli del datastore.
Monitora lo stato del datastore finché non diventa
Active. Dopo che lo stato del datastore passa daCreatingaActive, il datastore del server MCP personalizzato è pronto per essere utilizzato.
Abilita azioni
Per impostazione predefinita, tutte le azioni sono disattivate. Quando connetti un server MCP, tutti i suoi strumenti vengono importati e visualizzati come azioni nel datastore di Gemini Enterprise. Per garantire un'esperienza ottimale, puoi attivare fino a 100 azioni alla volta. Per attivare queste azioni per i tuoi utenti, segui questi passaggi:
- Vai al datastore del tuo server MCP personalizzato.
Fai clic su Azioni > Ricarica le azioni personalizzate per eseguire nuovamente l'autenticazione.
Seleziona le azioni da abilitare.
Fai clic su Attiva azioni.
Configura le annotazioni per saltare la conferma dell'utente
Quando gli strumenti del tuo server MCP vengono importati come azioni nel datastore di Gemini Enterprise, Gemini Enterprise controlla le annotazioni degli strumenti per determinare se è richiesta la conferma dell'utente. Per impostazione predefinita, tutte le chiamate a qualsiasi azione richiedono la conferma dell'utente, perché Gemini Enterprise presuppone che qualsiasi operazione sia potenzialmente distruttiva e possa modificare i dati.
Se il tuo server fornisce funzionalità di sola lettura (ad esempio l'esecuzione di query su un database) e vuoi saltare questa conferma per un'esperienza utente più fluida, puoi configurare le annotazioni nelle specifiche degli strumenti MCP prima che vengano importate come azioni.
Per gestire la conferma dell'utente per le azioni del datastore, configura le seguenti annotazioni nelle definizioni degli strumenti MCP:
readOnlyHint: aggiungi questa annotazione alla definizione dello strumento se l'operazione non è distruttiva e legge solo i dati. L'esecuzione dello strumento ignora la conferma dell'utente.destructiveHint: utilizza esplicitamente questa annotazione se lo strumento modifica i dati. In questo modo viene mantenuto il comportamento di conferma predefinito.
Ad esempio, in Python:
@mcp.tool(annotations={ "destructiveHint": False, "readOnlyHint": True })
Per assicurarti che le modifiche vengano applicate alla configurazione, ricarica le azioni personalizzate. Per saperne di più, consulta Abilita le azioni.
Best practice per prestazioni e affidabilità
Per ridurre al minimo la latenza di risposta ed evitare timeout delle richieste quando utilizzi un server MCP personalizzato, segui queste best practice:
- Mantieni concise le descrizioni e gli schemi degli strumenti: mantieni concise le descrizioni degli strumenti e gli schemi dei parametri di input per ridurre la latenza di elaborazione dei prompt.
- Utilizza l'impaginazione o il polling asincrono per le operazioni a lunga esecuzione: mantieni rapide le singole chiamate allo strumento impaginando i risultati di query di grandi dimensioni. Per le operazioni di backend a lunga esecuzione (come query di data warehouse di grandi dimensioni o generazione di report), implementa un pattern di strumenti asincroni in cui uno strumento avvia il job e restituisce immediatamente un ID job, mentre un secondo strumento esegue il polling dello stato del job e recupera i risultati.
- Richiedi l'accesso offline per i token OAuth persistenti: quando configuri l'autenticazione OAuth 2.0, includi l'ambito
offline_access(o&access_type=offline&prompt=consentin Parametri URL di autorizzazione per i provider che lo richiedono) dalla configurazione iniziale, in modo che il tuo provider di identità emetta un token di aggiornamento e le richieste non falliscano o non scadano dopo la scadenza del token di accesso iniziale. - Disattiva le azioni e i datastore inutilizzati o non integri: attiva solo le azioni necessarie agli utenti e disattiva i datastore dei server MCP personalizzati inutilizzati o in fase di manutenzione, in modo che gli endpoint non raggiungibili non aggiungano latenza ai turni di chat.
Passaggi successivi
- Per proteggerti da input e output dannosi, attiva Model Armor. Per saperne di più, consulta Attiva Model Armor.
- Se vuoi eseguire query sul server MCP utilizzando un agente personalizzato, anziché l'assistente Gemini Enterprise, consulta Crea un agente.
- Per utilizzare l'agente connesso al tuo server MCP personalizzato, consulta Utilizza un agente.
- Per visualizzare i chip delle citazioni delle fonti quando Gemini Enterprise risponde a una domanda utilizzando gli strumenti sul tuo server MCP personalizzato, consulta Configura le citazioni per i datastore MCP personalizzati.