Use o servidor MCP remoto de recuperação de agente para se conectar à IA e a aplicativos personalizados

O Protocolo de Contexto de Modelo (MCP) padroniza como os modelos de linguagem grandes (LLMs) e os aplicativos ou agentes de IA se conectam a fontes de dados externas. Os servidores MCP permitem que você use 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 que os aplicativos de IA se comuniquem entre o cliente MCP de IA e o servidor MCP. Para mais informações sobre a arquitetura do MCP, consulte Arquitetura do MCP.

Núcleo sem estado

Com a versão 2026-07-28 do MCP, o MCP muda de um protocolo bidirecional com estado para um protocolo sem estado. Cada solicitação do MCP é autodescritiva e pode ser roteada usando cabeçalhos. Não é necessário o handshake initialize/initialized ou Mcp-Session-Id porque cada solicitação inclui todas as informações necessárias nos cabeçalhos HTTP ou no parâmetro _meta. Os servidores MCP podem solicitar mais informações necessárias para uma ferramenta usando solicitações de ida e volta (MRTR, na sigla em inglês).

Para ajudar a rotear e processar solicitações sem analisar o corpo da solicitação, alguns cabeçalhos do MCP são necessários, incluindo os seguintes:

• Cabeçalhos exigidos pela especificação do MCP, como o cabeçalho da versão do protocolo e os cabeçalhos da solicitação padrão.
• Cabeçalhos personalizados definidos pelo servidor MCP. Esses cabeçalhos são espelhados em cabeçalhos HTTP do esquema de entrada da ferramenta usando a propriedade x-mcp-header. Por exemplo, um servidor MCP pode definir um cabeçalho personalizado para especificar a região do Cloud de Confiance by S3NS ou o ID do projeto.

Para mais informações sobre a arquitetura do MCP, consulte a especificação e as principais mudanças da versão 2026-07-28 do MCP.

Servidores MCP remotos do Google e do Cloud de Confiance by S3NS

• 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
• Geração de registros de auditoria centralizada

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

Antes de começar

1. In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance 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

2. 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.

3. Ative a API Agent Retrieval, se ainda não estiver ativada.

   Funções necessárias para ativar APIs

   Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

   Ativar a API

Funções exigidas

Para receber as permissões necessárias para usar o servidor MCP de recuperação de agentes, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto em que você quer usar o servidor MCP de recuperação de agentes:

• Fazer chamadas de ferramenta do MCP: Usuário da ferramenta MCP (roles/mcp.toolUser)
• Ler recursos de recuperação de agentes: Leitor da busca vetorial (roles/vectorsearch.viewer)

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 de recuperação de agentes. 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.

O servidor MCP de recuperação de agentes expõe apenas ferramentas somente leitura. Não são necessárias permissões de gravação.

Autenticação e autorização

O servidor MCP de recuperação de agentes usa o protocolo OAuth 2.0 com o IAM para autenticação e autorização. Todas as identidades doCloud de Confiance by S3NS são compatíveis com a autenticação em servidores MCP.

Recomendamos que você crie uma identidade separada para os 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 MCP.

Escopos do OAuth do MCP de recuperação de agentes

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

O servidor MCP de recuperação de agentes aceita o seguinte escopo OAuth:

Configurar um cliente MCP para usar o servidor MCP de recuperação de agentes

Os aplicativos e agentes de IA, como o Claude ou o Antigravity, 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. 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 seu aplicativo de IA, procure uma maneira de adicionar ou se conectar a um servidor MCP remoto. Para o servidor MCP de recuperação de agentes, insira as seguintes informações conforme necessário:

• Nome do servidor: servidor MCP de recuperação de agentes

• URL do servidor ou Endpoint: https://vectorsearch.googleapis.com/mcp

  Esse endpoint único expõe todas as nove ferramentas de MCP de recuperação de agentes. As chamadas de ferramenta são enviadas para o back-end correto pelo roteamento baseado em cabeçalho.

• Transporte: HTTP com streaming

• Detalhes de autenticação: suas credenciais do Cloud de Confiance by S3NS , seu ID e chave secreta do cliente OAuth ou uma identidade e credenciais de agente. Para mais informações sobre autenticação, consulte Autenticar em servidores MCP.

Roteamento com base em cabeçalho e requisitos de protocolo do cliente

O servidor MCP de recuperação de agentes envia cada tools/call na borda da rede com base em dois cabeçalhos HTTP:

• Mcp-Name: precisa ser igual ao nome da ferramenta no corpo da solicitação (params.name).
• Mcp-Param-Region: precisa ser igual ao componente location do caminho do recurso no corpo da solicitação (por exemplo, us-central1 para uma coleção em projects/PROJECT_ID/locations/us-central1/collections/COLLECTION_ID).

