Gerenciar servidores e ferramentas do MCP

O Agent Registry permite inspecionar, atualizar e remover servidores e ferramentas registrados do Protocolo de Contexto de Modelo (MCP, na sigla em inglês) para que seus agentes tenham esquemas de ferramentas e endpoints precisos no ambiente de execução. É possível descobrir servidores MCP registrados de forma automática e manual, atualizar definições de ferramentas registradas manualmente e remover servidores MCP que não estão mais em uso.

Antes de começar

  1. Configure o Agent Registry.

  2. Para uma configuração de projeto único, use o ID do projeto do projeto de governança em que o Agent Registry está ativado. Se você configurou um limite de gerenciamento para vários projetos, use o ID do projeto de gerenciamento para descoberta e registro em todo o limite ou especifique um ID de projeto de membro para operações de projeto único.

  3. Registrar servidores MCP no Agent Registry.

  4. 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 gerenciar servidores MCP e ferramentas no Agent Registry, peça ao administrador para conceder a você os seguintes papéis do IAM 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.

Descobrir servidores e ferramentas MCP disponíveis

Depois de registrar os servidores MCP, você pode descobri-los para vinculá-los aos seus agentes.

Listar todos os servidores MCP disponíveis

É possível listar todos os servidores MCP registrados no seu ambiente e conferir as configurações detalhadas deles, como endpoints e metadados associados.

Se você configurou um limite de gerenciamento, é possível listar servidores MCP em vários projetos do seu projeto de gerenciamento.

Para listar todos os servidores MCP no seu ambiente, faça o seguinte:

Console

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

    Acessar o Agent Registry

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

  3. Selecione a guia Servidores MCP.

    A página mostra uma lista de todos os servidores MCP registrados e os detalhes deles, como nome, identificador, descrição, ambiente de execução e local.

  4. Para ver os detalhes completos de um servidor, clique no nome dele.

gcloud

Para listar todos os servidores MCP em um local específico, execute o comando gcloud agent-registry mcp-servers list:

gcloud agent-registry mcp-servers list \
    --project=PROJECT_ID \
    --location=REGION

Substitua:

  • PROJECT_ID: o ID do projeto; Se você configurou um limite de gerenciamento, especifique o ID do seu projeto de gerenciamento para listar os servidores MCP no local especificado em todos os projetos membros no limite. Cada nome de recurso retornado preserva o ID do servidor MCP e usa o projeto especificado na solicitação.
  • REGION: o local do registro, como us-central1, eu ou global. Em um projeto de gerenciamento, especificar um local agrega servidores MCP nesse mesmo local em todos os projetos membros no limite.

Filtrar servidores MCP registrados

Se você tiver vários servidores ou quiser confirmar o registro de um servidor específico, filtre a lista pelos metadados do servidor:

Console

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

    Acessar o Agent Registry

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

  3. Selecione a guia Servidores MCP.

    A página mostra uma lista de todos os servidores MCP registrados e os detalhes deles, como nome, identificador, descrição, ambiente de execução e local.

  4. Para filtrar por local, clique no menu Local, selecione os locais que você quer filtrar e clique em Aplicar.

    A página mostra uma lista filtrada dos servidores MCP registrados para as condições selecionadas.

gcloud

Filtre sua lista para retornar apenas recursos que correspondam a metadados específicos transmitindo a flag --filter para o comando gcloud agent-registry mcp-servers list:

gcloud agent-registry mcp-servers list \
    --project=PROJECT_ID \
    --location=REGION \
    --filter="FILTER_EXPRESSION"

Substitua:

  • PROJECT_ID: o ID do projeto;
  • REGION: a região do registro.
  • FILTER_EXPRESSION: a expressão de filtro para os servidores MCP que você quer filtrar. Por exemplo, é possível usar os seguintes filtros:
    • Para filtrar por nome de exibição, use displayName='DISPLAY_NAME'.
    • Para pesquisar pelo identificador de servidor MCP globalmente exclusivo (URN), use mcpServerId='urn:mcp:SERVER_URN'.
    • Para filtrar por um projeto membro específico ao consultar um projeto de gerenciamento, use project_id=MEMBER_PROJECT_ID.

Terraform

Para recuperar um servidor MCP registrado específico filtrando os metadados, configure a fonte de dados google_agent_registry_mcp_server com o argumento filter:

