Usa el servidor de MCP remoto de Agent Retrieval para conectarte a aplicaciones personalizadas y de IA

En este documento, se muestra cómo usar el servidor remoto del Protocolo de contexto del modelo (MCP) de Gemini Enterprise Agent Platform para conectarte con aplicaciones de IA, como Gemini CLI, ChatGPT, Claude y las aplicaciones personalizadas que estás desarrollando. El servidor de MCP remoto de Agent Retrieval te permite acceder a las herramientas de Agent Retrieval y ejecutarlas para inspeccionar colecciones e índices, y realizar búsquedas vectoriales, semánticas, híbridas y de texto en tus datos desde tus entornos de desarrollo habilitados para IA y plataformas de agentes de IA. El servidor de MCP remoto de Gemini Enterprise Agent Platform se habilita cuando habilitas la API de Gemini Enterprise Agent Platform.

El Protocolo de contexto del modelo (MCP) estandariza la forma en que los modelos de lenguaje grandes (LLM) y las aplicaciones o agentes de IA se conectan a fuentes de datos externas. Los servidores de MCP te permiten usar sus herramientas, recursos y mensajes para realizar acciones y obtener datos actualizados de su servicio de backend.

¿Cuál es la diferencia entre los servidores de MCP locales y remotos?

Servidores de MCP locales
Por lo general, se ejecutan en tu máquina local y usan los flujos de entrada estándar y salida (stdio) para la comunicación entre servicios en el mismo dispositivo.
Servidores de MCP remotos
Se ejecutan en la infraestructura del servicio y ofrecen un extremo HTTP a las aplicaciones de IA para la comunicación entre el cliente de MCP de IA y el servidor de MCP. Para obtener más información sobre la arquitectura de MCP, consulta Arquitectura de MCP.

Núcleo sin estado

Con la versión 2026-07-28 del MCP, este cambia de un protocolo bidireccional con estado a un protocolo sin estado. Cada solicitud de MCP se describe a sí misma y se puede enrutar con encabezados. No es necesario el protocolo de enlace initialize/initialized ni Mcp-Session-Id, ya que cada solicitud incluye toda la información necesaria en los encabezados HTTP o el parámetro _meta. Los servidores de MCP pueden solicitar información adicional que requiere una herramienta a través de solicitudes de ida y vuelta múltiples (MRTR).

Para ayudar a enrutar y procesar las solicitudes sin analizar el cuerpo de la solicitud, se requieren algunos encabezados de MCP, incluidos los siguientes:

Para obtener más información sobre la arquitectura de MCP, consulta la especificación y los cambios clave de la versión 2026-07-28 de MCP.

Servidores de MCP remotos de Google y Cloud de Confiance by S3NS

Los servidores de MCP remotos de Google y Cloud de Confiance by S3NS tienen las siguientes características y beneficios:

  • Descubrimiento simplificado y centralizado
  • Extremos HTTP globales o regionales administrados
  • Autorización detallada
  • Seguridad opcional de instrucciones y respuestas con la protección de Model Armor
  • Registro de auditoría centralizado

Para obtener información sobre otros servidores de MCP y sobre los controles de seguridad y administración disponibles para los servidores de MCP de Google Cloud, consulta la descripción general de los servidores de MCP de Google Cloud.

Antes de comenzar

  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. Habilita la API de Agent Retrieval si aún no está habilitada.

    Roles necesarios para habilitar las APIs

    Para habilitar las APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtenerlo a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más información para otorgar roles.

    Habilitar la API

Roles obligatorios

Para obtener los permisos que necesitas para usar el servidor de MCP de recuperación de agentes, pídele a tu administrador que te otorgue los siguientes roles de IAM en el proyecto en el que quieras usar el servidor de MCP de recuperación de agentes:

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Estos roles predefinidos contienen los permisos necesarios para usar el servidor de MCP de recuperación de agentes. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para usar el servidor de MCP de recuperación de agentes:

  • Realiza llamadas a herramientas de MCP: mcp.tools.call
  • Enumera e inspecciona colecciones e índices: vectorsearch.collections.list, vectorsearch.collections.get, vectorsearch.indexes.list, vectorsearch.indexes.get
  • Lee y busca objetos de datos: vectorsearch.dataObjects.get, vectorsearch.dataObjects.query y vectorsearch.dataObjects.search

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

