Utilizza il server MCP remoto per il recupero degli agenti per connetterti all'AI e alle applicazioni personalizzate

Questo documento mostra come utilizzare il server Model Context Protocol (MCP) remoto di Gemini Enterprise Agent Platform per connetterti alle applicazioni di AI, tra cui Gemini CLI, ChatGPT, Claude e le applicazioni personalizzate che stai sviluppando. Il server MCP remoto di Agent Retrieval ti consente di accedere ed eseguire gli strumenti di Agent Retrieval per ispezionare raccolte e indici ed eseguire ricerche vettoriali, semantiche, ibride e di testo sui tuoi dati dai tuoi ambienti di sviluppo abilitati per l'AI e dalle piattaforme di agenti AI. Il server MCP remoto di Gemini Enterprise Agent Platform viene attivato quando abiliti l'API Gemini Enterprise Agent Platform.

Il Model Context Protocol (MCP) standardizza il modo in cui i modelli linguistici di grandi dimensioni (LLM) e le applicazioni o gli agenti AI si connettono alle origini dati esterne. I server MCP ti consentono di utilizzare i loro strumenti, le loro risorse e i loro prompt per eseguire azioni e ottenere dati aggiornati dal loro servizio di backend.

Qual è la differenza tra i server MCP locali e remoti?

Server MCP locali
In genere vengono eseguiti sulla tua macchina locale e utilizzano gli stream di input e output standard (stdio) per la comunicazione tra i servizi sullo stesso dispositivo.
Server MCP remoti
Vengono eseguiti sull'infrastruttura del servizio e offrono un endpoint HTTP alle applicazioni di AI per la comunicazione tra il client MCP di AI e il server MCP. Per saperne di più sull'architettura MCP, consulta Architettura MCP.

Core stateless

Con la versione MCP 2026-07-28, MCP passa da un protocollo bidirezionale stateful a un protocollo stateless. Ogni richiesta MCP è autodescrittiva e può essere instradata utilizzando le intestazioni. Non è necessario l'handshake initialize/initialized o Mcp-Session-Id perché ogni richiesta include tutte le informazioni necessarie nelle intestazioni HTTP o nel parametro _meta. I server MCP possono richiedere informazioni aggiuntive necessarie per uno strumento tramite richieste di andata e ritorno multiple (MRTR).

Per facilitare l'instradamento e l'elaborazione delle richieste senza analizzare il corpo della richiesta, sono necessarie alcune intestazioni MCP, tra cui:

Per saperne di più sull'architettura MCP, consulta la specifica della versione 2026-07-28 di MCP e le modifiche principali.

Server MCP Google e Cloud de Confiance by S3NS remoti

I server MCP di Google e Cloud de Confiance by S3NS remoti offrono le seguenti funzionalità e i seguenti vantaggi:

  • Rilevamento semplificato e centralizzato
  • Endpoint HTTP globali o regionali gestiti
  • Autorizzazione granulare
  • Sicurezza facoltativa di prompt e risposte con la protezione di Model Armor
  • Audit logging centralizzato

Per informazioni su altri server MCP e sui controlli di sicurezza e governance disponibili per i server MCP di Google Cloud, consulta la panoramica dei server MCP di Google Cloud.

Prima di iniziare

  1. In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

  3. Abilita l'API Agent Retrieval, se non è già abilitata.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente disponi già di questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

    Abilitare l'API

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per utilizzare il server MCP di recupero agentico, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto in cui vuoi utilizzare il server MCP di recupero agentico:

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questi ruoli predefiniti contengono le autorizzazioni necessarie per utilizzare il server MCP di recupero dell'agente. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per utilizzare il server MCP di recupero dell'agente sono necessarie le seguenti autorizzazioni:

  • Effettua chiamate allo strumento MCP: mcp.tools.call
  • Elenca e ispeziona raccolte e indici: vectorsearch.collections.list, vectorsearch.collections.get, vectorsearch.indexes.list, vectorsearch.indexes.get
  • Lettura e ricerca di oggetti di dati: vectorsearch.dataObjects.get, vectorsearch.dataObjects.query, vectorsearch.dataObjects.search

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Il server MCP di Agent Retrieval espone solo strumenti di sola lettura; non sono richieste autorizzazioni di scrittura.

