Use o servidor MCP remoto do Pub/Sub para gerenciar recursos do Pub/Sub e publicar mensagens

Este documento descreve como usar o servidor MCP remoto do Pub/Sub para se conectar ao Pub/Sub de aplicativos de IA, como a CLI do Gemini, o modo agente no Gemini Code Assist, o Claude Code ou em aplicativos de IA que você está desenvolvendo.

O servidor MCP do Pub/Sub permite gerenciar recursos do Pub/Sub e publicar mensagens. É possível criar, listar, receber, atualizar e excluir tópicos, assinaturas e snapshots do Pub/Sub, além de publicar mensagens em tópicos.

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 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 MCP locais e remotos?

Servidores 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 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 MCP de IA e o servidor MCP. Para mais informações sobre a arquitetura do MCP, consulte Arquitetura do MCP.

Servidores MCP do Google e Google Cloud remotos

• Descoberta simplificada e centralizada.
• Endpoints HTTP globais ou regionais gerenciados.
• Autorização detalhada.
• Comandos e respostas de segurança opcionais com a proteção do Model Armor.
• Registro de auditoria centralizado.

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

Antes de começar

Faça login na sua Google Cloud conta do. Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho dos nossos produtos em situações 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.

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.

1. Ative a API Pub/Sub.

   Funções necessárias para ativar APIs

   Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.

   Ativar a API

Funções exigidas

Para receber as permissões necessárias para usar o servidor MCP do Pub/Sub, peça que o administrador conceda a você os seguintes papéis do IAM no projeto em que você quer usar o servidor MCP:

• Fazer chamadas de ferramentas MCP: Usuário da ferramenta MCP (roles/mcp.toolUser)
• Criar, atualizar e excluir recursos do Pub/Sub: editor do Pub/Sub (roles/pubsub.editor)

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para usar o servidor MCP do Pub/Sub. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

As permissões necessárias do Pub/Sub dependem da operação específica que você quer realizar. Para mais informações, consulte Papéis e permissões do Pub/Sub.

Autenticação e autorização

O servidor MCP remoto do Pub/Sub usa o protocolo OAuth 2.0 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 MCP.

O Pub/Sub não aceita chaves de API como método de autenticação.

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

Escopos do OAuth do MCP do Pub/Sub

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 Pub/Sub tem os seguintes escopos do OAuth da ferramenta MCP:

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

Configurar um cliente MCP para usar o servidor MCP do Pub/Sub

Aplicativos e agentes de IA, como o Claude ou a CLI do Gemini, podem instanciar um cliente MCP que se conecta a um único servidor MCP. Um aplicativo de IA pode ter vários clientes que se conectam a diferentes servidores MCP. Para se conectar a um servidor MCP remoto, o cliente MCP precisa do URL do servidor MCP remoto.

No aplicativo de IA, procure uma maneira de se conectar a um servidor MCP remoto. Você vai receber uma solicitação para inserir detalhes sobre o servidor, como nome e URL.

Para o servidor MCP do Pub/Sub, insira o seguinte conforme necessário:

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

Para orientações específicas do host, consulte o seguinte:

• Claude.ai
• CLI do Gemini

Para adicionar o servidor MCP do Pub/Sub à CLI do Gemini, o arquivo de extensão precisa conter o seguinte:

{
  "name": "EXT_NAME",
  "version": "1.0.0",
  "mcpServers": {
    "MCP_SERVER_NAME": {
      "httpUrl": "https://pubsub.googleapis.com/mcp",
      "authProviderType": "google_credentials",
      "oauth": {
        "scopes": ["https://www.googleapis.com/auth/pubsub"]
      },
      "timeout": 30000,
      "headers": {
        "x-goog-user-project": "PROJECT_ID"
      }
    }
  }
}

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

• Conectar-se a servidores MCP remotos
• Configurar o MCP em um aplicativo de IA

Ferramentas disponíveis

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

Listar ferramentas

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

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

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

Exemplos de casos de uso

Confira abaixo exemplos de casos de uso do servidor MCP do Pub/Sub:

• Criar um pipeline do Pub/Sub que inclua um tópico com assinaturas.

• Criar uma assinatura que use recursos do Pub/Sub, como filtragem de mensagens.

• Adicionar transformações de mensagens únicas (SMTs) ao pipeline do Pub/Sub.

Comandos de amostra

• Crie um pipeline que consuma mensagens do tópico my-topic do Pub/Sub, filtre as mensagens que têm o atributo priority=low e grave as mensagens no bucket my-bucket do Cloud Storage.

