O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Registrar servidores MCP

O Agent Registry permite registrar servidores do Protocolo de Contexto de Modelo (MCP, na sigla em inglês) de forma automática ou manual para que desenvolvedores e agentes orquestradores possam descobrir e invocar ferramentas padronizadas em todo o ecossistema de IA.

O registro automático de servidores MCP personalizados implantados no Google Kubernetes Engine (GKE) ou no Cloud Run só descobre recursos implantados no projeto de governança em que o Agent Registry está ativado. Para registrar servidores MCP personalizados implantados em projetos Google Cloud separados ou hospedados externamente, consulte Registrar servidores MCP externos.

Descoberta automática de servidores MCP

Os servidores MCP remotos do Google e do Google Cloud são registrados e ingeridos automaticamente no Agent Registry.

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

Local e condições

Quando o Agent Registry registra automaticamente um servidor MCP remoto do Google ou do Google Cloud, ele cria o recurso McpServer apenas no local global, não em regiões individuais, como us-central1. Se o serviço fornecer endpoints regionais (REPs), o Agent Registry vai listar esses URLs regionais no campo interfaces desse único recurso global McpServer.

Como o recurso registrado automaticamente existe apenas em global, lembre-se das seguintes condições ao consultar o servidor ou configurar as políticas de acesso do Identity-Aware Proxy (IAP):

Use global para servidores registrados automaticamente: especifique o local global ao consultar o servidor no Agent Registry com --location=global ou aplique políticas do IAP a ele com --region=global. Se você especificar uma região como us-central1, o comando vai retornar um erro NOT_FOUND porque não há um recurso regional McpServer por padrão.
Registrar manualmente em uma região para residência de dados: se você precisar manter os metadados do registro em uma região específica, registre manualmente o servidor MCP e o URL do endpoint regional nessa região e, em seguida, aplique a política do IAP nessa mesma região.

Para mais informações, consulte Escopo de governança em locais regionais e globais e Servidor MCP remoto não encontrado em um local regional.

Antes de começar

Configure o Agent Registry.
Consiga o ID do projeto para o projeto de governança em que o Agent Registry está ativado.
Para usar os comandos da Google Cloud CLI neste documento, configure o ambiente da CLI gcloud.

Funções exigidas

Para receber as permissões necessárias para registrar servidores MCP 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 de governança em que o Agent Registry está ativado. 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.

Registrar servidores MCP do GKE

Para registrar servidores MCP personalizados implantados no GKE, adicione os rótulos e as anotações do Kubernetes necessários ao manifesto de implantação. O exemplo a seguir mostra um manifesto de implantação do servidor MCP do GKE configurado para registro automático:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-mcp-server
  labels:
    # GKE takes this label and registers the deployment as an MCP server
    registry.gke.io/functional-type: "MCP_SERVER"
  annotations:
    # 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
      annotations:
        # Agent Identity annotation for identity and access management
        iam.gke.io/spiffe-identity-type: agent-identity
    spec:
      containers:
      - name: server
        image: gcr.io/PROJECT_ID/my-mcp-server:1.0.0

Substitua PROJECT_ID pelo Google Cloud ID do projeto.

Para configurar e aplicar o manifesto de implantação, faça o seguinte:

No metadata.labels do manifesto Deployment, adicione o rótulo registry.gke.io/functional-type: "MCP_SERVER".

Observação: o GKE também é compatível com a anotação apphub.cloud.google.com/functional-type: "MCP_SERVER" para compatibilidade com versões anteriores. No entanto, use o rótulo registry.gke.io/functional-type: "MCP_SERVER" para as implantações do GKE.
No metadata.annotations do manifesto Deployment, ative a descoberta automatizada das ferramentas do MCP fornecendo as anotações modelcontextprotocol.info/urls e modelcontextprotocol.info/capabilities para declarar os URLs de endpoint do servidor e os detalhes de capacidade.
Em spec.template.metadata.annotations do modelo de pod, ative a comunicação autenticada configurando a Identidade do agente com a anotação iam.gke.io/spiffe-identity-type: agent-identity.
Aplique o manifesto de implantação ao cluster.

Quando você aplica a implantação, o GKE tenta automaticamente obter a especificação da ferramenta do servidor e registra o servidor e as ferramentas dele diretamente em um recurso de descoberta McpServer somente leitura no Agent Registry. O Agent Registry usa o nome da implantação como o nome de exibição do servidor MCP.

Registrar servidores MCP do Cloud Run

É possível registrar automaticamente servidores MCP personalizados ao implantá-los como serviços do Cloud Run especificando a flag --functional-type=mcp-server. A flag --functional-type=mcp-server identifica o serviço do Cloud Run como um servidor MCP, em vez de uma carga de trabalho conteinerizada padrão, instruindo o Cloud Run a registrar o servidor no Agent Registry. Durante o registro, o Cloud Run adiciona automaticamente o nome do servidor e o tipo MCP_SERVER ao registro.

Também é possível especificar um tipo de identidade usando a flag --identity-type. Por exemplo, especifique uma identidade agent-identity ou service-account. Se não for especificado, a carga de trabalho usará uma identidade de conta de serviço por padrão.

Para configurar o registro automático em um serviço novo ou atual do Cloud Run, consulte Configurar os recursos da Gemini Enterprise Agent Platform para o Cloud Run. Para implantar e proteger servidores MCP no Cloud Run, consulte Hospedar servidores MCP no Cloud Run e Autenticar servidores MCP.

Registrar servidores MCP externos

Para gerenciar e reutilizar ferramentas fornecidas por servidores externos ou APIs personalizadas, é necessário registrar manualmente 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 que os usuários descubram as ferramentas exatas disponíveis no seu servidor MCP, forneça as especificações das ferramentas durante o registro fazendo upload de um arquivo toolspec.json.

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 com a 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 ao mesmo tempo:

Console

No console do Google Cloud , acesse Agent Registry:

Acessar o Agent Registry
No seletor de projetos, selecione o projeto do 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 nesse 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 particular.
Clique em Próxima.

O painel Selecionar ferramentas 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

As flags de especificação usadas determinam a qual coleção de recursos o componente pertence. Para um mapeamento completo de flags para coleções de recursos, consulte [Recursos de serviço e recursos de descoberta](/agent-registry/data-model#service-resources).

Registre o servidor MCP com a especificação da ferramenta usando o comando gcloud agent-registry services create:

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. O nome precisa ter de 4 a 63 caracteres e pode conter apenas letras minúsculas, números e hífens.
PROJECT_ID: o ID do projeto;
REGION: a região do registro.
DISPLAY_NAME: o nome legível por humanos 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 do endpoint. Os valores válidos são jsonrpc, http-json ou grpc. Para servidores MCP, esse valor geralmente é jsonrpc.

Terraform

O bloco de especificação que você configura determina a qual coleção de recursos seu componente pertence. Para um mapeamento completo de especificações para coleções de recursos, consulte [Recursos de serviço e recursos de descoberta](/agent-registry/data-model#service-resources).

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 McpServer resource name."
  value       = google_agent_registry_service.mcp_server.registry_resource
}