Autenticazione e autorizzazione

Il server MCP Agent Retrieval utilizza il protocollo OAuth 2.0 con IAM per l'autenticazione e l'autorizzazione. Tutte le identitàCloud de Confiance by S3NS sono supportate per l'autenticazione ai server MCP.

Ti consigliamo di creare un'identità separata per gli agenti che utilizzano gli strumenti MCP, in modo da poter controllare e monitorare l'accesso alle risorse. Per saperne di più sull'autenticazione, consulta Esegui l'autenticazione ai server MCP.

Ambiti OAuth MCP di Agent Retrieval

OAuth 2.0 utilizza ambiti e credenziali per determinare se un'entità autenticata è autorizzata a eseguire un'azione specifica su una risorsa. Per saperne di più sugli ambiti OAuth 2.0 di Google, consulta Utilizzare OAuth 2.0 per accedere alle API di Google.

Il server MCP di Agent Retrieval accetta il seguente ambito OAuth:

URI ambito Descrizione
https://www.googleapis.com/auth/cloud-platform Concede l'accesso completo a tutti i servizi Cloud de Confiance by S3NS , incluse tutte le funzionalità di recupero agentico.

Configura un client MCP per utilizzare il server MCP di recupero agentico

Le applicazioni e gli agenti AI, come Claude o Antigravity, possono creare un'istanza di un client MCP che si connette a un singolo server MCP. Un'applicazione di AI può avere più client che si connettono a server MCP diversi. Se la tua applicazione non è elencata nelle indicazioni specifiche per il client, puoi utilizzare le seguenti informazioni per connetterti dalla maggior parte delle applicazioni.

Nell'applicazione di AI, cerca un modo per aggiungere o connetterti a un server MCP remoto. Per il server MCP Agent Retrieval, inserisci le seguenti informazioni, se richieste:

  • Nome server: server MCP di recupero agentico

  • URL server o Endpoint: https://vectorsearch.googleapis.com/mcp

    Questo singolo endpoint espone tutti e nove gli strumenti MCP di recupero agentico. Le chiamate agli strumenti vengono inviate al backend corretto tramite il routing basato su intestazione.

  • Trasporto: HTTP trasmissibile in streaming

  • Dettagli di autenticazione: le tue credenziali Cloud de Confiance by S3NS , l'ID client e il secret OAuth o un'identità e le credenziali dell'agente. Per saperne di più sull'autenticazione, consulta Esegui l'autenticazione ai server MCP.

Routing basato su intestazioni e requisiti del protocollo client

Il server MCP Agent Retrieval invia ogni tools/call all'edge della rete in base a due intestazioni HTTP:

  • Mcp-Name: deve corrispondere al nome dello strumento nel corpo della richiesta (params.name).
  • Mcp-Param-Region: deve corrispondere al componente location del percorso della risorsa nel corpo della richiesta (ad esempio, us-central1 per una raccolta in projects/PROJECT_ID/locations/us-central1/collections/COLLECTION_ID).

Se una delle intestazioni manca o non corrisponde al corpo, la richiesta viene rifiutata con HTTP 400 Bad Request.

Il tuo client MCP deve emettere queste intestazioni in modo dinamico per tools/call. Questo comportamento è standardizzato nella versione del protocollo MCP 2026-07-28 e successive; assicurati che la libreria client MCP annunci almeno questa versione del protocollo durante l'handshake initialize. I client bloccati su versioni precedenti del protocollo o su versioni dell'SDK che non supportano l'emissione di intestazioni dinamiche non possono utilizzare il server MCP di recupero dell'agente tramite l'endpoint /mcp unificato.

URI di reindirizzamento

Per le applicazioni basate sul web e alcune applicazioni desktop, devi inserire nella lista consentita un URI di reindirizzamento quando crei un ID client e un secret per l'autenticazione. Gli URI di reindirizzamento vengono utilizzati dal server di autorizzazione per inviare token alla tua applicazione. La documentazione dell'applicazione deve specificare l'URI di reindirizzamento da utilizzare. Gli URI di reindirizzamento personalizzati non sono supportati.

Per indicazioni specifiche sull'applicazione per la configurazione e la connessione al server MCP, consulta Indicazioni specifiche per il client.

Per indicazioni più generali, consulta le seguenti risorse:

