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 funge da catalogo centralizzato registrando e gestendo gli endpoint dei server Model Context Protocol (MCP) e gli strumenti specifici che espongono.

Questo documento descrive come registrare i server MCP e come vengono gestite le relative specifiche degli strumenti in Agent Registry.

Rilevamento automatico dei server Google Cloud MCP

I server MCP ufficiali di Google e i server MCP Google Cloud remoti vengono registrati automaticamente e inseriti in Agent Registry. I server MCP di Google e i Google Cloud server MCP remoti disponibili sono elencati in Prodotti supportati nellaGoogle Cloud documentazione dei server MCP.

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

Ambiti e binding per i server MCP gestiti da Google

I server MCP remoti gestiti da Google vengono registrati automaticamente nella località global del tuo progetto. Poiché questi server Google integrati risiedono a livello globale, devi applicare tutti i binding Identity and Access Management (IAM) per questi server nell'ambito globale specificando il flag --region=global. I binding IAM regionali, come --region=us-central1, non sono supportati per questi server MCP remoti globali e restituiscono un errore NOT_FOUND.

Registrare i server MCP da GKE

Puoi configurare la registrazione automatica per i server MCP personalizzati di cui è stato eseguito il deployment su Google Kubernetes Engine (GKE) aggiungendo l'etichetta registry.gke.io/functional-type: "MCP_SERVER" ai deployment GKE.

Per consentire ad Agent Registry di eseguire una scansione di introspezione e rilevare gli strumenti MCP, il deployment deve includere anche annotazioni che dichiarano gli URL degli endpoint del server e i dettagli delle funzionalità.

L'esempio seguente mostra un manifest di deployment del server MCP GKE che utilizza queste configurazioni.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-mcp-server
  labels:
    # GKE takes this label and registers the deployment as an MCP server to the registry
    registry.gke.io/functional-type: "MCP_SERVER"
  annotations:
    # A list of 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
    spec:
      containers:
      - name: server
        image: gcr.io/my-project/my-mcp-server:1.0.0

Quando applichi il deployment, GKE tenta automaticamente di ottenere la specifica dello strumento dal server e registra gli strumenti direttamente nel modello dei dati di Agent Registry.

Registrare i server MCP da Cloud Run

Puoi configurare la registrazione automatica per i server MCP personalizzati di cui è stato eseguito il deployment in Cloud Run specificando il --functional-type=mcp-server flag durante il deployment.

Quando esegui il deployment di un servizio Cloud Run con --functional-type=mcp-server, questo viene registrato nel catalogo dei server MCP in Agent 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 specificato, il carico di lavoro utilizza per impostazione predefinita un'identità del account di servizio.

Per scoprire come eseguire il deployment di un servizio server MCP in Cloud Run, consulta Configurare le funzionalità di Agent Platform per Cloud Run.

Per saperne di più, consulta Ospitare server MCP su Cloud Run e Autenticare i server MCP.

La registrazione automatica rileva solo le risorse di cui è stato eseguito il deployment nello stesso Google Cloud progetto.

Registrare server MCP esterni

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

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

Prima di iniziare

Prima di iniziare, configura Agent Registry. Per eseguire queste attività, devi disporre dell'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 registrare manualmente i server MCP in Agent Registry, chiedi all'amministratore di concederti il ruolo IAM Editor API Agent Registry (roles/agentregistry.editor) sul progetto. 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.

Preparare la specifica dello strumento

Crea un file toolspec.json che descriva gli strumenti forniti dal server. La dimensione massima del file per questo file di specifica è di 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 Schemi JSON e il riferimento REST.

Registrare il server e gli strumenti

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

Console

Nella Google Cloud console, vai ad Agent Registry:

Vai ad Agent Registry
Nel selettore di progetti, seleziona il Google Cloud progetto in cui hai configurato Agent Registry.
Seleziona la scheda Server MCP.
Fai clic su Aggiungi server MCP.
Nel riquadro Dettagli 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 il contenuto del file toolspec.json.

Facoltativamente, 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 dal server MCP.
Seleziona tutti gli strumenti MCP che vuoi includere. Puoi filtrare gli strumenti dall'elenco per nome o valore.
Fai clic su Salva.

gcloud

Registra il server MCP con la specifica dello strumento:

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 server MCP, ad esempio custom-mcp-server.
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

Per registrare un server MCP e specificare i relativi 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 Server resource name."
  value       = google_agent_registry_service.mcp_server.registry_resource
}