Nachdem Google REST auf API Gateway MCP legt: Warum ist Discovery noch JSON? OpenAPI 3.x bis tools/list

Vorab: das Gateway spielt MCP-Server. Der Entdeckungsvertrag ist weiter ein JSON-Dokument. Am 24. September 2026 hat Googles Entwicklerblog geschrieben: Cloud API Gateway kann im Public Preview die OpenAPI-3.x-Operationen, die Sie schon deployen, als entfernte MCP-Tools ausliefern — ohne extra MCP-Server zu bauen oder zu hosten. Die Docs waren früher da: die Release Notes vom 11. September listen bereits Enable MCP. Das Gateway nimmt Standard-JSON-RPC auf /mcp entgegen, transcodiert tools/call in den bestehenden REST-Request und hält JWT, API-Keys, Quota und Logs auf einem Policy-Pfad. Was der Agent sieht, ist nicht „REST wurde Magie.“ Es sind die Tool-Namen und Input-Schemas aus tools/list — weiter JSON.

Stand 30. September 2026, gegen diesen Blogpost und die API-Gateway-Docs, die an dem Tag noch aktuell waren. Diese Seite hat bereits was MCP ist, warum Skill-Entdeckung weiter JSON ist und bösartiges JSON und Tool Calling. Dieser Text beantwortet nur, welche JSON-Schicht Sie zuerst prüfen, nachdem OpenAPI auf dem Gateway landet, und welche Schicht default offen ist.

Was „Gateway als MCP-Server“ tatsächlich ausgeliefert hat

Die offizielle Linie ist kurz: die meiste Enterprise-Fähigkeit sitzt hinter REST; Agenten sehen sie nicht. Teams stellen meist einen zweiten MCP-Server auf und implementieren Routing, Auth und Quota nochmal. API Gateway ist der leichte Einstieg in der Gateway-Linie von Google Cloud. Ein Cloud-Run-Dienst, der in Minuten gemanagt und Agenten zugänglich gemacht werden soll, gehört hierher. Voller Lifecycle, schwere Traffic-Policy und Monetisierung bleiben auf Apigee. Ausgehende Agent-Calls, einschließlich MCP-Servern wie diesem, laufen über Agent Gateway. Ausgehendes Model Routing ist die andere Richtung, und es kann keine API-Config mit MCP teilen.

