Utiliser le serveur MCP distant Agent Retrieval pour se connecter à l'IA et aux applications personnalisées

Le Model Context Protocol (MCP) standardise la façon dont les grands modèles de langage (LLM) et les applications ou agents d'IA se connectent à des sources de données externes. Les serveurs MCP vous permettent d'utiliser leurs outils, leurs ressources et leurs prompts pour effectuer des actions et obtenir des données à jour à partir de leur service de backend.

Quelle est la différence entre les serveurs MCP locaux et distants ?

Serveurs MCP locaux

Ils s'exécutent généralement sur votre ordinateur local et utilisent les flux d'entrée et de sortie standards (stdio) pour la communication entre les services sur le même appareil.

Serveurs MCP distants

S'exécutent sur l'infrastructure du service et offrent un point de terminaison HTTP aux applications d'IA pour la communication entre le client MCP d'IA et le serveur MCP. Pour en savoir plus sur l'architecture MCP, consultez Architecture MCP.

Noyau sans état

Avec la version 2026-07-28 du MCP, le MCP passe d'un protocole bidirectionnel avec état à un protocole sans état. Chaque requête MCP est auto-descriptive et peut être acheminée à l'aide d'en-têtes. Le handshake initialize/initialized ou Mcp-Session-Id n'est pas nécessaire, car chaque requête inclut toutes les informations requises dans les en-têtes HTTP ou le paramètre _meta. Les serveurs MCP peuvent demander des informations supplémentaires requises par un outil via des requêtes multi-aller-retour (MRTR).

Pour faciliter le routage et le traitement des requêtes sans analyser le corps de la requête, certains en-têtes MCP sont requis, y compris les suivants :

• En-têtes requis par la spécification MCP, tels que l'en-tête de version du protocole et les en-têtes de requête standards.
• En-têtes personnalisés définis par le serveur MCP. Ces en-têtes sont mis en miroir dans les en-têtes HTTP à partir du schéma d'entrée de l'outil à l'aide de la propriété x-mcp-header. Par exemple, un serveur MCP peut définir un en-tête personnalisé pour spécifier la région ou l'ID du projet Cloud de Confiance by S3NS .

Pour en savoir plus sur l'architecture MCP, consultez la spécification et les principaux changements de la version 2026-07-28 de MCP.

Serveurs MCP distants Google et Cloud de Confiance by S3NS

• Découverte simplifiée et centralisée
• Points de terminaison HTTP gérés mondiaux ou régionaux
• Autorisations précises
• Sécurité facultative des prompts et des réponses avec la protection Model Armor
• Journaux d'audit centralisés

Pour en savoir plus sur les autres serveurs MCP et sur les contrôles de sécurité et de gouvernance disponibles pour les serveurs MCP Google Cloud, consultez la présentation des serveurs MCP Google Cloud.

Avant de commencer

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. Activez l'API Agent Retrieval si ce n'est pas déjà fait.

   Rôles requis pour activer les API

   Pour activer des API, vous devez disposer de l'autorisation serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation via le rôle Propriétaire (roles/owner). Sinon, vous pouvez l'obtenir via le rôle Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin). Découvrez comment attribuer des rôles.

   Activer l'API

Rôles requis

Pour obtenir les autorisations nécessaires pour utiliser le serveur MCP de récupération d'agent, demandez à votre administrateur de vous accorder les rôles IAM suivants sur le projet dans lequel vous souhaitez utiliser le serveur MCP de récupération d'agent :

• Effectuer des appels d'outils MCP : Utilisateur de l'outil MCP (roles/mcp.toolUser)
• Lire les ressources Agent Retrieval : Lecteur Vector Search (roles/vectorsearch.viewer)

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ces rôles prédéfinis contiennent les autorisations requises pour utiliser le serveur MCP de récupération d'agent. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

Le serveur MCP de récupération d'agent n'expose que des outils en lecture seule. Aucune autorisation d'écriture n'est requise.