data "google_agent_registry_mcp_server" "filtered_mcp_server" {
  location = "REGION"
  filter   = "displayName=\"DISPLAY_NAME\""
}

Substitua:

  • REGION: a região do registro.
  • DISPLAY_NAME: o nome legível por humanos do servidor MCP para filtrar, por exemplo, Custom MCP Server.

Ver detalhes de um servidor MCP

Confira os detalhes de um servidor MCP específico, por exemplo, as ferramentas dele:

Console

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

    Acessar o Agent Registry

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

  3. Selecione a guia Servidores MCP.

    A página mostra uma lista de todos os servidores MCP registrados e os detalhes deles, como nome, identificador, descrição, ambiente de execução e local.

  4. Clique no nome do servidor MCP que você quer visualizar.

    A página de detalhes inclui guias para os detalhes do servidor MCP.

  5. Clique na guia correspondente para ver detalhes específicos do servidor MCP:

    • Visão geral: detalhes principais do servidor MCP, incluindo o nome, o identificador, o local e a descrição. A visão geral também mostra um snippet de código para você criar seus agentes usando o Kit de Desenvolvimento de Agente (ADK).
    • Observabilidade: insights sobre a integridade operacional e o uso do servidor MCP. Ele mostra métricas centradas no aplicativo, como latência, tráfego, erros e gasto de tokens. Essa guia se integra ao Google Cloud Observability para mostrar métricas de performance em tempo real e utilização no nível do sistema para ajudar você a gerenciar custos, depurar problemas e acompanhar a experiência do usuário. Para mais informações, consulte a Visão geral da observabilidade.
    • Ferramentas: os recursos fornecidos pelo servidor. Essa guia lista as funções específicas expostas por um servidor MCP que os agentes podem invocar para realizar ações específicas. Para cada ferramenta, a interface mostra o esquema, incluindo o nome, a descrição e as anotações comportamentais críticas que orientam como um agente de orquestração deve interagir com ela. Clique no nome de uma ferramenta para exibir um snippet de código que permite criar seus agentes usando o ADK.

gcloud

Para conferir os metadados detalhados de um servidor MCP específico, execute o comando gcloud agent-registry mcp-servers describe:

gcloud agent-registry mcp-servers describe SERVER_NAME \
    --project=PROJECT_ID \
    --location=REGION

Substitua:

  • SERVER_NAME: o nome do servidor MCP, por exemplo, custom-mcp-server.
  • PROJECT_ID: o ID do projeto; Em um limite de gerenciamento, é possível especificar o ID do projeto de gerenciamento ou o ID do projeto membro em que o servidor está implantado. O nome do recurso retornado preserva o ID do servidor MCP e usa o projeto especificado na solicitação.
  • REGION: a região do registro.

Terraform

Para recuperar detalhes sobre um servidor MCP registrado específico usando o ID dele, configure a fonte de dados google_agent_registry_mcp_server:

data "google_agent_registry_mcp_server" "my_mcp_server" {
  location      = "REGION"
  mcp_server_id = "SERVER_NAME"
}

output "server_create_time" {
  description = "The timestamp when the MCP server was registered."
  value       = data.google_agent_registry_mcp_server.my_mcp_server.create_time
}

output "server_update_time" {
  description = "The timestamp when the MCP server was last updated."
  value       = data.google_agent_registry_mcp_server.my_mcp_server.update_time
}

Substitua:

  • REGION: a região do registro.
  • SERVER_NAME: o identificador exclusivo do servidor MCP, por exemplo, custom-mcp-server.

Atualizar detalhes do servidor e definições de ferramentas

Se o servidor MCP adicionar novas ferramentas ou mudar os esquemas atuais, será necessário atualizar o registro para refletir essas mudanças.

No Agent Registry, os recursos McpServer são recursos de descoberta somente leitura. Para servidores MCP registrados automaticamente, atualize a implantação ou a carga de trabalho no ambiente de execução para que o Agent Registry sincronize as mudanças. Para atualizar um servidor MCP registrado manualmente, atualize o recurso Service gravável diretamente especificando o ID do projeto em que esse recurso Service foi registrado. Como o registro não inspeciona automaticamente os servidores MCP registrados manualmente, é necessário fazer o upload manual da especificação de ferramenta atualizada, que substitui as definições de ferramenta atuais do servidor.

Console

