Usar o servidor MCP remoto do Resource Manager

Este documento mostra como usar o servidor do Protocolo de Contexto de Modelo (MCP) remoto do Resource Manager para se conectar a aplicativos de IA, incluindo a CLI do Gemini, o ChatGPT, o Claude e aplicativos personalizados que você está desenvolvendo. O servidor do MCP remoto do Resource Manager permite pesquisar e identificar todos os Google Cloud projetos que você tem as permissões necessárias para acessar, garantindo que você tenha os identificadores corretos antes de tentar configurações de recursos mais específicas.

A ferramenta retorna uma lista estruturada contendo o ID do projeto, o número e o estado do ciclo de vida do projeto. O servidor do MCP remoto do Resource Manager é ativado quando você ativa a API Resource Manager.

O Protocolo de Contexto de Modelo (MCP) padroniza como modelos de linguagem grandes (LLMs) e aplicativos ou agentes de IA se conectam a fontes de dados externas. Os servidores do MCP permitem usar as ferramentas, os recursos e os comandos deles para realizar ações e receber dados atualizados do serviço de back-end.

Qual é a diferença entre servidores do MCP locais e remotos?

Servidores do MCP locais
Normalmente são executados na máquina local e usam os fluxos de entrada e saída padrão (stdio) para comunicação entre serviços no mesmo dispositivo.
Servidores do MCP remotos
São executados na infraestrutura do serviço e oferecem um endpoint HTTP para aplicativos de IA para comunicação entre o cliente do MCP de IA e o servidor MCP. Para mais informações sobre a arquitetura do MCP, consulte Arquitetura do MCP.

Servidores do MCP do Google e Google Cloud remotos

Os servidores do MCP do Google e Google Cloud remotos têm os seguintes recursos e benefícios:

  • Descoberta simplificada e centralizada
  • Endpoints HTTP globais ou regionais gerenciados
  • Autorização detalhada
  • Segurança opcional de comandos e respostas com a proteção do Model Armor
  • Registro de auditoria centralizado

Para informações sobre outros servidores do MCP e sobre os controles de segurança e governança disponíveis para servidores do MCP do Google Cloud, consulte Visão geral dos servidores do MCP do Google Cloud.

Limitações

É possível usar políticas de negação do IAM para bloquear o tráfego para o serviço Resource Manager e o servidor MCP. No entanto, os atributos do IAM específicos do MCP e as permissões toolUser não podem ser usados para restringir o acesso a ferramentas para esse servidor.

Antes de começar

    Faça login na sua Google Cloud conta do. Se você não conhece o Google Cloud, crie uma conta para avaliar o desempenho dos nossos produtos em cenários reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho.

    In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

    If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

    Verify that billing is enabled for your Google Cloud project.

    Enable the Cloud Resource Manager API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

    Instale a Google Cloud CLI. Após a instalação, inicialize a Google Cloud CLI executando o seguinte comando: 

    gcloud init

    Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

    In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

    If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

    Verify that billing is enabled for your Google Cloud project.

    Enable the Cloud Resource Manager API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

    Instale a Google Cloud CLI. Após a instalação, inicialize a Google Cloud CLI executando o seguinte comando: 

    gcloud init

    Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

Autenticação e autorização

O servidor do MCP remoto do Resource Manager usa o OAuth 2.0 protocolo com o Identity and Access Management (IAM) para autenticação e autorização. Todas as Google Cloud identidades são aceitas para autenticação em servidores do MCP.

O servidor MCP do Resource Manager não aceita chaves de API para autenticação.

Recomendamos criar uma identidade separada para agentes que usam ferramentas do MCP para que o acesso aos recursos possa ser controlado e monitorado. Para mais informações sobre autenticação, consulte Autenticar em servidores do MCP.

Escopos do OAuth do MCP do Resource Manager

O OAuth 2.0 usa escopos e credenciais para determinar se um principal autenticado está autorizado a realizar uma ação específica em um recurso. Para mais informações sobre os escopos do OAuth 2.0 no Google, leia Como usar o OAuth 2.0 para acessar as APIs do Google.

O Resource Manager tem os seguintes escopos do OAuth da ferramenta MCP:

URI do escopo para a CLI gcloud Descrição
https://www.googleapis.com/auth/cloudresourcemanager.read-only Permite apenas o acesso para leitura de dados.
https://www.googleapis.com/auth/cloudresourcemanager.read-write Permite acesso para ler e modificar dados.

Outros escopos podem ser necessários nos recursos acessados durante uma chamada de ferramenta. Para conferir uma lista de escopos necessários para o Resource Manager, consulte API Resource Manager.

Configurar um cliente do MCP para usar o servidor MCP do Resource Manager

