Registrar servidores MCP

O Agent Registry funciona como um catálogo centralizado, registrando e gerenciando endpoints de servidor 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 deles são gerenciadas no Agent Registry.

Descoberta automática de Google Cloud servidores MCP

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

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

Observação: se sua organização usa o hub de APIs da Apigee, é possível configurá-lo para sincronizar automaticamente as APIs no estilo MCP com o Agent Registry. Verifique se a sincronização está ativada no hub de APIs para manter os dados importados da API MCP no Agent Registry. Para mais informações, consulte Registrar APIs MCP.

Escopo e vinculações para servidores MCP gerenciados pelo Google

Os servidores MCP remotos gerenciados pelo Google são registrados automaticamente no local global do seu projeto. Como esses servidores integrados do Google residem globalmente, é necessário aplicar todas as vinculações do Identity and Access Management (IAM) para eles no escopo global, especificando a flag --region=global. As vinculações regionais do IAM, como --region=us-central1, não são compatíveis com esses servidores MCP remotos globais e retornam um erro NOT_FOUND.

Registrar servidores MCP do GKE

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

Observação: o GKE também oferece suporte à anotação apphub.cloud.google.com/functional-type: "MCP_SERVER" para compatibilidade com versões anteriores. No entanto, recomendamos usar o registry.gke.io/functional-type: "MCP_SERVER" rótulo para as implantações do GKE.

Para permitir que o Agent Registry execute uma verificação de introspecção e descubra suas ferramentas MCP, a implantação também precisa incluir anotações que declaram os URLs de endpoint e os detalhes de capacidade 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 receber a especificação da ferramenta do servidor e registra as ferramentas diretamente no modelo de dados do Agent Registry.

**Observação** :ao implantar um servidor MCP no GKE, o nome do servidor poderá aparecer como UNKNOWN no Agent Registry. Esse comportamento não afeta a funcionalidade do servidor MCP nem a capacidade de descoberta das ferramentas dele.

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 inspeciona automaticamente o servidor para determinar quais ferramentas estão disponíveis. Para permitir que os usuários descubram as ferramentas exatas disponíveis no servidor MCP, é necessário fornecer as especificações da ferramenta durante o registro, fazendo upload de um arquivo toolspec.json.

Aviso: esse recurso não é compatível com os locais de multirregião us e eu. É necessário usar uma região compatível ou o local global. Para mais informações, consulte Locais do Agent Registry.

Antes de começar

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

Para usar os comandos da CLI gcloud neste documento, verifique se você tem configurado o 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ê opapel 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 com papéis personalizados ou outros papéis predefinidos.

Preparar 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

1. No Google Cloud console, acesse o Agent Registry:

   Acessar o Agent Registry

2. No seletor de projetos, selecione o Google Cloud projeto em que você configurou o Agent Registry.

3. Selecione a guia Servidores MCP.

4. Clique em Adicionar servidor MCP.

5. No painel Detalhes do servidor MCP , insira o nome de exibição, uma descrição e a região geográfica.

6. Na seção Especificação da ferramenta, insira o URL do endpoint do servidor MCP e cole o conteúdo do arquivo toolspec.json.

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

7. Clique em Próxima.

   O painel Selecionar ferramentas MCP mostra uma lista de ferramentas com nomes e descrições do servidor MCP.

8. Selecione todas as ferramentas MCP que você quer incluir. É possível filtrar as ferramentas da lista por nome ou valor.

9. 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    = "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
}

Substitua:

• REGION: a região do registro.
• SERVER_NAME: o nome que você quer dar ao servidor MCP, por exemplo, custom-mcp-server.
• 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.

Verificar o registro

Liste, filtre e confira os detalhes do servidor MCP recém-registrado. Para confirmar se o servidor MCP foi registrado, você pode listar os servidores no registro.