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

Registra server MCP

Agent Registry consente di registrare i server Model Context Protocol (MCP) automaticamente o manualmente, in modo che gli sviluppatori e gli agenti orchestratore possano scoprire e richiamare strumenti standardizzati nel tuo ecosistema di AI.

La registrazione automatica per i server MCP personalizzati di cui è stato eseguito il deployment su Google Kubernetes Engine (GKE) o Cloud Run rileva solo le risorse di cui è stato eseguito il deployment all'interno del progetto di governance in cui è abilitato Agent Registry. Per registrare server MCP personalizzati di cui è stato eseguito il deployment in progetti Google Cloud separati o ospitati esternamente, consulta Registra server MCP esterni.

Rilevamento automatico dei server MCP

I server MCP remoti di Google e Google Cloud vengono registrati e importati automaticamente in Agent Registry.

Quando abiliti un'API Google Cloud con supporto MCP nel tuo progetto, ad esempio l'API Compute Engine, il server MCP corrispondente e i relativi strumenti vengono immediatamente registrati e resi disponibili per il rilevamento in Agent Registry. Non è necessario configurare o caricare manualmente le specifiche degli strumenti per questi server.

Località e condizioni

Quando Agent Registry registra automaticamente un server MCP Google o Google Cloud remoto, crea la risorsa McpServer solo nella località global, non in singole regioni come us-central1. Se il servizio fornisce endpoint regionali (REP), Agent Registry elenca gli URL regionali nel campo interfaces della singola risorsa global McpServer.

Poiché la risorsa registrata automaticamente esiste solo in global, tieni presente le seguenti condizioni quando esegui query sul server o configuri le policy di accesso di Identity-Aware Proxy (IAP):

Utilizza global per i server registrati automaticamente: specifica la località global quando esegui query sul server in Agent Registry con --location=global o applichi policy IAP con --region=global. Se specifichi una regione come us-central1, il comando restituisce un errore NOT_FOUND perché per impostazione predefinita non esiste alcuna risorsa McpServer regionale.
Registrati manualmente in una regione per la residenza dei dati: se devi conservare i metadati del registry in una regione specifica, registra manualmente il server MCP e l'URL dell'endpoint regionale in quella regione, quindi applica la policy IAP nella stessa regione.

Per saperne di più, consulta Ambito di governance tra località regionali e globali e Server MCP remoto non trovato in una località regionale.

Prima di iniziare

Configura Agent Registry.
Recupera l'ID progetto per il progetto di governance in cui è abilitato Agent Registry.
Per utilizzare i comandi di Google Cloud CLI in questo documento, configura l'ambiente gcloud CLI.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per registrare i server MCP in Agent Registry, chiedi all'amministratore di concederti il ruolo IAM Agent Registry API Editor (roles/agentregistry.editor) nel progetto di governance in cui è abilitato Agent Registry. 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.

Registra i server MCP da GKE

Per registrare i server MCP personalizzati di cui è stato eseguito il deployment su GKE, aggiungi le etichette e le annotazioni Kubernetes richieste al manifest di deployment. L'esempio seguente mostra un manifest di deployment del server MCP GKE configurato per la registrazione automatica:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-mcp-server
  labels:
    # GKE takes this label and registers the deployment as an MCP server
    registry.gke.io/functional-type: "MCP_SERVER"
  annotations:
    # Endpoint URLs where the GKE controller can access this MCP server
    modelcontextprotocol.info/urls: |
      - https://my-mcp-server.default.svc.cluster.local/mcp
    # Defines structural capabilities for the MCP server card
    modelcontextprotocol.info/capabilities: |
      card:
        endpoint: "/mcp"
        protocol: "HTTP"
spec:
  selector:
    matchLabels:
      app: my-mcp-server
  template:
    metadata:
      labels:
        app: my-mcp-server
      annotations:
        # Agent Identity annotation for identity and access management
        iam.gke.io/spiffe-identity-type: agent-identity
    spec:
      containers:
      - name: server
        image: gcr.io/PROJECT_ID/my-mcp-server:1.0.0

Sostituisci PROJECT_ID con l'ID progetto Google Cloud .

Per configurare e applicare il manifest di deployment, segui questi passaggi:

In metadata.labels del manifest Deployment, aggiungi l'etichetta registry.gke.io/functional-type: "MCP_SERVER".

Nota: GKE supporta anche l'annotazione apphub.cloud.google.com/functional-type: "MCP_SERVER" per la compatibilità con le versioni precedenti. Tuttavia, utilizza l'etichetta registry.gke.io/functional-type: "MCP_SERVER" per i deployment GKE.
In metadata.annotations del tuo manifest Deployment, attiva il rilevamento automatico degli strumenti MCP fornendo le annotazioni modelcontextprotocol.info/urls e modelcontextprotocol.info/capabilities per dichiarare gli URL degli endpoint del server e i dettagli delle funzionalità.
In spec.template.metadata.annotations del template del pod, abilita la comunicazione autenticata configurando l'identità dell'agente con l'annotazione iam.gke.io/spiffe-identity-type: agent-identity.
Applica il manifest di deployment al tuo cluster.

Quando applichi il deployment, GKE tenta automaticamente di ottenere la specifica dello strumento dal server e registra il server e i suoi strumenti direttamente in una risorsa di rilevamento McpServer di sola lettura in Agent Registry. Agent Registry utilizza il nome del deployment come nome visualizzato del server MCP.

Registra i server MCP da Cloud Run

Puoi registrare automaticamente i server MCP personalizzati quando li esegui il deployment come servizi Cloud Run specificando il flag --functional-type=mcp-server. Il flag --functional-type=mcp-server identifica il servizio Cloud Run come server MCP anziché come workload containerizzato standard, indicando a Cloud Run di registrare il server in Agent Registry. Durante la registrazione, Cloud Run aggiunge automaticamente il nome del server e il tipo MCP_SERVER al registry.

