Après que Google a mis REST sur API Gateway MCP, pourquoi la découverte est-elle encore du JSON ? OpenAPI 3.x jusqu’à tools/list

D’emblée : la passerelle fera office de MCP Server. Le contrat de découverte reste un document JSON. Le 24 septembre 2026, le blog développeurs de Google a annoncé que Cloud API Gateway, en Public Preview, peut exposer les opérations OpenAPI 3.x déjà déployées comme outils MCP distants — plus de MCP Server à construire ou à héberger. La doc était arrivée plus tôt : les notes de version du 11 septembre listent déjà Enable MCP. La passerelle accepte le JSON-RPC standard sur /mcp, transcode tools/call en la requête REST existante, et garde JWT, clés API, quota et journaux sur un seul chemin de politique. Ce que l’agent voit n’est pas « REST est devenu magique ». Ce sont les noms d’outils et les input schemas de tools/list — encore du JSON.

Rédigé au 30 septembre 2026, d’après ce billet et la doc API Gateway encore en vigueur ce jour-là. Ce site a déjà ce qu’est MCP, pourquoi la découverte des Skills est encore du JSON, et le JSON malveillant et le Tool Calling. Cet article ne répond qu’à quelle couche JSON vous vérifiez d’abord une fois OpenAPI posé sur la passerelle, et quelle couche est ouverte par défaut.

Ce que « gateway as MCP server » a vraiment livré

La ligne officielle est courte : la plupart des capacités d’entreprise sont derrière REST ; les agents ne les voient pas. Les équipes dressent en général un second MCP Server et réimplémentent routage, auth et quota. API Gateway est la rampe légère dans la gamme de passerelles Google Cloud. Un service Cloud Run à gérer et exposer aux agents en quelques minutes passe par ici. Cycle de vie complet, politique de trafic lourde et monétisation restent sur Apigee. Les appels sortants d’agent, y compris les MCP Servers comme celui-ci, passent par Agent Gateway. Le routage de modèle sortant est l’autre direction, et il ne peut pas partager une API config avec MCP.

