Gestire server e strumenti MCP

Anteprima

Questo prodotto o funzionalità sono soggetti ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Agent Registry ti consente di scoprire e gestire i server Model Context Protocol (MCP) e gli strumenti specifici che espongono.

I server MCP ufficiali di Google e Google Cloud remoti vengono registrati automaticamente e importati in Agent Registry quando abiliti l'API supportata Google Cloud nel tuo progetto. Puoi anche registrare manualmente altri server MCP esterni. Per saperne di più, consulta Registrare i server MCP.

Questo documento descrive come scoprire gli strumenti e i server MCP registrati e come modificare le definizioni degli strumenti.

Prima di iniziare

Prima di poter gestire i server e gli strumenti MCP, registra i server MCP in Agent Registry. Per eseguire queste attività, ti serve anche l'ID progetto.

Per utilizzare i comandi gcloud CLI in questo documento, assicurati di aver configurato l'ambiente Google Cloud CLI.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per gestire i server e gli strumenti MCP in Agent Registry, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

• Scopri gli strumenti e i server MCP disponibili: Agent Registry API Viewer (roles/agentregistry.viewer)
• Aggiorna le definizioni degli strumenti: Agent Registry API Editor (roles/agentregistry.editor)

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

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Scopri gli strumenti e i server MCP disponibili

Dopo aver registrato i server MCP, puoi scoprirli per associarli ai tuoi agenti.

Elenca tutti i server MCP disponibili

Puoi elencare tutti i server MCP registrati nel tuo ambiente e visualizzarne le configurazioni dettagliate, come gli endpoint e i metadati associati:

Console

1. Nella Google Cloud console, vai ad Agent Registry:

   Vai ad Agent Registry

2. Nel selettore di progetti, seleziona il Google Cloud progetto in cui hai configurato Agent Registry.

3. Seleziona la scheda Server MCP.

   La pagina mostra un elenco di tutti i server MCP registrati e i relativi dettagli, come nome, identificatore, descrizione, runtime e località.

4. Per visualizzare i dettagli completi di un server, fai clic sul nome del server.

gcloud

Per elencare tutti i server MCP in una località specifica, utilizza il comando mcp-servers list:

gcloud alpha agent-registry mcp-servers list \
  --project=PROJECT_ID \
  --location=REGION

Sostituisci quanto segue:

• PROJECT_ID: l'ID progetto.
• REGION: la regione del registro.

Filtra i server MCP registrati

Se hai più server o se vuoi confermare la registrazione di un server specifico, puoi filtrare l'elenco in base ai metadati del server:

Console

1. Nella Google Cloud console, vai ad Agent Registry:

   Vai ad Agent Registry

2. Nel selettore di progetti, seleziona il Google Cloud progetto in cui hai configurato Agent Registry.

3. Seleziona la scheda Server MCP.

   La pagina mostra un elenco di tutti i server MCP registrati e i relativi dettagli, come nome, identificatore, descrizione, runtime e località.

4. Per filtrare in base alla località, fai clic sul menu Località , seleziona le località che vuoi filtrare e fai clic su Applica.

   La pagina mostra un elenco filtrato dei server MCP registrati per le condizioni selezionate.

gcloud

Filtra l'elenco in modo da restituire solo le risorse che corrispondono a metadati specifici utilizzando il flag --filter:

gcloud alpha agent-registry mcp-servers list \
  --project=PROJECT_ID \
  --location=REGION \
  --filter="FILTER_EXPRESSION"

Sostituisci FILTER_EXPRESSION con l'espressione di filtro per i server MCP che vuoi filtrare. Ad esempio, puoi utilizzare i seguenti filtri:

• Per filtrare in base al nome visualizzato, utilizza displayName='DISPLAY_NAME'.
• Per cercare in base all'identificatore univoco globale (URN), utilizza mcpServerId='urn:mcp:SERVER_URN'.

Visualizza i dettagli di un server MCP

Visualizza i dettagli di un server MCP specifico, ad esempio i relativi strumenti:

Console

1. Nella Google Cloud console, vai ad Agent Registry:

   Vai ad Agent Registry

2. Nel selettore di progetti, seleziona il Google Cloud progetto in cui hai configurato Agent Registry.

3. Seleziona la scheda Server MCP.

   La pagina mostra un elenco di tutti i server MCP registrati e i relativi dettagli, come nome, identificatore, descrizione, runtime e località.

4. Fai clic sul nome del server MCP che vuoi visualizzare.

   La pagina dei dettagli include schede per i dettagli del server MCP.

5. Fai clic sulla scheda corrispondente per visualizzare i dettagli specifici del server MCP:

   • Panoramica: dettagli principali del server MCP, inclusi nome, identificatore, località e descrizione del server. La panoramica mostra anche uno snippet di codice che ti consente di creare gli agenti utilizzando Agent Development Kit (ADK).
   • Osservabilità: informazioni sullo stato operativo e sull'utilizzo di del server MCP. Mostra metriche incentrate sulle applicazioni, come latenza, traffico, errori e spesa per i token. Questa scheda si integra con Google Cloud Observability per mostrare le metriche delle prestazioni in tempo reale e l'utilizzo a livello di sistema per aiutarti a gestire i costi, eseguire il debug dei problemi e monitorare l'esperienza utente. Per saperne di più, consulta la panoramica di Observability.
   • Strumenti: il catalogo delle funzionalità fornite dal server. Questa scheda elenca le funzioni specifiche esposte da un server MCP che gli agenti possono richiamare per eseguire azioni specifiche. Per ogni strumento, l'interfaccia mostra lo schema, inclusi nome, descrizione e annotazioni comportamentali critiche che indicano come un agente di orchestrazione deve interagire con lo strumento. Fai clic sul nome di uno strumento per visualizzare uno snippet di codice che ti consente di creare gli agenti utilizzando il ADK.

gcloud

Per visualizzare i metadati dettagliati di un server MCP specifico, utilizza il comando mcp-servers describe:

gcloud alpha agent-registry mcp-servers describe SERVER_NAME \
  --project=PROJECT_ID \
  --location=REGION

Sostituisci SERVER_NAME con il nome del server MCP, ad esempio custom-mcp-server.

Aggiorna le definizioni degli strumenti

Se il server MCP aggiunge nuovi strumenti o modifica gli schemi esistenti, devi aggiornare il registro per riflettere queste modifiche. Poiché il registro non esegue automaticamente l'introspezione dei server MCP, devi caricare manualmente la specifica dello strumento aggiornata. I contenuti che carichi sostituiscono le definizioni degli strumenti esistenti per questo servizio.

Per l'API Agent Registry, le risorse McpServer vengono utilizzate per la scoperta. Pertanto, devi aggiornare direttamente la risorsa Service registrata.

Prepara la nuova specifica dello strumento. Poi, aggiorna il file JSON con le definizioni degli strumenti più recenti:

gcloud alpha agent-registry services update SERVER_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --mcp-server-spec-content=@TOOL_SPEC

Nota: le dimensioni del file di specifica dello strumento che carichi non devono superare i 10 kB.

Sostituisci quanto segue:

• SERVER_NAME: il nome del server MCP, ad esempio custom-mcp-server.
• PROJECT_ID: l'ID progetto.
• REGION: la regione del registro.
• TOOL_SPEC: il nome della nuova specifica dello strumento, ad esempio new-toolspec.json.