Aplicativos e agentes de IA, como o Claude ou o Antigravity, podem instanciar um cliente do MCP que se conecta a um único servidor MCP. Um aplicativo de IA pode ter vários clientes que se conectam a diferentes servidores do MCP. Se o aplicativo não estiver listado nas orientações específicas do cliente, use as informações a seguir para se conectar na maioria dos aplicativos.

No aplicativo de IA, procure uma maneira de adicionar ou se conectar a um servidor do MCP remoto. Para o servidor MCP do Resource Manager, insira as seguintes informações, conforme necessário:

  • Nome do servidor: servidor MCP do Resource Manager
  • URL do servidor ou endpoint: https://cloudresourcemanager.googleapis.com/mcp
  • Transporte: HTTP
  • Detalhes de autenticação: dependendo de como você quer autenticar, é possível inserir suas Google Cloud credenciais, o ID e a chave secreta do cliente OAuth ou uma identidade e credenciais do agente. Para mais informações sobre autenticação, consulte Autenticar em servidores do MCP.
  • Escopo do OAuth: o escopo do OAuth 2.0 que você quer usar ao se conectar ao servidor MCP do Resource Manager.

URIs de redirecionamento

Para aplicativos da Web e alguns aplicativos para computador, é necessário permitir uma lista de URIs de redirecionamento ao criar um ID e uma chave secreta do cliente para autenticação. Os URIs de redirecionamento são usados pelo servidor de autorização para enviar tokens ao aplicativo. A documentação do aplicativo precisa especificar o URI de redirecionamento que você precisa usar. URIs de redirecionamento personalizados não são compatíveis.

Para orientações específicas do aplicativo sobre como configurar e se conectar ao servidor MCP, consulte Orientações específicas do cliente.

Para orientações mais gerais, consulte os seguintes recursos:

Ferramentas disponíveis

Para conferir detalhes das ferramentas do MCP disponíveis e as descrições delas para o servidor MCP do Resource Manager, consulte a referência do MCP do Resource Manager.

Listar ferramentas

Use o inspetor do MCP para listar ferramentas ou envie uma tools/list solicitação HTTP diretamente para o Resource Manager servidor do MCP remoto. O método tools/list não exige autenticação.

POST /mcp HTTP/1.1
Host: cloudresourcemanager.googleapis.com
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "tools/list",
}

Exemplos de casos de uso

A ferramenta search_projects no servidor do MCP remoto do Resource Manager permite que os agentes de IA descubram e identifiquem dinamicamente todos os Google Cloud projetos que você tem as permissões necessárias para acessar, para que eles possam executar comandos em outras ferramentas.

A ferramenta retorna uma lista estruturada contendo o ID do projeto, o número e o estado do ciclo de vida do projeto. Confira a seguir exemplos de casos de uso para o servidor MCP do Resource Manager:

  • Inventário de recursos e auditorias de acessibilidade: liste e resuma os projetos ativos do Cloud acessíveis a você.

    Comando do usuário: "Listar todos os meus projetos ativos Google Cloud ".

    Ação do agente: o agente envia uma consulta de pesquisa ao servidor MCP para recuperar e mostrar uma lista resumida de todos os projetos ativos nas suas credenciais.

  • Pesquisas direcionadas com base no pai: recupere projetos localizados em uma pasta ou organização específica para restringir o escopo de uma solicitação.

    Comando do usuário: "Encontrar todos os projetos na pasta 223".

    Ação do agente: o agente executa uma chamada de ferramenta com a consulta parent:folders/223 para retornar uma lista de projetos dentro desse limite administrativo.

  • Resolução de contexto implícita: quando você pede informações sobre um recurso sem fornecer um ID do projeto específico, o agente pode resolver o contexto automaticamente.

    Comando do usuário: "Verificar o status do meu serviço de 'processador de pagamentos'".

    Ação do agente: o agente reconhece que um project_id está ausente para a ferramenta do Cloud Run. Ele usa a ferramenta search_projects para encontrar projetos com payment no nome, identifica projetos prováveis (como payment-prod-123) e pede sua confirmação antes de continuar.

  • Descoberta específica do ambiente: é possível encontrar projetos filtrados por ambientes ou estruturas organizacionais específicas sem sair da interface de chat.

    Comando do usuário: "A quais projetos tenho acesso no ambiente de preparação?"

    Ação do agente: o agente realiza uma operação de pesquisa para todos os projetos rotulados ou nomeados staging que você tem permissão para visualizar e retorna os IDs de projetos específicos.

Personalizar o comportamento do LLM

A ferramenta search_projects é versátil, mas os LLMs nem sempre sabem quando consultar sua Google Cloud hierarquia. Para chamar a ferramenta em cenários específicos, forneça um contexto personalizado em um arquivo Markdown, por exemplo, ~/.gemini/GEMINI.md ou um AGENTS.md para envolvidos no projeto.

A seguir