El servidor de MCP de recuperación de agentes solo expone herramientas de solo lectura; no se requieren permisos de escritura.

Autenticación y autorización

El servidor de MCP de recuperación de agentes usa el protocolo OAuth 2.0 con IAM para la autenticación y la autorización. Todas las identidades deCloud de Confiance by S3NS son compatibles con la autenticación en los servidores de MCP.

Te recomendamos que crees una identidad independiente para los agentes que usan herramientas de MCP, de modo que se pueda controlar y supervisar el acceso a los recursos. Para obtener más información sobre la autenticación, consulta Autentícate en servidores de MCP.

Permisos de OAuth de MCP de Agent Retrieval

OAuth 2.0 usa permisos y credenciales para determinar si un principal autenticado está autorizado a realizar una acción específica en un recurso. Para obtener más información sobre los permisos de OAuth 2.0 en Google, consulta Usa OAuth 2.0 para acceder a las APIs de Google.

El servidor de MCP de recuperación de agentes acepta el siguiente permiso de OAuth:

URI de alcance Descripción
https://www.googleapis.com/auth/cloud-platform Otorga acceso amplio a todos los servicios de Cloud de Confiance by S3NS , incluidas todas las funciones de recuperación de agentes.

Configura un cliente de MCP para que use el servidor de MCP de recuperación de agentes

Las aplicaciones y los agentes de IA, como Claude o Antigravity, pueden crear una instancia de un cliente de MCP que se conecte a un solo servidor de MCP. Una aplicación de IA puede tener varios clientes que se conecten a diferentes servidores de MCP. Si tu aplicación no aparece en la guía específica del cliente, puedes usar la siguiente información para conectarte desde la mayoría de las aplicaciones.

En tu aplicación de IA, busca una forma de agregar un servidor de MCP remoto o conectarte a él. Para el servidor de MCP de recuperación de agentes, ingresa la siguiente información según sea necesario:

  • Nombre del servidor: Servidor de MCP de Agent Retrieval

  • URL del servidor o Extremo: https://vectorsearch.googleapis.com/mcp

    Este único extremo expone las nueve herramientas de MCP de recuperación de agentes. Las llamadas a herramientas se envían al backend correcto a través del enrutamiento basado en encabezados.

  • Transport: Streamable HTTP

  • Detalles de autenticación: tus credenciales de Cloud de Confiance by S3NS , tu ID y secreto de cliente de OAuth, o una identidad y credenciales de agente. Para obtener más información sobre la autenticación, consulta Autentícate en servidores de MCP.

Requisitos del protocolo del cliente y del enrutamiento basado en encabezados

El servidor de MCP de recuperación de agentes envía cada tools/call en el perímetro de la red en función de dos encabezados HTTP:

  • Mcp-Name: Debe ser igual al nombre de la herramienta en el cuerpo de la solicitud (params.name).
  • Mcp-Param-Region: Debe ser igual al componente location de la ruta de acceso del recurso en el cuerpo de la solicitud (por ejemplo, us-central1 para una colección en projects/PROJECT_ID/locations/us-central1/collections/COLLECTION_ID).

Si falta alguno de los encabezados o no coincide con el cuerpo, la solicitud se rechaza con HTTP 400 Bad Request.

Tu cliente de MCP debe emitir estos encabezados de forma dinámica por tools/call. Este comportamiento está estandarizado en la versión 2026-07-28 del protocolo MCP y versiones posteriores. Asegúrate de que tu biblioteca cliente de MCP anuncie al menos esta versión del protocolo durante el protocolo de enlace initialize. Los clientes fijados a versiones anteriores del protocolo o versiones del SDK que no admiten la emisión dinámica de encabezados no pueden usar el servidor de MCP de recuperación de agentes a través del extremo unificado de /mcp.

Redirecciona los URI

En el caso de las aplicaciones basadas en la Web y algunas aplicaciones de escritorio, debes incluir un URI de redireccionamiento en la lista de entidades permitidas cuando crees un ID de cliente y un secreto para la autenticación. El servidor de autorización usa los URI de redireccionamiento para enviar tokens a tu aplicación. La documentación de tu aplicación debe especificar el URI de redireccionamiento que debes usar. No se admiten los URI de redireccionamiento personalizados.