Authentification et autorisation

Le serveur MCP de récupération d'agent utilise le protocole OAuth 2.0 avec IAM pour l'authentification et l'autorisation. Toutes les identitésCloud de Confiance by S3NS sont compatibles avec l'authentification auprès des serveurs MCP.

Nous vous recommandons de créer une identité distincte pour les agents qui utilisent des outils MCP afin de pouvoir contrôler et surveiller l'accès aux ressources. Pour en savoir plus sur l'authentification, consultez S'authentifier auprès des serveurs MCP.

Champs d'application OAuth du MCP Agent Retrieval

OAuth 2.0 utilise des champs d'application et des identifiants pour déterminer si un compte principal authentifié est autorisé à effectuer une action spécifique sur une ressource. Pour en savoir plus sur les champs d'application OAuth 2.0 chez Google, consultez Utiliser OAuth 2.0 pour accéder aux API Google.

Le serveur MCP Agent Retrieval accepte le champ d'application OAuth suivant :

Configurer un client MCP pour utiliser le serveur MCP de récupération d'agent

Les applications et agents d'IA, tels que Claude ou Antigravity, peuvent instancier un client MCP qui se connecte à un seul serveur MCP. Une application d'IA peut avoir plusieurs clients qui se connectent à différents serveurs MCP. Si votre application ne figure pas dans les instructions spécifiques au client, vous pouvez utiliser les informations suivantes pour vous connecter à partir de la plupart des applications.

Dans votre application d'IA, recherchez un moyen d'ajouter un serveur MCP distant ou de vous y connecter. Pour le serveur MCP de récupération d'agent, saisissez les informations suivantes :

• Nom du serveur : serveur MCP Agent Retrieval

• URL du serveur ou point de terminaison : https://vectorsearch.googleapis.com/mcp

  Ce point de terminaison unique expose les neuf outils MCP de récupération d'agent. Les appels d'outils sont envoyés au bon backend par le routage basé sur l'en-tête.

• Transport : HTTP diffusable en streaming

• Informations d'authentification : vos identifiants Cloud de Confiance by S3NS , l'ID client et le secret de votre client OAuth, ou l'identité et les identifiants d'un agent. Pour en savoir plus sur l'authentification, consultez S'authentifier auprès des serveurs MCP.

Routage basé sur les en-têtes et exigences liées au protocole client

Le serveur MCP de récupération de l'agent distribue chaque tools/call à la périphérie du réseau en fonction de deux en-têtes HTTP :

• Mcp-Name : doit être identique au nom de l'outil dans le corps de la requête (params.name).
• Mcp-Param-Region : doit être égal au composant location du chemin d'accès à la ressource dans le corps de la requête (par exemple, us-central1 pour une collection à l'emplacement projects/PROJECT_ID/locations/us-central1/collections/COLLECTION_ID).

Si l'un des en-têtes est manquant ou ne correspond pas au corps, la requête est rejetée avec l'erreur HTTP 400 Bad Request.

Votre client MCP doit émettre ces en-têtes de manière dynamique par tools/call. Ce comportement est standardisé dans la version 2026-07-28 du protocole MCP et les versions ultérieures. Assurez-vous que votre bibliothèque cliente MCP annonce au moins cette version du protocole lors du handshake initialize. Les clients épinglés à des versions de protocole antérieures ou à des versions de SDK qui ne sont pas compatibles avec l'émission d'en-têtes dynamiques ne peuvent pas utiliser le serveur MCP de récupération d'agent via le point de terminaison /mcp unifié.

URI de redirection

Pour les applications Web et certaines applications de bureau, vous devez ajouter un URI de redirection à la liste d'autorisation lorsque vous créez un ID client et un code secret pour l'authentification. Les URI de redirection sont utilisés par le serveur d'autorisation pour envoyer des jetons à votre application. La documentation de votre application doit spécifier l'URI de redirection que vous devez utiliser. Les URI de redirection personnalisés ne sont pas acceptés.

