Registra server MCP

Agent Registry funge da catalogo centralizzato registrando e gestendo gli endpoint del 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 all'interno del registry dell'agente.

Rilevamento automatico dei server MCP Google Cloud

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

Quando abiliti un'API Google Cloud 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 l'individuazione nel registry degli agenti. Non è necessario configurare o caricare manualmente le specifiche degli strumenti per questi server.

Registra 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 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 endpoint e i dettagli delle funzionalità del server. Inoltre, configura Workload Identity utilizzando l'annotazione iam.gke.io/spiffe-identity-type: agent-identity per attivare 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 nemodello dei datiti di Agent Registry.

Registra 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 tuo server MCP, devi fornire le specifiche degli strumenti durante la registrazione caricando un file toolspec.json.

Prima di iniziare

Prima di iniziare, configura il registro degli agenti. 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.

Prepara le specifiche dello strumento

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

Il file JSON deve essere allineato 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.

Registra il server e gli strumenti

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

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

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    = "NO_SPEC"
  }
}

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

Verifica 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 registro.