Atualize os detalhes do servidor disponíveis no console do Google Cloud :

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

    Acessar o Agent Registry

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

  3. Selecione a guia Servidores MCP.

    A página mostra uma lista de todos os servidores MCP registrados e os detalhes deles, como nome, identificador, descrição, ambiente de execução e local.

  4. Clique no nome do servidor que você quer atualizar.

  5. Na guia Visão geral do servidor, clique em Editar.

  6. No painel Editar serviço, insira as informações atualizadas do servidor, como o novo nome ou descrição.

  7. Clique em Salvar.

gcloud

Prepare a especificação da nova ferramenta. Em seguida, execute o comando gcloud agent-registry services update com o arquivo JSON atualizado:

gcloud agent-registry services update SERVER_NAME \
    --project=PROJECT_ID \
    --location=REGION \
    --mcp-server-spec-content=TOOL_SPEC

Substitua:

  • SERVER_NAME: o nome do servidor MCP, por exemplo, custom-mcp-server.
  • PROJECT_ID: o ID do projeto;
  • REGION: a região do registro.
  • TOOL_SPEC: o caminho para o novo arquivo de especificação da ferramenta, por exemplo, new-toolspec.json. O tamanho máximo do arquivo de especificação é de 10 KB.

Terraform

Para atualizar os metadados, o URL do endpoint ou a especificação da ferramenta do servidor MCP registrado, modifique os parâmetros do recurso google_agent_registry_service atual na configuração e execute terraform apply:

resource "google_agent_registry_service" "mcp_server" {
  location     = "REGION"
  service_id   = "SERVER_NAME"
  display_name = "DISPLAY_NAME"
  description  = "Updated description of the MCP server."

  interfaces {
    url              = "SERVER_URL"
    protocol_binding = "JSONRPC"
  }

  mcp_server_spec {
    type    = "TOOL_SPEC"
    content = file("TOOL_SPEC")
  }
}

Substitua:

  • REGION: a região do registro.
  • SERVER_NAME: o nome do servidor MCP, por exemplo, custom-mcp-server.
  • DISPLAY_NAME: o nome de exibição legível por humanos do servidor MCP, por exemplo, Custom MCP Server.
  • SERVER_URL: o URL do endpoint do servidor MCP, por exemplo, https://api.example.com/mcp.
  • TOOL_SPEC: o caminho para o arquivo de especificação de ferramenta atualizado, por exemplo, new-toolspec.json. O tamanho máximo do arquivo de especificação é de 10 KB.

Remover um servidor MCP

Para excluir servidores MCP que foram registrados automaticamente no Agent Registry, exclua o servidor MCP subjacente ou desative a API Google Cloud do servidor MCP no seu projeto. O servidor é removido automaticamente do registro.

Para remover um servidor MCP registrado manualmente do registro, exclua o recurso Service especificando o ID do projeto em que esse recursoService foi registrado. Essa ação remove o servidor MCP dos resultados da pesquisa e o torna indetectável para outras ferramentas:

Console

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

    Acessar o Agent Registry

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

  3. Selecione a guia Servidores MCP.

    A página mostra uma lista de todos os servidores MCP registrados e os detalhes deles, como nome, identificador, descrição, ambiente de execução e local.

  4. Clique no nome do servidor que você quer remover.

  5. Na guia Visão geral do servidor, clique em Excluir.

  6. Na caixa de diálogo de confirmação, digite DELETE para confirmar a ação.

  7. Clique em Excluir.

gcloud

Execute o comando gcloud agent-registry services delete:

gcloud agent-registry services delete SERVER_NAME \
    --project=PROJECT_ID \
    --location=REGION

Substitua:

  • SERVER_NAME: o nome do servidor MCP que você quer remover, por exemplo, my-mcp-server.
  • PROJECT_ID: o ID do projeto;
  • REGION: a região do registro.

Terraform

Remova o recurso google_agent_registry_service que representa o servidor MCP da configuração do Terraform e execute terraform apply.

Controlar o acesso à ferramenta

Implemente governança e segurança de nível empresarial para seus servidores e ferramentas MCP. Use o Agent Registry como seu registro central e o Gateway de Agente para aplicação ativa de políticas.

O Gateway de Agente permite controlar com segurança as interações entre agentes e ferramentas, independentemente de esses agentes estarem em execução no Google Cloud ou serem ferramentas para desenvolvedores externas.

Para mais informações sobre como controlar o acesso às ferramentas, consulte: