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 (Model Context Protocol)

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. Le MCP n'est pas compatible avec OpenAPI 2.0.
Assurez-vous de bien 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 des outils doivent correspondre à [A-Za-z0-9_.-]{1,128} et être uniques dans la spécification.
Description : chaque outil doit correspondre à une description non vide (extraite de la description, du résumé ou du remplacement de l'opération). Les opérations sans description résoluble sont refusées.
Sécurité : si vous configurez l'authentification pour tools/list, vous devez nommer exactement un schéma de sécurité défini sous components.securitySchemes. Le schéma peut être un schéma JWT ou un schéma de clé API. Si vous utilisez un schéma JWT, vous devez également le nommer dans l'exigence security de premier niveau de la spécification.

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 de clé API ou de jeton 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, pour des raisons de sécurité, nous vous recommandons vivement de protéger la découverte d'outils en activant l'authentification pour cette méthode à l'aide de tools-list.security. Vous pouvez authentifier tools/list avec un jeton JWT ou une clé API.

Étapes pour configurer MCP

Pour exposer votre API en tant qu'outils MCP, procédez comme suit :

1. Identifier les opérations à exposer

Examinez votre spécification OpenAPI et déterminez les opérations qui doivent être disponibles pour les agents 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 mondiale

Activez MCP de manière globale 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é globalement, toutes les opérations éligibles (en fonction de la méthode HTTP et du chemin d'accès) sont exposées en tant qu'outils MCP. Par défaut, le nom de l'outil est l'operationId de l'opération, et la description est la description ou le résumé de l'opération.

Configuration par opération

Vous pouvez remplacer les paramètres globaux ou exposer de manière sélective 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 de manière globale en définissant x-google-mcp-tool: false.

3. Authentifier `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 pouvez nommer un schéma JWT ou un schéma de clé API.

L'exemple suivant nécessite un jeton JWT :

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

L'exemple suivant nécessite une clé API. Les clients doivent envoyer la clé dans l'en-tête HTTP x-api-key. tools/list ne lit pas les clés API à partir des paramètres de requête. Une requête sans clé valide reçoit une erreur JSON-RPC et aucune liste d'outils. Pour savoir comment créer une clé API, consultez Utiliser des clés API.

x-google-api-management:
  mcp:
    tools-list:
      security:
        api_key: []
components:
  securitySchemes:
    api_key:
      type: apiKey
      name: x-api-key
      in: header

4. Créer et déployer la configuration d'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. Pour modifier les outils ultérieurement, consultez Mettre à jour les outils MCP exposés.

5. Vérifier la compatibilité MCP

Une fois la passerelle déployée, vous pouvez vérifier qu'elle diffuse 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

Lister les outils disponibles. Si vous avez configuré tools-list.security, ajoutez l'identifiant correspondant, par exemple un en-tête Authorization: Bearer pour un jeton JWT ou un en-tête x-api-key pour une clé API :

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 paramètres de requête : deviennent des propriétés de premier niveau dans l'objet arguments, indexées par leurs noms de paramètres OpenAPI.
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 : 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 adressée à votre service de backend. Les services de backend ne peuvent pas distinguer de manière programmatique un appel REST direct d'un appel transcodé à partir de MCP.

Appeler un outil

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

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

Mettre à jour les outils MCP exposés

Les configurations d'API dans API Gateway sont immuables. Vous ne pouvez donc pas modifier la définition d'API dans une configuration d'API existante. Par conséquent, la réponse tools/list est statique pour chaque configuration d'API déployée.

Pour ajouter, supprimer, renommer ou mettre à jour des outils MCP exposés ou des paramètres de sécurité tools/list, créez une configuration d'API et déployez-la sur votre passerelle :

Mettez à jour votre spécification OpenAPI 3.x, y compris les opérations, les valeurs operationId, les résumés, les paramètres et les extensions x-google-api-management.mcp et x-google-mcp-tool.
Créez une configuration d'API avec un nouvel ID de configuration d'API :
```
gcloud api-gateway api-configs create NEW_CONFIG_ID \
    --api=API_ID \
    --openapi-spec=API_DEFINITION \
    --project=PROJECT_ID \
    --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL
```
Remplacez les éléments suivants :
- NEW_CONFIG_ID : nouvel ID de la configuration d'API mise à jour
- API_ID : ID de l'API API Gateway
- API_DEFINITION : chemin d'accès à votre spécification OpenAPI 3.x mise à jour
- PROJECT_ID : ID de votre projet Google Cloud
- SERVICE_ACCOUNT_EMAIL : adresse e-mail du compte de service utilisé pour signer les jetons des backends pour lesquels l'authentification est configurée. Omettez cette option si aucun de vos backends ne nécessite d'authentification.
Pour en savoir plus, consultez Créer une configuration d'API.
Mettez à jour chaque passerelle qui diffuse l'API pour utiliser la nouvelle configuration d'API :
```
gcloud api-gateway gateways update GATEWAY_ID \
    --api=API_ID \
    --api-config=NEW_CONFIG_ID \
    --location=GCP_REGION \
    --project=PROJECT_ID
```
Remplacez les éléments suivants :
- GATEWAY_ID : ID de la passerelle à mettre à jour.
- GCP_REGION : région où la passerelle est déployée
Pour en savoir plus, consultez Mettre à jour une passerelle.
Appelez tools/list pour vérifier l'ensemble d'outils mis à jour. Pour obtenir un exemple de requête, consultez Découvrir des outils.
Une fois qu'aucune passerelle n'utilise la configuration d'API précédente, supprimez la configuration d'API remplacée :
```
gcloud api-gateway api-configs delete OLD_CONFIG_ID \
    --api=API_ID \
    --project=PROJECT_ID
```
Remplacez OLD_CONFIG_ID par l'ID de la configuration d'API remplacée. Ne supprimez pas une configuration d'API tant qu'une passerelle l'utilise. Si votre nouvelle configuration d'API renomme ou supprime des métriques de quota, les passerelles qui diffusent toujours une ancienne configuration d'API peuvent renvoyer des erreurs HTTP 500 jusqu'à ce qu'elles soient mises à jour (voir Les quotas s'appliquent à l'ensemble de l'API). Pour en savoir plus, consultez Supprimer une configuration d'API.

Tenez compte des comportements de déploiement et de client suivants lorsque vous mettez à jour des outils MCP :

Déploiement sans temps d'arrêt : API Gateway met à jour les passerelles sans temps d'arrêt. Pendant la propagation de la nouvelle configuration d'API, certaines requêtes peuvent brièvement atteindre la configuration d'API précédente. Si votre API est déployée sur plusieurs passerelles ou régions, mettez à jour chaque passerelle séparément.
Caches des outils clients : comme API Gateway diffuse le protocole MCP via un transport HTTP sans état, la passerelle n'émet pas de notifications notifications/tools/list_changed. Une fois la mise à jour de la passerelle terminée, les clients MCP qui mettent en cache les définitions d'outils doivent appeler à nouveau tools/list pour découvrir les outils mis à jour.
Limites de configuration d'API : chaque API est limitée à 100 configurations d'API. Supprimez donc les configurations d'API obsolètes après avoir mis à jour vos passerelles. Créez les configurations d'API une par une. Si vous lancez une deuxième configuration d'API pour la même API avant que la première ne soit terminée, l'une d'elles ou les deux risquent de ne pas être utilisables par une passerelle. Pour en savoir plus, consultez la page Quotas et limites.

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.

Dépannage des échecs de MCP

Le protocole MCP distingue les échecs de transport des échecs de protocole. La passerelle renvoie un code 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 transport.

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

Problème constaté	Code JSON-RPC	État HTTP	Signification et correction standard
Méthode non autorisée	n/a	`405`	Une requête non POST a atteint `/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 manquant/non valide	`-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 n'est pas compatible (par exemple, `ping`).
Version de protocole non compatible	`-32602`	`200`	`protocolVersion` nomme une version non compatible avec la passerelle.
Version du protocole manquante	`-32602`	`200`	Les paramètres `initialize` omettent `protocolVersion` ou il ne s'agit pas d'une chaîne.
Outil inconnu	`-32602`	`200`	Nom de l'outil introuvable dans la configuration de l'API déployée. Actualisez le cache de l'outil client ou consultez Mettre à jour les outils MCP exposés.
Arguments d'outil non valides	`-32602`	`200`	Les arguments sont manquants ou non valides. Vérifiez l'imbrication de la clé `body`.
Corps trop volumineux	`-32000`	`200`	La charge utile de la réponse a dépassé les limites de taille.
Corps de transport trop volumineux	n/a	`413`	Le corps de la requête HTTP brute a dépassé les limites de transport de la passerelle.
Erreur du serveur	`-32000`	`200`	Réponse du backend impossible à analyser. Vérifiez les journaux.
Non autorisé/Interdit	n/a	`401`/`403`	Échec de l'authentification. La réponse contient 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.