Pour obtenir des conseils spécifiques à une application sur la configuration et la connexion à un serveur MCP, consultez Conseils spécifiques au client.

Pour obtenir des conseils plus généraux, consultez les ressources suivantes :

• Se connecter à des serveurs MCP distants
• Configurer MCP dans une application d'IA

Outils disponibles

Le serveur MCP de récupération d'agents expose neuf outils en lecture seule :

Tous les outils sont en lecture seule. Le serveur MCP n'expose aucune opération d'écriture, de mise à jour ou de suppression sur les ressources Agent Retrieval.

Lister les outils

Utilisez l'inspecteur MCP pour lister les outils ou envoyez une requête HTTP tools/list directement au serveur MCP de récupération de l'agent. La méthode tools/list ne nécessite pas d'authentification.

Le serveur MCP de récupération de l'agent est compatible avec le protocole sans état MCP 2026-07-28. Par conséquent, chaque requête sans état est auto-descriptive et doit déclarer la version du protocole dans l'en-tête HTTP MCP-Protocol-Version et le champ de corps _meta.io.modelcontextprotocol/protocolVersion, ainsi qu'un objet _meta.io.modelcontextprotocol/clientCapabilities (un objet vide est accepté). L'en-tête HTTP Mcp-Method doit également correspondre à method dans le corps.

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

Exemples de cas d'utilisation

Voici des exemples de cas d'utilisation du serveur MCP de récupération d'agent :

• Inspection des ressources : listez les collections et les index d'un projet, et inspectez leurs schémas et leurs métadonnées.
• Recherche vectorielle et sémantique : exécutez une recherche vectorielle ou sémantique sur une collection pour trouver les objets de données les plus pertinents pour une requête.
• Récupération hybride : combinez les recherches sémantiques, textuelles et vectorielles dans un seul appel par lot et fusionnez les résultats avec la fusion de classement réciproque (RRF) ou l'API Vertex Ranking.
• Récupération d'objets de données : récupérez des objets de données individuels par ID ou interrogez une collection par filtre pour inspecter les enregistrements ingérés.

Exemples de prompts

• "Répertorie les collections Agent Retrieval du projet PROJECT_ID dans REGION."
• "Affiche le schéma de la collection COLLECTION_ID dans la région REGION."
• "Exécutez une recherche sémantique sur la collection COLLECTION_ID pour QUERY_TEXT et renvoyez les cinq voisins les plus proches."
• "Effectue une recherche hybride sur la collection COLLECTION_ID pour QUERY_TEXT qui combine la recherche sémantique et la recherche textuelle, puis reclasse les 50 premiers résultats avec semantic-ranker-fast@latest."
• "Récupérer l'objet de données avec l'ID DATA_OBJECT_ID de la collection COLLECTION_ID."

Dans les prompts, remplacez les éléments suivants :

• PROJECT_ID : ID du projet Cloud de Confiance
• REGION : région de votre collection (par exemple, us-central1)
• COLLECTION_ID : ID de la collection de récupération de l'agent.
• DATA_OBJECT_ID : ID d'un objet de données dans la collection
• QUERY_TEXT : texte en langage naturel de la requête

Quotas et limites

Le serveur MCP de récupération d'agent ne dispose pas de ses propres quotas. Le nombre d'appels pouvant être effectués vers le serveur MCP n'est pas limité. Vous êtes toujours soumis aux quotas appliqués par l'API Agent Retrieval, que les outils du serveur MCP appellent en votre nom. Pour en savoir plus, consultez Quotas de récupération de l'agent.

Étapes suivantes

• Consultez la documentation de référence sur le MCP de récupération de l'agent.
• Découvrez comment créer une collection.
• Découvrez comment rechercher des objets de données.
• Découvrez comment reclasser les résultats de recherche.
• En savoir plus sur les serveurs MCP Google Cloud