Seules quatre méthodes de cycle de vie sont prises en charge : initialize, notifications/initialized, tools/list et tools/call. Tout le reste (resources/*, prompts/*) renvoie JSON-RPC -32601. Le transport est HTTP POST. Il n’y a pas de stdio. L’en-tête d’exemple est MCP-Protocol-Version: 2025-11-25. La spec elle-même a déplacé le handshake en 2026-07-28 ; cette preview épingle 2025-11-25. Même la chaîne de version est un champ à aligner d’abord dans l’enveloppe JSON.

Ce n’est pas écrire un autre MCP Server

La requête REST transcodée est indistinguable d’un appel navigateur ou SDK. Le quota est par opération ; MCP et REST partagent l’allocation. Le backend ne gagne pas une deuxième interface pour les agents. Ce qui change, c’est la découverte : les gens lisaient OpenAPI ; le modèle lit maintenant le JSON Schema dans tools/list.

Couche	Avant	Après Gateway MCP
Contrat humain	OpenAPI 2.0 / 3.x, souvent du YAML	Il faut d’abord passer à OpenAPI 3.0.x ou 3.1.x
Découverte agent	Un tools/list auto-hébergé	La passerelle construit tools/list depuis la même spec
Appel	REST, ou votre propre tools/call	JSON-RPC tools/call → le REST d’origine
Auth / quota	Politique de passerelle, parfois écrite deux fois	Toujours la politique de passerelle ; la découverte a un défaut séparé

Donc « pas de MCP Server à opérer » n’est pas « pas de contrat JSON à maintenir ». Les descriptions vides, les objets trop profonds et les restes 2.0 apparaissent à la découverte ou au transcodage. Voir ce qu’est MCP.

Le contrat pousse depuis OpenAPI 3.x

Activez MCP au niveau du document avec x-google-api-management.mcp. Par opération, x-google-mcp-tool peut renommer, réécrire la description, ou mettre false pour se retirer. Chaque opération exposée a besoin d’un backend et d’une description non vide. Seuls GET / POST / PUT / PATCH / DELETE sont admis. Les noms d’outils doivent correspondre à [A-Za-z0-9_.-]{1,128} et rester uniques sur la passerelle.

La forme minimale officielle (YAML sur la page ; le sens est un objet JSON) :

x-google-api-management:
  mcp: true
paths:
  /orders/{orderId}:
    get:
      operationId: getOrderStatus
      description: Returns the current status, carrier, and ETA for an order.
      x-google-mcp-tool:
        name: get_order_status
        description: "Look up the delivery status and ETA of a customer order."
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string

La description est le signal principal dont le modèle se sert pour savoir quand appeler. Google demande du when / why, pas seulement ce qui revient. Les schemas de path, query, body et header deviennent les arguments d’outil. Les objets imbriqués peuvent ne pas se rendre entièrement dans tools/list — une limite documentée de la preview, pas un validateur cassé. Aplatissez l’OpenAPI en local, puis faites un Diff contre l’input schema de la passerelle.

tools/list n’est pas authentifié par défaut

Par défaut, n’importe qui peut POST /mcp et recevoir le catalogue : noms, descriptions, input schemas. Correct pour le développement. En production, ça publie le contrat de paramètres. Google recommande un JWT sur tools/list. En Public Preview, une clé API ne peut pas protéger cette méthode. La forme objet active aussi MCP globalement ; les opérations que vous ne voulez pas exposer ont besoin de x-google-mcp-tool: false.

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

tools/call applique toujours l’auth REST sous-jacente, découverte verrouillée ou non. Un catalogue ouvert et un appel verrouillé sont deux choses différentes. Si les noms d’outils et les schemas sont sensibles, verrouillez tools/list avant de livrer. C’est la même couche que le guide du JSON malveillant : plus le contrat vu par le modèle est large, plus la surface d’injection l’est.

tools/call reste du JSON-RPC

La forme sur le fil dans la doc est :

{"jsonrpc":"2.0","id":1,"method":"tools/call",
 "params":{"name":"get_order_status","arguments":{"orderId":"A-1042"}}}

La passerelle replace arguments sur path / query / body / header, applique la politique, et enveloppe la réponse backend en résultat MCP. Au débogage, séparez les couches : l’enveloppe externe est du JSON-RPC ; le payload interne est le JSON métier. Les échecs de parse appartiennent à l’une ou l’autre couche. L’exemple ADK pointe Streamable HTTP vers …/mcp et peut encore envoyer les identifiants que la passerelle attend déjà.

Branchez la passerelle à API hub et une config MCP publiée arrive avec des métadonnées MCP et apparaît dans Agent Registry. Le répertoire a changé. Le contrat de champs n’a pas changé : c’est encore le schema poussé depuis votre OpenAPI. La découverte des Skills est un autre document JSON — voir SEP-2640 et skill://index.json. Ne fusionnez pas ces deux catalogues en une seule table.

Limites à lire en Public Preview

OpenAPI 2.0 n’est pas pris en charge. Passez d’abord à 3.x.
Les opérations à corps vide (HTTP 204) ne sont pas exposées comme outils.
Les schemas d’objets trop imbriqués peuvent être tronqués dans tools/list.
Une passerelle sert jusqu’à environ 1 000 outils.
MCP et le routage de modèle ne peuvent pas partager une même API config.
Resources / prompts, le streaming de réponse et l’inspection Model Armor sont encore sur la feuille de route.

Ce n’est pas du « on polira plus tard ». Une opération 204 disparaît du catalogue et le modèle en appellera une autre. Un schema tronqué ne correspondra ni à un validateur strict ni au vrai backend. Le guide de migration MCP 2026 parle des versions de protocole. Cet article ajoute : la list que la passerelle génère peut ne pas égaler l’OpenAPI complète de votre dépôt.

Quatre documents JSON à vérifier avant d’actionner l’interrupteur

L’OpenAPI 3.x dans le dépôt. Passez d’abord le 2.0. Chaque opération exposée a une description non vide, un backend, et un nom d’outil légal.
Le tools/list de la passerelle. Vérifiez si les input schemas ont été tronqués et si des opérations en trop ont fuité.
Un vrai tools/call. Les arguments se remappent-ils sur REST ? L’enveloppe est-elle du JSON-RPC 2.0 ?
L’objet de sécurité de la découverte. Ne livrez pas avec tools/list encore ouvert. Le nom du scheme JWT doit déjà exister sous components.securitySchemes.

Inspecter la spec avec les outils JSON locaux

Avant d’activer MCP, étalez trois textes dans le navigateur : l’OpenAPI (convertissez d’abord le YAML en JSON), une réponse tools/list, et l’objet arguments que vous enverrez à tools/call.

Validateur JSON — la grammaire est-elle légale ; si vous avez un schema, vérifiez ensemble champs required et clés en trop.
JSON ↔ YAML — la plupart des OpenAPI vivent en YAML ; convertissez avant de Diff contre la list.
JSON Diff — comparez le schema parameters du dépôt avec l’inputSchema renvoyé par la passerelle.

Rien ne quitte le navigateur. Aplatissez le contrat, puis actionnez le commutateur de la passerelle. La passerelle transcodera. Vos noms de champs et la liste required ne devraient pas se relâcher avec la troncature de la preview.

FAQ

Est-ce GA ? Ai-je encore besoin de mon propre MCP Server ?

Au 30 septembre 2026, c’est Public Preview. REST plus OpenAPI 3.x et les quatre méthodes de cycle de vie peuvent tenir sur la passerelle. Resources, prompts, streaming, stdio, ou plus d’environ 1 000 outils ont encore besoin de votre propre server.

Si tools/list est ouvert, la clé API ne protège-t-elle pas encore les appels ?

Les appels suivent la politique REST. Le catalogue publie noms et input schemas par défaut. Une clé API ne peut pas protéger tools/list. Verrouillez la découverte avec un JWT en production.

Ma spec est encore OpenAPI 2.0 / Swagger. Puis-je activer ça ?

Non. Passez à 3.0.x ou 3.1.x, puis ajoutez l’extension mcp.

Est-ce la même chose que la découverte Skill SEP-2640 de septembre ?

Non. La découverte Skill, c’est skill://index.json ou skills/list. Le chemin passerelle transforme les opérations REST en tools/list. Deux documents JSON, deux jeux de champs.

Pourquoi le schema tools/list est-il plus plat que mon OpenAPI ?

La preview dit que les objets profonds peuvent ne pas se rendre entièrement. Fiez-vous à la réponse de la passerelle. Diff contre la spec du dépôt et voyez quels champs required ont disparu.

Où est passé mon DELETE qui renvoie 204 ?

Les opérations à corps vide ne sont pas exposées comme outils. Le modèle ne verra pas ce nom et ne l’appellera pas.

Résumé

API Gateway enlève le processus MCP Server. Il n’enlève pas le contrat JSON. OpenAPI 3.x fait pousser tools/list. tools/call reste du JSON-RPC. La politique reste la politique REST que vous avez déjà. Un catalogue ouvert, un schema imbriqué tronqué, et une opération 204 manquante sont des contrôles avant lancement — pas « preview activée, terminé ».

Aplatissez l’OpenAPI, la réponse list et un échantillon d’appel en local, puis posez mcp: true. La passerelle transcodera. Le contrat de champs ne devrait pas se relâcher avec les limites de la preview.