Para obtener orientación específica de la aplicación sobre cómo configurar y conectarse al servidor de MCP, consulta Orientación específica del cliente.

Para obtener orientación más general, consulta los siguientes recursos:

Herramientas disponibles

El servidor de MCP de recuperación de agentes expone nueve herramientas de solo lectura:

Herramienta Descripción
list_collections Enumera las colecciones de recuperación de agentes en un proyecto y una ubicación.
get_collection Recupera el esquema y los metadatos de una colección específica.
list_indexes Enumera los índices definidos en una colección.
get_index Recupera la configuración de un índice específico.
get_data_object Recupera un objeto de datos por ID de una colección.
search_data_objects Ejecuta una búsqueda de vectores, semántica o de texto en una colección.
query_data_objects Enumera los objetos de datos que coinciden con una expresión de filtro.
batch_search_data_objects Ejecuta varias búsquedas en paralelo y combina los resultados con la fusión por clasificación recíproca (RRF) o la API de Vertex Ranking.
aggregate_data_objects Agrega objetos de datos que coincidan con una expresión de filtro (por ejemplo, recuentos).

Todas las herramientas son de solo lectura. El servidor de MCP no expone ninguna operación de escritura, actualización o eliminación en los recursos de recuperación de agentes.

Herramientas de listas

Usa el inspector de MCP para enumerar las herramientas o enviar una solicitud HTTP tools/list directamente al servidor de MCP de recuperación de agentes. El método tools/list no requiere autenticación.

El servidor de MCP de recuperación de agentes admite el protocolo sin estado MCP 2026-07-28, por lo que cada solicitud sin estado se describe a sí misma y debe declarar la versión del protocolo tanto en el encabezado HTTP MCP-Protocol-Version como en el campo del cuerpo _meta.io.modelcontextprotocol/protocolVersion, junto con un objeto _meta.io.modelcontextprotocol/clientCapabilities (se acepta un objeto vacío). El encabezado HTTP Mcp-Method también debe coincidir con el method en el cuerpo.

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": {}
      }
    }
  }'

Ejemplos de casos de uso

A continuación, se muestran algunos casos de uso de ejemplo para el servidor de MCP de recuperación de agentes:

  • Inspección de recursos: Enumera colecciones e índices en un proyecto, y revisa sus esquemas y metadatos.
  • Búsqueda semántica y de vectores: Ejecuta una búsqueda semántica o de vectores en una colección para encontrar los objetos de datos más relevantes para una consulta.
  • Recuperación híbrida: Combina búsquedas semánticas, de texto y de Vector Search en una sola llamada por lotes y fusiona los resultados con la fusión por clasificación recíproca (RRF) o la API de Vertex Ranking.
  • Recuperación de objetos de datos: Recupera objetos de datos individuales por ID o consulta una colección por filtro para inspeccionar los registros transferidos.

Ejemplos de instrucciones

  • "Enumera las colecciones de recuperación de agentes en el proyecto PROJECT_ID en REGION".
  • "Muestra el esquema de la colección COLLECTION_ID en la región REGION".
  • "Ejecuta una búsqueda semántica en la colección COLLECTION_ID para QUERY_TEXT y devuelve los 5 vecinos más cercanos".
  • "Realiza una búsqueda híbrida en la colección COLLECTION_ID para QUERY_TEXT que combine la búsqueda semántica y de texto, luego, vuelve a clasificar los 50 resultados principales con semantic-ranker-fast@latest".
  • "Obtén el objeto de datos con el ID DATA_OBJECT_ID de la colección COLLECTION_ID".

En las instrucciones, reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto de Cloud de Confiance .
  • REGION: Es la región de tu colección (por ejemplo, us-central1).
  • COLLECTION_ID: Es el ID de la colección de recuperación de agentes.
  • DATA_OBJECT_ID: Es el ID de un objeto de datos en la colección.
  • QUERY_TEXT: Es el texto en lenguaje natural de la consulta.

Cuotas y límites

El servidor de MCP de recuperación de agentes no tiene sus propias cuotas. No hay límite en la cantidad de llamadas que se pueden realizar al servidor de MCP. Aún estás sujeto a las cuotas que aplica la API de Agent Retrieval, a la que llaman las herramientas del servidor de MCP en tu nombre. Para obtener más información, consulta Cuotas de recuperación de agentes.

¿Qué sigue?