• Crie uma assinatura do tópico my-topic para a tabela my-table do BigQuery, com entregas com falha enviadas para my-dead-letter-topic.

Configurações opcionais de segurança e proteção

O MCP introduz novos riscos e considerações de segurança devido à grande variedade de ações que podem ser realizadas com as ferramentas MCP. Para minimizar e gerenciar esses riscos, Google Cloud o oferece políticas padrão e personalizáveis para controlar o uso de ferramentas MCP na sua Google Cloud organização ou projeto.

Para mais informações sobre segurança e governança do MCP, consulte Segurança e proteção de IA.

Usar o Model Armor

O Model Armor é um Google Cloud serviço projetado para aumentar a segurança e a segurança dos aplicativos de IA. Ele funciona examinando proativamente comandos e respostas de LLMs, protegendo contra vários riscos e oferecendo suporte a práticas de IA responsável. Se você estiver implantando a IA no ambiente de nuvem ou em provedores de nuvem externos, o Model Armor poderá ajudar a evitar entradas mal-intencionadas, verificar a segurança do conteúdo, proteger dados sensíveis, manter a conformidade e aplicar suas políticas de segurança de IA de maneira consistente em todo o cenário de IA.

O Model Armor está disponível apenas em locais regionais específicos. Se o Model Armor estiver ativado para um projeto e uma chamada para esse projeto vier de uma região não aceita, o Model Armor fará uma chamada entre regiões. Para mais informações, consulte Locais do Model Armor.

Ativar o Model Armor

É necessário ativar as APIs do Model Armor antes de usar o Model Armor.

Configurar a proteção para servidores MCP do Google e Google Cloud remotos

Para ajudar a proteger as chamadas e respostas da ferramenta MCP, use as configurações mínimas do Model Armor. Uma configuração mínima define os filtros de segurança mínimos que se aplicam ao projeto. Essa configuração aplica um conjunto consistente de filtros a todas as chamadas e respostas de ferramentas MCP no projeto.

Configure uma configuração mínima do Model Armor com a higienização do MCP ativada. Para mais informações, consulte Configurar as configurações mínimas do Model Armor.

Consulte o comando de exemplo a seguir:

gcloud model-armor floorsettings update \
--full-uri='projects/PROJECT_ID/locations/global/floorSetting' \
--enable-floor-setting-enforcement=TRUE \
--add-integrated-services=GOOGLE_MCP_SERVER \
--google-mcp-server-enforcement-type=INSPECT_AND_BLOCK \
--enable-google-mcp-server-cloud-logging \
--malicious-uri-filter-settings-enforcement=ENABLED \
--add-rai-settings-filters='[{"confidenceLevel": "MEDIUM_AND_ABOVE", "filterType": "DANGEROUS"}]'

Substitua PROJECT_ID pelo ID do Google Cloud projeto.

Observe as seguintes configurações:

• INSPECT_AND_BLOCK: o tipo de aplicação que inspeciona o conteúdo do servidor MCP do Google e bloqueia comandos e respostas que correspondem aos filtros.
• ENABLED: a configuração que ativa um filtro ou aplicação.
• MEDIUM_AND_ABOVE: o nível de confiança para as configurações de filtro de IA responsável - perigoso. É possível modificar essa configuração, embora valores mais baixos possam resultar em mais falsos positivos. Para mais informações, consulte Níveis de confiança do Model Armor.

Desativar a verificação do tráfego do MCP com o Model Armor

Se você quiser interromper a verificação do tráfego do MCP do Google com o Model Armor, execute o comando a seguir:

gcloud model-armor floorsettings update \
  --full-uri='projects/PROJECT_ID/locations/global/floorSetting' \
  --remove-integrated-services=GOOGLE_MCP_SERVER

Substitua PROJECT_ID pelo Google Cloud ID do projeto.

O Model Armor não vai verificar o tráfego do MCP no projeto.

Controlar o uso do MCP com políticas de negação do IAM

As políticas de negação do Identity and Access Management (IAM) ajudam a proteger Google Cloud servidores MCP remotos. Configure essas políticas para bloquear o acesso indesejado à ferramenta MCP.

Por exemplo, é possível negar ou permitir o acesso com base em:

• O principal
• Propriedades da ferramenta, como somente leitura
• O ID do cliente OAuth do aplicativo

Para mais informações, consulte Controlar o uso do MCP com o Identity and Access Management.

A seguir

• Leia a documentação de referência do MCP do Pub/Sub.
• Saiba mais sobre os servidores MCP do Google Cloud.