Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Configurer le protocole MCP

Ce document explique comment configurer API Gateway pour qu'il agisse en tant que serveur MCP (Model Context Protocol) distant.

Avant de commencer

Assurez-vous de disposer d'une spécification OpenAPI 3.x valide pour votre API. MCP n'est pas compatible avec OpenAPI 2.0.
Assurez-vous de comprendre les principes de base d'API Gateway.

Validation de la configuration

Lorsque vous importez votre spécification OpenAPI, API Gateway effectue les validations suivantes pour la configuration MCP :

Emplacement : l'extension x-google-mcp-tool ne doit être spécifiée qu'au niveau de l'opération individuelle.
Méthode HTTP : seules les opérations GET, POST, PUT, PATCH et DELETE peuvent être exposées en tant qu'outils MCP.
Nom de l'outil : les noms d'outils doivent correspondre à [A-Za-z0-9_.-]{1,128} et être uniques dans la spécification.
Description : chaque outil doit renvoyer à une description non vide (tirée de la description, du résumé ou du remplacement de l'opération). Les opérations sans description résolvable sont refusées.
Sécurité : si vous configurez l'authentification pour tools/list, vous devez nommer exactement un schéma de sécurité JWT défini sous components.securitySchemes. La sécurité des clés API n'est pas compatible avec tools/list dans la version Preview publique.

Modèle d'authentification

API Gateway applique différentes règles d'authentification en fonction de la méthode MCP appelée :

Cycle de vie du protocole : les méthodes initialize et notifications/initialized ne sont pas authentifiées.
Appel d'outil (tools/call) : réutilise les règles d'authentification définies pour l'opération sous-jacente dans votre spécification OpenAPI. Il applique les mêmes exigences concernant les clés API ou les jetons JWT que l'appel direct du point de terminaison REST.
Découverte d'outils (tools/list) : par défaut, cette méthode n'est pas authentifiée. Toutefois, en tant que bonne pratique de sécurité, il est fortement recommandé de protéger la découverte d'outils en activant l'authentification pour cette méthode à l'aide de tools-list.security. Si vous choisissez d'activer l'authentification, vous devez utiliser un schéma de sécurité JWT. L'authentification par clé API n'est pas acceptée pour tools/list.

Étapes pour configurer MCP

Pour exposer votre API en tant qu'outils MCP :

1. Identifier les opérations à exposer

Examinez votre spécification OpenAPI et déterminez les opérations qui doivent être disponibles pour les agents d'IA.

2. Mettre à jour votre spécification OpenAPI

Vous pouvez activer le MCP de manière globale pour toutes les opérations éligibles ou le configurer pour chaque opération.

Activation globale

Activez MCP globalement en ajoutant le champ mcp à x-google-api-management au niveau du document :

openapi: 3.0.3
info:
  title: Bookstore API
  version: 1.0.0
x-google-api-management:
  mcp: true
  backends:
    bookstore-backend:
      address: https://bookstore-backend-12345678.us-central1.run.app

Lorsqu'il est activé au niveau mondial, toutes les opérations éligibles (en fonction de la méthode et du chemin HTTP) sont exposées en tant qu'outils MCP. Par défaut, le nom de l'outil correspond à l'operationId de l'opération, et la description correspond à la description ou au résumé de l'opération.

Configuration par opération

Vous pouvez remplacer les paramètres globaux ou exposer sélectivement des opérations à l'aide de x-google-mcp-tool :

paths:
  /v1/shelves/{shelf}:
    delete:
      operationId: deleteShelf
      summary: Delete a shelf.
      x-google-backend: bookstore-backend
      x-google-mcp-tool:
        name: delete_shelf
        description: "Permanently delete a shelf and every book on it."

Vous pouvez également désactiver une opération lorsqu'elle est activée au niveau global en définissant x-google-mcp-tool: false.

3. S'authentifier avec `tools/list` (recommandé)

Par défaut, la méthode tools/list (qui énumère les outils disponibles) n'est pas authentifiée. Pour respecter les bonnes pratiques de sécurité, nous vous recommandons vivement d'appliquer l'authentification en configurant tools-list.security sous x-google-api-management/mcp. Vous devez utiliser un schéma JWT. Les clés API ne sont pas acceptées pour cette méthode.

x-google-api-management:
  mcp:
    tools-list:
      security:
        myJWT: []

4. Créer et déployer la configuration de l'API

Créez une configuration d'API à partir de votre spécification annotée et déployez-la sur une passerelle à l'aide du flux standard. Pour en savoir plus, consultez Déployer une API sur une passerelle.

5. Vérifier la compatibilité avec MCP

Une fois le déploiement effectué, vous pouvez vérifier que la passerelle traite les requêtes MCP.

Handshake

Envoyez une requête d'initialisation pour établir la version et les fonctionnalités du protocole :

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {"name": "demo-client", "version": "1.0.0"}
  }
}'