Nur vier Lifecycle-Methoden sind unterstützt: initialize, notifications/initialized, tools/list und tools/call. Alles andere (resources/*, prompts/*) liefert JSON-RPC -32601. Transport ist HTTP POST. Es gibt kein stdio. Der Sample-Header ist MCP-Protocol-Version: 2025-11-25. Die Spec selbst hat den Handshake am 2026-07-28 verschoben; dieses Preview pinnt 2025-11-25. Selbst der Versionsstring ist ein Feld, das Sie zuerst im JSON-Umschlag ausrichten.

Das ist nicht, noch einen MCP-Server zu schreiben

Der transcodierte REST-Request ist von einem Browser- oder SDK-Call nicht zu unterscheiden. Quota gilt pro Operation; MCP und REST teilen das Kontingent. Das Backend wächst keine zweite Schnittstelle für Agenten. Was sich ändert, ist die Entdeckung: Menschen haben OpenAPI gelesen; das Modell liest jetzt das JSON Schema in tools/list.

Also ist „kein MCP-Server zu betreiben“ nicht „kein JSON-Vertrag zu pflegen.“ Leere Descriptions, tiefe Objekte und übrig gebliebenes 2.0 zeigen sich bei der Entdeckung oder beim Transcoding. Siehe was MCP ist.

Der Vertrag wächst aus OpenAPI 3.x

Schalten Sie MCP am Dokument mit x-google-api-management.mcp ein. Pro Operation kann x-google-mcp-tool umbenennen, die Description neu schreiben oder mit false aussteigen. Jede exponierte Operation braucht ein Backend und eine nicht-leere Description. Nur GET / POST / PUT / PATCH / DELETE zählen. Tool-Namen müssen [A-Za-z0-9_.-]{1,128} matchen und auf dem Gateway eindeutig bleiben.

Die offizielle Minimalform (YAML auf der Seite; die Bedeutung ist ein JSON-Objekt):

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

Die Description ist das Hauptsignal, das das Modell für den Aufrufzeitpunkt nutzt. Google verlangt when / why, nicht nur was zurückkommt. Path-, Query-, Body- und Header-Schemas werden zu Tool-Arguments. Verschachtelte Objekte erscheinen in tools/list möglicherweise nicht vollständig — eine dokumentierte Preview-Grenze, kein kaputter Validator. Ziehen Sie die OpenAPI lokal glatt, dann Diff gegen das Input-Schema des Gateways.

tools/list ist default unauthentifiziert

Per Default kann jeder POST /mcp und den Katalog bekommen: Namen, Descriptions, Input-Schemas. Für Entwicklung in Ordnung. In Produktion veröffentlicht das den Parametervertrag. Google empfiehlt ein JWT auf tools/list. Im Public Preview kann ein API-Key diese Methode nicht schützen. Die Objektform schaltet MCP ebenfalls global ein; Operationen, die Sie nicht exponieren wollen, brauchen x-google-mcp-tool: false.

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

tools/call erzwingt immer die darunterliegende REST-Auth, ob Entdeckung gesperrt ist oder nicht. Ein offener Katalog und ein gesperrter Call sind zwei verschiedene Dinge. Sind Tool-Namen und Schemas sensibel, sperren Sie tools/list, bevor Sie ausliefern. Das ist dieselbe Schicht wie der Leitfaden zu bösartigem JSON: je breiter der Vertrag, den das Modell sieht, desto breiter die Injection-Fläche.

tools/call ist weiter JSON-RPC

Die On-the-Wire-Form in den Docs lautet:

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

Das Gateway mappt arguments zurück auf Path / Query / Body / Header, fährt Policy und packt die Backend-Antwort als MCP-Result. Beim Debuggen die Schichten trennen: der äußere Umschlag ist JSON-RPC; die innere Payload ist Business-JSON. Parse-Fehler gehören zu der einen Schicht oder der anderen. Das ADK-Sample zeigt Streamable HTTP auf …/mcp und kann weiter die Credentials senden, die das Gateway schon erwartet.

Hängen Sie das Gateway an API hub, und eine MCP-fähige Config erscheint mit MCP-Metadaten und taucht im Agent Registry auf. Das Verzeichnis hat sich geändert. Der Feldvertrag nicht: es ist weiter das Schema, das aus Ihrer OpenAPI wächst. Skill-Entdeckung ist ein anderes JSON-Dokument — siehe SEP-2640 und skill://index.json. Mischen Sie diese zwei Kataloge nicht in eine Tabelle.

Grenzen, die Sie im Public Preview lesen

• OpenAPI 2.0 ist nicht unterstützt. Zuerst auf 3.x heben.
• Operationen mit leerem Body (HTTP 204) werden nicht als Tools exponiert.
• Tief verschachtelte Objekt-Schemas können in tools/list abgeschnitten werden.
• Ein Gateway bedient bis etwa 1.000 Tools.
• MCP und Model Routing können sich keine API-Config teilen.
• Resources / Prompts, Response-Streaming und Model-Armor-Prüfung stehen weiter auf der Roadmap.

Das ist kein „später polieren.“ Eine 204-Operation verschwindet aus dem Katalog, und das Modell ruft etwas anderes. Ein abgeschnittenes Schema matcht weder einen strikten Validator noch das echte Backend. Der MCP-2026-Migrationsleitfaden handelt von Protokollversionen. Dieser Artikel legt nach: die Liste, die das Gateway erzeugt, muss nicht der vollen OpenAPI in Ihrem Repo entsprechen.

Vier JSON-Dokumente, bevor Sie den Schalter umlegen

1. Die OpenAPI 3.x im Repo. 2.0 zuerst heben. Jede exponierte Operation hat eine nicht-leere Description, ein Backend und einen legalen Tool-Namen.
2. Das tools/list des Gateways. Prüfen, ob Input-Schemas abgeschnitten wurden und ob Extra-Operationen durchgesickert sind.
3. Einen echten tools/call. Mappen arguments zurück auf REST? Ist der Umschlag JSON-RPC 2.0?
4. Das Entdeckungs-Security-Objekt. Nicht mit offenem tools/list ausliefern. Der JWT-Scheme-Name muss schon unter components.securitySchemes existieren.

Die Spec mit lokalen JSON-Tools prüfen

Bevor Sie MCP einschalten, drei Texte im Browser auslegen: die OpenAPI (YAML zuerst nach JSON wandeln), eine tools/list-Antwort und das arguments-Objekt, das Sie an tools/call senden.

• JSON-Validator — ist die Grammatik legal; wenn Sie ein Schema haben, Pflichtfelder und Extra-Keys zusammen prüfen.
• JSON ↔ YAML — die meiste OpenAPI lebt als YAML; wandeln Sie sie, bevor Sie gegen die Liste diffen.
• JSON Diff — das Parameters-Schema im Repo mit dem inputSchema vergleichen, das das Gateway zurückgegeben hat.

Nichts verlässt den Browser. Den Vertrag glattziehen, dann den Gateway-Schalter umlegen. Das Gateway transcodiert. Ihre Feldnamen und die required-Liste sollten nicht mit der Preview-Kürzung lockern.

FAQ

Fazit

API Gateway nimmt den MCP-Server-Prozess. Es nimmt nicht den JSON-Vertrag. OpenAPI 3.x wächst tools/list. tools/call bleibt JSON-RPC. Policy bleibt die REST-Policy, die Sie schon haben. Ein offener Katalog, ein abgeschnittenes Nested-Schema und eine fehlende 204-Operation sind Checks vor dem Launch — nicht „Preview an, fertig.“

Ziehen Sie die OpenAPI, die List-Antwort und ein Call-Sample lokal glatt, dann setzen Sie mcp: true. Das Gateway transcodiert. Der Feldvertrag sollte nicht mit den Preview-Grenzen lockern.