Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Registrar servidores MCP

O Registro de Agente funciona como um catálogo centralizado, registrando e gerenciando endpoints de servidores do Protocolo de Contexto de Modelo (MCP) e as ferramentas específicas que eles expõem.

Este documento descreve como registrar servidores MCP e como as especificações de ferramentas são gerenciadas no Agent Registry.

Descoberta automática de servidores Google Cloud MCP

Os servidores MCP oficiais do Google e Google Cloud remotos são registrados e ingeridos automaticamente no Agent Registry. Os servidores MCP remotos do Google e do Google Cloud disponíveis estão listados em Produtos compatíveis na documentação de servidoresGoogle Cloud MCP.

Quando você ativa uma API Google Cloud compatível no projeto, como a API Compute Engine, o servidor MCP correspondente e as ferramentas dele são registrados imediatamente e disponibilizados para descoberta no Registro de agentes. Não é necessário configurar ou fazer upload manual das especificações de ferramentas para esses servidores.

Registrar servidores MCP do GKE

É possível configurar o registro automático para servidores MCP personalizados implantados no Google Kubernetes Engine (GKE) ao adicionar o rótulo registry.gke.io/functional-type: "MCP_SERVER" às implantações do GKE.

Para permitir que o Agent Registry faça uma verificação de introspecção e descubra suas ferramentas do MCP, a implantação também precisa incluir anotações que declaram os URLs de endpoints e os detalhes de recursos do servidor. Além disso, configure a Identidade da carga de trabalho usando a anotação iam.gke.io/spiffe-identity-type: agent-identity para ajudar a ativar a comunicação autenticada segura.

O exemplo a seguir mostra um manifesto de implantação do servidor MCP do GKE usando essas configurações.

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 você aplica a implantação, o GKE tenta automaticamente extrair a especificação da ferramenta do servidor e registra as ferramentas diretamente no modelo de dados do Agent Registry.

Registrar servidores MCP externos

Para gerenciar e reutilizar ferramentas fornecidas por servidores externos ou APIs personalizadas, é necessário registrar explicitamente o servidor MCP.

Ao registrar um servidor MCP manualmente, o Agent Registry registra o endpoint. No entanto, ele não faz a introspecção automática do servidor para determinar quais ferramentas estão disponíveis. Para permitir que os usuários descubram as ferramentas exatas disponíveis no seu servidor MCP, forneça as especificações delas durante o registro enviando um arquivo toolspec.json.

Antes de começar

Antes de começar, configure o Agent Registry. Você precisa do ID do projeto para realizar essas tarefas.

Para usar os comandos da CLI gcloud neste documento, configure seu ambiente da Google Cloud CLI.

Funções exigidas

Para receber as permissões necessárias para registrar servidores MCP manualmente no Agent Registry, peça ao administrador para conceder a você o papel do IAM de Editor da API Agent Registry (roles/agentregistry.editor) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Prepare a especificação da ferramenta

Crie um arquivo toolspec.json que descreva as ferramentas fornecidas pelo servidor. O tamanho máximo do arquivo de especificação é de 10 KB.

O arquivo JSON precisa estar alinhado à especificação do MCP para esquemas de ferramentas, por exemplo:

{
  "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
      }
    }
  ]
}

Para requisitos estruturais detalhados, consulte Esquemas JSON e a referência REST.

Registrar o servidor e as ferramentas

Registre o servidor MCP e faça upload da definição da ferramenta simultaneamente:

Console

No console do Google Cloud , acesse Registro de agentes:

Acessar o Agent Registry
No seletor de projetos, escolha o projeto Google Cloud em que você configurou o Agent Registry.
Selecione a guia Servidores MCP.
Clique em Adicionar servidor MCP.
No painel Detalhes do servidor MCP, insira o nome de exibição, uma descrição e a região geográfica.
Na seção Especificação da ferramenta, insira o URL do endpoint do servidor MCP e cole o conteúdo do arquivo toolspec.json.

Se quiser, clique em Importar ferramentas neste painel para importar as ferramentas do MCP do URL. Essa opção só funciona se o URL do endpoint do seu servidor MCP estiver hospedado publicamente na Internet. Não é possível usar esse recurso para importar ferramentas de servidores MCP hospedados de forma privada.
Clique em Próxima.

O painel Selecionar ferramentas do MCP mostra uma lista de ferramentas com nomes e descrições do seu servidor MCP.
Selecione todas as ferramentas do MCP que você quer incluir. É possível filtrar as ferramentas da lista por nome ou valor.
Clique em Salvar.

gcloud

Registre o servidor MCP com a especificação da ferramenta:

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

Substitua:

SERVER_NAME: o nome que você quer dar ao servidor MCP, por exemplo, custom-mcp-server.
PROJECT_ID: o ID do projeto.
REGION: a região do registro.
DISPLAY_NAME: o nome legível que você quer dar ao servidor, por exemplo, Custom MCP Server.
SERVER_URL: o URL do endpoint do servidor MCP, por exemplo, https://api.example.com/mcp.
PROTOCOL: a vinculação de protocolo para o endpoint. Os valores válidos são JSONRPC, HTTP_JSON ou GRPC. Para servidores MCP, esse valor geralmente é JSONRPC.

Terraform

Para registrar um servidor MCP e especificar as ferramentas dele, configure um recurso google_agent_registry_service com o bloco 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    = "NO_SPEC"
  }
}

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