Puoi anche specificare un tipo di identità utilizzando il flag --identity-type. Ad esempio, specifica un'identità agent-identity o service-account. Se non viene specificato, il workload utilizza per impostazione predefinita l'identità di un account di servizio.

Per configurare la registrazione automatica su un servizio Cloud Run nuovo o esistente, consulta Configura le funzionalità di Gemini Enterprise Agent Platform per Cloud Run. Per eseguire il deployment e proteggere i server MCP su Cloud Run, consulta Ospita i server MCP su Cloud Run e Autentica i server MCP.

Registra server MCP esterni

Per gestire e riutilizzare gli strumenti forniti da server esterni o API personalizzate, devi registrare manualmente il server MCP.

Quando registri manualmente un server MCP, Agent Registry registra l'endpoint. Tuttavia, non esamina automaticamente il server per determinare quali strumenti sono disponibili. Per consentire agli utenti di scoprire gli strumenti esatti disponibili sul tuo server MCP, devi fornire le specifiche degli strumenti durante la registrazione caricando un file toolspec.json.

Prepara la specifica dello strumento

Crea un file toolspec.json che descriva gli strumenti forniti dal server. La dimensione massima del file di specifica è 10 kB.

Il file JSON deve essere conforme alla specifica MCP per gli schemi degli strumenti, ad esempio:

{
  "tools": [
    {
      "name": "get_customer_info",
      "description": "Retrieves customer details from the database.",
      "annotations": {
        "title": "Get Customer Info",
        "readOnlyHint": true,
        "idempotentHint": true
      }
    },
    {
      "name": "create_support_ticket",
      "description": "Creates a new support ticket in the issue tracking system.",
      "annotations": {
        "title": "Create Support Ticket",
        "destructiveHint": true,
        "idempotentHint": false,
        "openWorldHint": true
      }
    }
  ]
}

Per i requisiti strutturali dettagliati, consulta gli schemi JSON e il riferimento REST.

Registra il server e gli strumenti

Registra il server MCP e carica la definizione dello strumento contemporaneamente:

Console

Nella console Google Cloud , vai a Agent Registry:

Vai ad Agent Registry
Nel selettore di progetti, seleziona il progetto Google Cloud in cui hai configurato Agent Registry.
Seleziona la scheda Server MCP.
Fai clic su Aggiungi server MCP.
Nel riquadro Dettagli del server MCP, inserisci il nome visualizzato, una descrizione e la regione geografica.
Nella sezione Specifica dello strumento, inserisci l'URL dell'endpoint del server MCP e incolla i contenuti del file toolspec.json.

Se vuoi, fai clic su Importa strumenti in questo riquadro per importare gli strumenti MCP dall'URL. Questa opzione funziona solo se l'URL dell'endpoint del server MCP è ospitato pubblicamente su internet. Non puoi utilizzare questa funzionalità per importare strumenti da server MCP ospitati privatamente.
Fai clic su Avanti.

Il riquadro Seleziona strumenti MCP mostra un elenco di strumenti con nomi e descrizioni del tuo server MCP.
Seleziona tutti gli strumenti MCP che vuoi includere. Puoi filtrare gli strumenti dell'elenco per nome o valore.
Fai clic su Salva.

gcloud

I flag di specifica che utilizzi determinano la raccolta di risorse a cui appartiene il componente. Per una mappatura completa dei flag alle raccolte di risorse, consulta [Risorse di servizio e risorse di rilevamento](/agent-registry/data-model#service-resources).

Registra il server MCP con la specifica dello strumento utilizzando il comando gcloud agent-registry services create:

gcloud agent-registry services create SERVER_NAME \
    --project=PROJECT_ID \
    --location=REGION \
    --display-name="DISPLAY_NAME" \
    --mcp-server-spec-type=tool-spec \
    --mcp-server-spec-content=toolspec.json \
    --interfaces=url=SERVER_URL,protocolBinding=PROTOCOL

Sostituisci quanto segue:

SERVER_NAME: il nome che vuoi assegnare al tuo server MCP, ad esempio custom-mcp-server. Il nome deve contenere da 4 a 63 caratteri e può contenere solo lettere minuscole, numeri e trattini.
PROJECT_ID: l'ID progetto
REGION: la regione del registry.
DISPLAY_NAME: il nome leggibile che vuoi assegnare al server, ad esempio Custom MCP Server.
SERVER_URL: l'URL dell'endpoint del server MCP, ad esempio https://api.example.com/mcp.
PROTOCOL: l'associazione del protocollo per l'endpoint. I valori validi sono jsonrpc, http-json o grpc. Per i server MCP, questo valore è spesso jsonrpc.

Terraform

Il blocco di specifica che configuri determina la raccolta di risorse a cui appartiene il componente. Per una mappatura completa delle specifiche alle raccolte di risorse, consulta [Risorse di servizio e risorse di rilevamento](/agent-registry/data-model#service-resources).

Per registrare un server MCP e specificarne gli strumenti, configura una risorsa google_agent_registry_service con il blocco mcp_server_spec:

resource "google_agent_registry_service" "mcp_server" {
  location     = "REGION"
  service_id   = "SERVER_NAME"
  display_name = "DISPLAY_NAME"
  description  = "An external MCP server registered using Terraform."

  interfaces {
    url              = "SERVER_URL"
    protocol_binding = "JSONRPC"
  }

  mcp_server_spec {
    type    = "TOOL_SPEC"
    content = file("toolspec.json")
  }
}

output "server_resource_name" {
  description = "The generated read-only McpServer resource name."
  value       = google_agent_registry_service.mcp_server.registry_resource
}