Strumenti disponibili

Il server MCP di Agent Retrieval espone nove strumenti di sola lettura:

Strumento Descrizione
list_collections Elenca le raccolte di recupero agentico in un progetto e una località.
get_collection Recupera lo schema e i metadati di una raccolta specifica.
list_indexes Elenca gli indici definiti in una raccolta.
get_index Recupera la configurazione di un indice specifico.
get_data_object Recupera un oggetto di dati per ID da una raccolta.
search_data_objects Esegui una ricerca vettoriale, semantica o di testo su una raccolta.
query_data_objects Elenca gli oggetti dati che corrispondono a un'espressione di filtro.
batch_search_data_objects Esegui più ricerche in parallelo e unisci i risultati con Reciprocal Rank Fusion (RRF) o l'API Vertex Ranking.
aggregate_data_objects Aggrega gli oggetti di dati che corrispondono a un'espressione di filtro (ad esempio, i conteggi).

Tutti gli strumenti sono di sola lettura; il server MCP non espone operazioni di scrittura, aggiornamento o eliminazione sulle risorse di recupero agentico.

Strumenti per gli elenchi

Utilizza lo strumento di controllo MCP per elencare gli strumenti o invia una richiesta HTTP tools/list direttamente al server MCP di recupero degli agenti. Il metodo tools/list non richiede l'autenticazione.

Il server MCP Agent Retrieval supporta il protocollo stateless MCP 2026-07-28, pertanto ogni richiesta stateless è autodescrittiva e deve dichiarare la versione del protocollo sia nell'intestazione HTTP MCP-Protocol-Version sia nel campo del corpo _meta.io.modelcontextprotocol/protocolVersion, insieme a un oggetto _meta.io.modelcontextprotocol/clientCapabilities (è accettato un oggetto vuoto). Anche l'intestazione HTTP Mcp-Method deve corrispondere a method nel corpo.

curl -X POST 'https://vectorsearch.googleapis.com/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/list' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientCapabilities": {}
      }
    }
  }'

Esempi di casi d'uso

Di seguito sono riportati alcuni esempi di casi d'uso per il server MCP di Agent Retrieval:

  • Ispezione delle risorse: elenca le raccolte e gli indici in un progetto e ispeziona i relativi schemi e metadati.
  • Ricerca vettoriale e semantica: esegui una ricerca vettoriale o semantica su una raccolta per trovare gli oggetti di dati più pertinenti per una query.
  • Recupero ibrido: combina ricerche semantiche, di testo e Vector Search in un'unica chiamata batch e unisci i risultati con Reciprocal Rank Fusion (RRF) o l'API Vertex Ranking.
  • Recupero di oggetti di dati: recupera singoli oggetti di dati in base all'ID o esegui query su una raccolta in base al filtro per esaminare i record importati.

Prompt di esempio

  • Elenca le raccolte di recupero agentico nel progetto PROJECT_ID in REGION.
  • "Mostra lo schema della raccolta COLLECTION_ID nella regione REGION."
  • "Esegui una ricerca semantica nella raccolta COLLECTION_ID per QUERY_TEXT e restituisci i 5 vicini più prossimi."
  • "Esegui una ricerca ibrida sulla raccolta COLLECTION_ID per QUERY_TEXT che combina la ricerca semantica e testuale, quindi riordina i primi 50 risultati con semantic-ranker-fast@latest."
  • "Recupera l'oggetto di dati con ID DATA_OBJECT_ID dalla raccolta COLLECTION_ID."

Nei prompt, sostituisci quanto segue:

  • PROJECT_ID: l'ID progetto Cloud de Confiance
  • REGION: la regione della raccolta (ad esempio us-central1)
  • COLLECTION_ID: l'ID della raccolta di recupero dell'agente
  • DATA_OBJECT_ID: l'ID di un oggetto dati nella raccolta
  • QUERY_TEXT: il testo in linguaggio naturale della query

Quote e limiti

Il server MCP Agent Retrieval non ha quote proprie. Non esiste un limite al numero di chiamate che possono essere effettuate al server MCP. Sei comunque soggetto alle quote applicate dall'API Agent Retrieval, che gli strumenti del server MCP chiamano per tuo conto. Per saperne di più, consulta Quote di recupero dell'agente.

Passaggi successivi