Se um dos cabeçalhos estiver ausente ou não corresponder ao corpo, a solicitação será rejeitada com HTTP 400 Bad Request.

Seu cliente do MCP precisa emitir esses cabeçalhos dinamicamente por tools/call. Esse comportamento é padronizado na versão 2026-07-28 e posteriores do protocolo MCP. Verifique se a biblioteca de cliente do MCP anuncia pelo menos essa versão do protocolo durante o handshake initialize. Os clientes fixados em versões anteriores do protocolo ou do SDK que não oferecem suporte à emissão de cabeçalho dinâmico não podem usar o servidor MCP de recuperação de agente pelo endpoint unificado /mcp.

URIs de redirecionamento

Para aplicativos baseados na Web e alguns aplicativos para computador, é necessário incluir um URI de redirecionamento na lista de permissões ao criar um ID do cliente e uma chave secreta 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 deve especificar o URI de redirecionamento que você precisa usar. URIs de redirecionamento personalizados não são compatíveis.

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

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

• Conexão com servidores MCP remotos.
• Configurar o MCP em um aplicativo de IA.

Ferramentas disponíveis

O servidor MCP de recuperação de agentes expõe nove ferramentas somente leitura:

Todas as ferramentas são somente leitura. O servidor MCP não expõe operações de gravação, atualização ou exclusão em recursos de recuperação de agentes.

Listar ferramentas

Use o inspetor do MCP para listar ferramentas ou envie uma solicitação HTTP tools/list diretamente ao servidor MCP de recuperação de agentes. O método tools/list não requer autenticação.

O servidor MCP de recuperação de agentes é compatível com o protocolo sem estado MCP 2026-07-28. Portanto, cada solicitação sem estado é autodescritiva e precisa declarar a versão do protocolo no cabeçalho HTTP MCP-Protocol-Version e no campo de corpo _meta.io.modelcontextprotocol/protocolVersion, além de um objeto _meta.io.modelcontextprotocol/clientCapabilities (um objeto vazio é aceito). O cabeçalho HTTP Mcp-Method também precisa corresponder ao method no corpo.

curl -X POST 'https://vectorsearch.googleapis.com/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/list' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientCapabilities": {}
      }
    }
  }'

Exemplos de casos de uso

Confira a seguir exemplos de casos de uso do servidor MCP de recuperação de agentes:

• Inspeção de recursos: listar coleções e índices em um projeto e inspecionar os esquemas e metadados deles.
• Pesquisa vetorial e semântica: execute uma pesquisa vetorial ou semântica em uma coleção para encontrar os objetos de dados mais relevantes para uma consulta.
• Recuperação híbrida: combine pesquisas semânticas, de texto e vetoriais em uma única chamada em lote e mescle os resultados com a Reciprocal Rank Fusion (RRF) ou a API Vertex Ranking.
• Recuperação de objetos de dados: recupere objetos de dados individuais por ID ou consulte uma coleção por filtro para inspecionar registros ingeridos.

Comandos de amostra

• "Liste as coleções de recuperação de agentes no projeto PROJECT_ID em REGION."
• "Mostrar o esquema da coleção COLLECTION_ID na região REGION."
• "Execute uma pesquisa semântica na coleção COLLECTION_ID para QUERY_TEXT e retorne os 5 vizinhos mais próximos."
• "Faça uma pesquisa híbrida na coleção COLLECTION_ID para QUERY_TEXT que combine pesquisa semântica e de texto, depois reordene os 50 principais com semantic-ranker-fast@latest."
• "Receba o objeto de dados com o ID DATA_OBJECT_ID da coleção COLLECTION_ID."

Nos comandos, substitua o seguinte:

• PROJECT_ID: o ID do projeto do Cloud de Confiance
• REGION: a região da coleção (por exemplo, us-central1)
• COLLECTION_ID: o ID da coleção de recuperação de agentes
• DATA_OBJECT_ID: o ID de um objeto de dados na coleção.
• QUERY_TEXT: o texto em linguagem natural da consulta.

Cotas e limites

O servidor MCP de recuperação de agentes não tem cotas próprias. Não há limite para o número de chamadas que podem ser feitas ao servidor MCP. Você ainda está sujeito às cotas aplicadas pela API Recuperação de Agentes, que as ferramentas do servidor MCP chamam em seu nome. Para mais informações, consulte Cotas de recuperação do agente.

A seguir

• Consulte a referência do MCP de recuperação de agentes.
• Saiba como criar uma coleção.
• Saiba como pesquisar objetos de dados.
• Saiba como reclassificar os resultados da pesquisa.
• Saiba mais sobre os servidores MCP do Google Cloud.