Confirmer le handshake

Confirmez l'initialisation. La passerelle répond avec HTTP 202 Accepted :

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc": "2.0", "method": "notifications/initialized"}'

Découvrent les outils

Répertoriez les outils disponibles :

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

Mappage des arguments à la requête REST

Les arguments transmis à un outil sont mappés à la requête REST sous-jacente en fonction de la spécification OpenAPI :

Paramètres de chemin d'accès et de requête : ils deviennent des propriétés de premier niveau dans l'objet arguments, avec leurs noms de paramètres OpenAPI comme clés.
Corps de la requête : imbriqué sous une seule propriété nommée body. Par exemple, pour créer une ressource, vous transmettez {"body": {"fieldName": "value"}}.
En-têtes : ils deviennent également des propriétés de premier niveau. La passerelle les injecte en tant qu'en-têtes HTTP standards dans l'appel de backend.

La requête de backend transcodée est identique à une requête REST directe envoyée à votre service de backend. Les services de backend ne peuvent pas faire la distinction entre un appel REST direct et un appel transcodé à partir de MCP.

Appeler un outil

Appeler un outil spécifique. Assurez-vous d'inclure les jetons d'authentification requis si l'opération REST sous-jacente en nécessite :

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "delete_shelf",
    "arguments": {"shelf": "sci-fi"}
  }
}'

Observabilité

Les requêtes MCP génèrent des métriques et des journaux API Gateway standards. Vous pouvez distinguer le trafic MCP du trafic REST standard en inspectant le chemin de la requête (qui se termine généralement par /mcp) ou en configurant des métriques personnalisées.

Résoudre les échecs MCP

Le protocole MCP fait la distinction entre les échecs de transport et les échecs de protocole. La passerelle renvoie HTTP 200 avec un objet d'erreur JSON-RPC pour les erreurs de protocole et d'application, car les réponses autres que 200 peuvent entraîner l'échec de nombreux clients MCP au niveau de la couche de transport.

Le tableau suivant décrit les symptômes et les correctifs courants :

Problème constaté	Code JSON-RPC	État HTTP	Signification et solution type
Méthode non autorisée	n/a	`405`	Une requête autre que POST a été envoyée à `/mcp`. Seul le protocole HTTP `POST` est accepté.
Erreur d'analyse JSON	`-32700`	`400`	Le corps de la requête n'est pas un fichier JSON valide.
Méthode ou ID manquants/non valides	`-32600`	`200`	Le corps est un fichier JSON valide, mais pas une requête JSON-RPC valide. Vérifiez les champs obligatoires (`jsonrpc`, `method`, `id`).
La méthode n'est pas acceptée	`-32601`	`200`	La méthode ne fait pas partie du champ d'application accepté (par exemple, `ping`).
Version du protocole non compatible	`-32602`	`200`	`protocolVersion` indique une version non compatible avec la passerelle.
Version du protocole manquante	`-32602`	`200`	Les paramètres `initialize` omettent `protocolVersion` ou ne sont pas une chaîne.
Outil inconnu	`-32602`	`200`	Nom de l'outil introuvable. Videz le cache du client ou vérifiez le déploiement.
Arguments d'outil non valides	`-32602`	`200`	Les arguments sont manquants ou incorrects. Vérifiez l'imbrication des clés `body`.
Corps trop volumineux	`-32000`	`200`	La charge utile de la réponse a dépassé les limites de taille.
Corps du véhicule de transport trop volumineux	n/a	`413`	Le corps brut de la requête HTTP a dépassé les limites de transport de la passerelle.
Erreur du serveur	`-32000`	`200`	Réponse backend non analysable. Vérifiez les journaux.
Non autorisé / Interdit	n/a	`401`/`403`	Échec de l'authentification. La réponse comporte un en-tête `WWW-Authenticate` pointant vers les métadonnées de la ressource protégée.

Les erreurs d'application de backend se présentent généralement sous la forme d'une réponse JSON-RPC réussie (HTTP 200) avec result.isError: true contenant le corps de l'erreur de backend.