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 specifiche degli strumenti in Agent Registry.

Rilevamento automatico dei server Google Cloud MCP

I server MCP ufficiali di Google e Google Cloud remoti vengono registrati automaticamente e inseriti in Agent Registry. I server MCP di Google e Google Cloud remoti disponibili sono elencati in Prodotti supportati nella Google 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.

Nota: se la tua organizzazione utilizza l'hub API Apigee, puoi configurarlo in modo che sincronizzi automaticamente le API in stile MCP con Agent Registry. Assicurati che la sincronizzazione sia abilitata nell'hub API per conservare i dati delle API MCP importati in Agent Registry. Per saperne di più, consulta Registrare le API MCP.

Ambito 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, ad esempio --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.

Nota: GKE supporta anche l'annotazione apphub.cloud.google.com/functional-type: "MCP_SERVER" per la compatibilità con le versioni precedenti. Tuttavia, ti consigliamo di utilizzare l' registry.gke.io/functional-type: "MCP_SERVER" etichetta per i tuoi 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à. Inoltre, configura Workload Identity utilizzando l'annotazione iam.gke.io/spiffe-identity-type: agent-identity per contribuire ad abilitare la comunicazione autenticata sicura.

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:
      annotations:
        # Workload Identity annotation for identity and access management
        iam.gke.io/spiffe-identity-type: agent-identity
      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.

Nota: quando esegui il deployment di un server MCP su GKE, il nome del server potrebbe essere visualizzato come UNKNOWN in Agent Registry. Questo comportamento non influisce sulla funzionalità del server MCP o sulla rilevabilità dei relativi strumenti.

Registrare i 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.

Avviso: questa funzionalità non è supportata nelle località multi-regionali us e eu. Devi utilizzare una regione supportata o la località global. Per saperne di più, consulta Località di Agent Registry.

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) nel 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 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 Schemi JSON e il riferimento REST.

Registrare il server e gli strumenti

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

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.

4. Fai clic su Aggiungi server MCP.

5. Nel riquadro Dettagli server MCP , inserisci il nome visualizzato, una descrizione e la regione geografica.

6. 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.

7. Fai clic su Avanti.

   Il riquadro Seleziona strumenti MCP mostra un elenco di strumenti con nomi e descrizioni del server MCP.

8. Seleziona tutti gli strumenti MCP che vuoi includere. Puoi filtrare gli strumenti dall'elenco per nome o valore.

9. 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: il binding 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
}

Sostituisci quanto segue:

• REGION: la regione del registry.
• SERVER_NAME: il nome che vuoi assegnare al server MCP, ad esempio custom-mcp-server.
• 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.

Verificare la registrazione

Elenca, filtra e visualizza i dettagli del server MCP appena registrato. Per verificare che il server MCP sia stato registrato correttamente, puoi elencare i server nel registry.