OpenAPI als Quelle der Wahrheit für MCP-Server: Verträge, Schemata, Überprüfung

Der Vertrag steht an erster Stelle

Ein MCP-Server kann nicht klarer oder zuverlässiger sein als der API-Vertrag, auf dem er beruht. Viele Teams betrachten eine OpenAPI-Datei als Referenzmaterial für menschliche Entwickler oder als Rohdateneingang für Code-Generatoren. Wenn der Nutzer ein KI-Klient ist, übernimmt die Datei eine wichtigere Rolle: Sie beschreibt detailliert die Operationen, Eingaben, Ausgaben, Authentifizierungsverfahren sowie Umgebungen, die die MCP-Schicht getreu darstellen muss.

Ein praktisches Faustregel: Das OpenAPI-Dokument bleibt die Autorität bezüglich der Funktionalitäten der API, während die MCP-Konfiguration eine sorgfältig ausgewählte Darstellung dieses Dokuments für KI-Klienten ist. Dabei kann die Darstellung bestimmen, welche Operationen angezeigt werden, und wie sie präsentiert werden. Es darf auf keinen Fall Felder, Berechtigungen oder Geschäftslogiken erfinden, die in der zugrunde liegenden API nicht vorhanden sind.

Jemand, der einen Endpunkt liest, kann sich einige Beispiele ansehen und anschließend einen Kollegen bezüglich eines verwirrenden Parameters um Rat fragen. Ein KI-Klient verfügt nur über das, was die Tools und Schemata ihm mitteilen. Lücken in der Quelldokumentation treten direkt in die für die KI vorgesehene Schnittstelle über und nehmen in der Regel einige vertraute Formen an:

• ein Tool-Name, der nichts über die von ihm ausgeführte Aktion verrät
• ein Feld, das in der Praxis obligatorisch ist, aber als optional erscheint
• ein Enum ohne Liste der zulässigen Werte
• eine Antwort ohne nutzbare Struktur
• falsche Authentifizierungsdaten
• ein Staging-Server, der für ein Produktivsystem durchgehen könnte

Der Server startet weiterhin und das Tool erscheint weiterhin in der Entdeckungsfunktion. Doch der Client könnte die falsche Operation auswählen, ungültige Eingaben senden oder das Ergebnis falsch interpretieren. Daher ist eine API noch nicht für KI bereit, nur weil ihre OpenAPI-Datei korrekt parset wird. Sie ist bereit, wenn der Vertrag ausreichend Details enthält, damit ein anderes System die API korrekt nutzen kann.

Wer ist für welche Schicht verantwortlich?

OpenAPI beschreibt eine HTTP-API, während MCP Fähigkeiten für MCP-kompatible KI-Anwendungen bereitstellt. Sie arbeiten zusammen, sind aber nicht austauschbar, und jede kümmert sich um einen anderen Aspekt:

• Was die Operationen betrifft, definiert OpenAPI den Pfad und die Aktion, während MCP eine ausgewählte Operation als etwas darstellt, das ein Client entdecken kann.
• Was die Eingaben betrifft, definiert OpenAPI Parameter, Anfragekörper und Typen, während MCP diese in ein Eingabeschema umwandelt, mit dem der Client arbeiten kann.

Was die Ergebnisse betrifft, so geben OpenAPI-Dokumente Erfolgs- und Fehlerantworten wieder, während MCP die Ergebnisse in einer vom Client interpretierbaren Form liefert.

Was die Sicherheit angeht, so deklariert OpenAPI die Schemata und Anforderungen, und der MCP-Laufzeitmechanismus leitet die Anmeldeinformationen an die ursprüngliche API weiter.

Was die Umgebungen betrifft, so nennt OpenAPI Server und API-Versionen, während die MCP-Schicht den konfigurierten Endpunkt hostet und zugänglich macht.

Was die Historie betrifft, so verfolgt OpenAPI, wie sich der Vertrag entwickelt, während die MCP-Konfiguration die ausgewählte Funktionsausstattung sowie ihre Versionen trackt.

Diese Trennung verhindert einen klassischen Fehler: Den Namen eines Tools in einer MCP-Ansicht zu ändern und anzunehmen, dass sich dadurch auch der API-Vertrag geändert hat. Änderungen an der Darstellung gehören in die MCP-Konfiguration. Änderungen am Verhalten oder an den Schemata gehören in die ursprüngliche API-Definition.

Die wichtigsten OpenAPI-Felder

Nicht jedes Feld hat für einen KI-Client die gleiche Bedeutung. Einige prägen direkt die Oberfläche des entstehenden Tools.

Die operationId verleiht jeder Operation eine eindeutige Identität sowie einen Ausgangspunkt für den Toolnamen. Duplizierte oder unklare IDs erschweren die Auswahl der Tools. Die Felder summary und description sind es, die der Client liest, um zu entscheiden, ob ein Tool geeignet ist; daher machen knappe Formulierungen es schwierig, ähnliche Operationen voneinander zu unterscheiden. Der Pfad und die HTTP-Methode identifizieren die Aktion hinter dem Tool, und ein Fehler hier leitet die Funktionalität auf den falschen Weg.

Path- und Abfragemethoden definieren die Eingabefelder – ob sie erforderlich oder optional sind. Fehlende, falsch benannte oder falsch eingegebene Parameter führen zu fehlgeschlagenen Aufrufen. requestBody sowie seine Schemata beschreiben die strukturierte Eingabe für Erstellungs- und Aktualisierungsoperationen; ein unvollständiges Schema veranlasst die Clients, fehlerhafte Datenpakete zu senden. Antwort-Schemata erklären, was zurückgegeben wird, und schwache Definitionen machen es dem Client unmöglich, diese zu interpretieren.

securitySchemes sowie die dazugehörigen Anforderungen beschreiben, wie die Authentifizierung zur Laufzeit funktioniert, und falsche Angaben sorgen dafür, dass Tools, die zunächst gültig erscheinen, nach Übermittlung der Zugangsdaten versagen. Der Eintrag servers oder die Host-Konfiguration geben an, welches Umfeld die Anfrage erhält; daher kann eine fehlerhafte URL Test- oder Produktverkehr an die falsche Stelle leiten. Schließlich liefern info.version sowie die Änderungshistorie den Überprüfern eine Grundlage, und ohne sie kann eine Abweichung erst dann erkennbar werden, wenn die Tools nicht mehr funktionieren. Die Qualität all dieser Felder bestimmt, wie umfangreich eine Überprüfung vor der Auswahl und Veröffentlichung von Funktionen durch ein Team erforderlich ist.

Operation IDs als stabile Bezeichnungen

Eine operationId dient einem größeren Zweck als die Erstellung von SDKs. Sie verleiht jeder Operation eine Identität, die auch nach Änderungen in der Beschreibung oder Darstellung der API bestehen bleibt. Gute IDs sind im gesamten Dokument eindeutig, beschreiben genau, was der Benutzer sieht, weisen einen einheitlichen Stil auf und sind stabil genug, um sie in späteren Überprüfungen wiederzuerkennen. Namen wie list_projects, get_invoice oder create_ticket sind weitaus leichter zu verstehen als request1, endpointA oder eine generierte Zeichenkette ohne geschäftliche Bedeutung.

Stabilität hilft auch bei der Wartung. Wenn jemand eine Beschreibung ändert, ein Antwortfeld hinzufügt oder einen Parameter verändert, kann das Team erkennen, welche MCP-Funktionalität betroffen ist, anstatt die gesamte Tool-Liste als einen Haufen unbekannter Endpunkte zu betrachten.

Beschreibungen als Entscheidungshilfe

Eine Beschreibung eines Tools ist keine Dekoration. Der KI-Client verwendet sie, um zu entscheiden, was zu tun ist, daher sollte sie angeben, welche Aufgabe durchgeführt wird, wann sie verwendet werden soll, welchen Ressourcen sie zugrunde liegt, welche Eingaben erforderlich sind, welche Einschränkungen gelten und ob Daten gelesen oder der Zustand geändert wird.

Nehmen wir zwei Versionen für eine Operation zur Aktualisierung eines Projekts. Die schwächere besagt lediglich „Projekt aktualisieren“. Die stärkere erklärt, dass dadurch der Name, die Beschreibung oder der Status eines bestehenden Projekts geändert werden, dass sie angewendet werden soll, wenn der Benutzer ein Projekt ausgewählt hat und eindeutig die gespeicherten Details ändern möchte, und dass sie nicht zur Erstellung eines neuen Projekts verwendet werden darf. Die zweite Version zieht eine klare Linie zwischen Aktualisieren und Erstellen und macht das verhaltensbezogene Ändern des Zustands für Prüfer deutlich.

Die Quelldatei im OpenAPI-Format sollte überall dort sinnvolle Zusammenfassungen und Beschreibungen enthalten. Viele Plattformen ermöglichen es Teams, nach dem Import Namen und Beschreibungen von Funktionen zu ändern, was der Präsentation gegenüber KI-Systemen hilft. Dennoch müssen Parameter und Verhaltensweisen in der ursprünglichen API-Definition festgelegt sein.

Schemata, die ein Client verwenden kann

Allein die Namen der Parameter reichen nicht aus, denn ein Client benötigt ein Schema, auf das er sich stützen kann. Eingabeschemata sollten zeigen, welche Felder obligatorisch sind und welche Datentypen sie haben, ob ein Wert aus einer Enum-Liste stammt oder frei eingegeben werden kann, wie Datumsangaben, IDs und Beträge formatiert werden müssen, welche unteren und oberen Grenzen gelten, sowie wie verschachtelte Objekte und Arrays strukturiert sind. Ausgabeschemata sollten alles offenlegen, was es einem Client ermöglicht, zum nächsten Schritt überzugehen. Angenommen, ein Endpunkt gibt ein Projekt mit ID, Status, Eigentümer und Zeitstempeln zurück: Modellieren Sie jedes dieser Elemente genau, damit sie nicht in einem unstrukturierten Datensatz verloren gehen.

Die Genauigkeit beeinflusst sowohl Erfolg als auch Misserfolg. Ein als optional markiertes Feld, das die API tatsächlich erfordert, kann den Client in einen Kreislauf von ungültigen Anfragen bringen, während ein als erforderlich markiertes Feld, das die API nicht mehr akzeptiert, einen legitimen Arbeitsablauf blockieren kann. Referenzen müssen ebenfalls korrekt funktionieren. Wiederverwendbare Komponenten sind eine Stärke von OpenAPI, doch ein fehlerhafter $ref oder eine unvollendete verschachtelte Definition kann dazu führen, dass eine generierte Funktionalität nicht über ausreichende Informationen verfügt, um Eingaben zu validieren.

Sicherheit ist dokumentiert, nicht garantiert

OpenAPI kann API-Schlüssel, Bearer-Tokens, OAuth-Flüsse sowie die Anforderungen beschreiben, die mit jeder Operation verbunden sind – dies gibt der MCP-Schicht an, wie Anfragen authentifiziert werden sollen. Das ist jedoch noch nicht das vollständige Bild der Sicherheit. Im Laufzeitbetrieb muss ein Team dennoch vier Dinge überprüfen: Die vorgesehenen Zugangsdaten stammen vom MCP-Klienten, sie erreichen die ursprüngliche API unverändert, die API setzt Tenant- und Benutzerrechte durch, und abgelaufene oder fehlerhafte Zugangsdaten erzeugen ein Ergebnis, das sicher ist und leicht diagnostizierbar.

Ein gängiges Design ist der Credential-Pass-Through. Der Client stellt eine API-Schlüssel, einen Bearer-Token oder einen OAuth-Token bereit, und die MCP-Laufzeitleistung leitet diesen bei jeder Anfrage an die ursprüngliche API weiter, ohne die Kundenanmeldedaten zu speichern. Im Rahmen dieses Modells bleibt die API selbst für die Geschäftsautorisierung, die Grenzen der Nutzer sowie den Zugriff auf Datensätze verantwortlich. Sicherheitsanforderungen erfordern genaue Dokumentation, und die Authentifizierung sollte mit Anmeldedaten getestet werden, die denen in der Realität ähneln.

Entscheidung darüber, was offengelegt werden soll

Eine OpenAPI-Datei kann eine gesamte Produkt-API beschreiben, doch der MCP-Server sollte nur den Teil bereitstellen, der nützliche, sichere AI-Arbeitsabläufe unterstützt. Der Quellvertrag gibt an, welche Operationen vorhanden sind und wie sie funktionieren. Eine separate Überprüfung der Funktionalitäten bestimmt, welche davon ein AI-Klient sehen sollte. Dabei werden der Kundennutzen, die Sensitivität der Daten, das Risiko von Zustandsänderungen, die Abhängigkeitsbeziehungen zwischen den Operationen, die Klarheit der Beschreibungen, die Autorisierungsregeln sowie die Gesamtzahl der dem Klienten angezeigten Tools berücksichtigt.

Tools können die mechanischen Schritte automatisieren, wie beispielsweise das Importieren einer unterstützten Swagger- oder OpenAPI-Definition, die Auflistung der erkannten Operationen sowie die Erstellung oder Aktualisierung von Tools, Ressourcen und Anweisungen. Das Team entscheidet weiterhin, welche Funktionalitäten das Produkt am besten repräsentieren.

Validierung vor der Produktion

Führen Sie vor dem Erstellen einer Produktiv-MCP-Schnittstelle eine Validierung durch, beginnend mit der Struktur. Überprüfen Sie, ob die OpenAPI- oder Swagger-Version unterstützt wird, ob Pfade und Methoden gültig sind und ob sich die Operationen IDs nicht wiederholen. Stellen Sie sicher, dass jedes $ref korrekt verarbeitet wird, dass die Anfrage- und Antwort-Schemata vollständig sind, dass die Server-URLs und Basispfade richtig sind und dass Sicherheitsschemata den richtigen Operationen zugeordnet sind.

Danach folgt eine Überprüfung der Bedeutung. Spiegeln die Beschreibungen das tatsächliche Verhalten wider, und sind die erforderlichen Felder tatsächlich notwendig? Prüfen Sie, ob die Beispiele sicher und aktuell sind, ob deaktivierte Operationen klar gekennzeichnet sind, ob die Antworten die Felder enthalten, die ein KI-Arbeitsablauf benötigt, und ob Leseoperationen von solchen getrennt bleiben, die den Zustand ändern.

Frühe Rückmeldungen aus der Validierung sind wertvoll, da die beiden Arten von Befunden unterschiedlichen Gewichts sind. Eine Warnung wegen eines fehlenden Beschreibungen weist auf ein Designproblem hin, während eine ungelöste Schema-Referenz zu einem Fehlschlag während der Ausführung führen kann.

Zwei Artefakte, zwei Verantwortliche

Hinter jeder Integration, auf die KI-Kunden vertrauen können, stehen zwei miteinander verknüpfte Artefakte: der API-Vertrag sowie die MCP-Konfiguration, die die verfügbaren Funktionen auswählt und anzeigt. Jedes davon benötigt einen eindeutig benannten Verantwortlichen.

Das Eigentum an der API-Definition umfasst Routen, Methoden, Anfrage- und Antwortfelder, die dahinterliegenden Typen, Formate und Einschränkungen, Authentifizierungsverfahren, Versionsdetails sowie das tatsächlich von dem Service umgesetzte Verhalten. Die MCP-Konfiguration enthält die Liste der bereitgestellten Operationen, die Auswahl von Werkzeugen, Ressourcen und Anfragen, die für die KI verwendeten Namen und Beschreibungen, den MCP-Namen samt seinem gehosteten Domainnamen sowie die gespeicherte Konfigurationsversion.

Falls sich das API-Schema ändert, sollte man mit der Quelldefinition beginnen. Anschließend muss man die davon betroffenen MCP-Konfigurationen durchgehen, die geänderten Funktionen ausprobieren und eine Version veröffentlichen, die bei Bedarf zurückgesetzt werden kann. Gute Plattformen unterstützen das Speichern von Konfigurationsversionen, die Überprüfung von Änderungen, das Wiederherstellen einer früheren Version sowie das Aktualisieren eines gehosteten Servers ohne Neubau und ohne Änderung der URL.

Die Quelle der Wahrheit aktuell halten

Eine Quelle der Wahrheit ist nur dann nützlich, wenn sie stets auf dem neuesten Stand gehalten wird. Die für KI vorgesehene Schnittstelle kann beeinflusst werden, wenn ein erforderlicher Parameter hinzugefügt oder entfernt wird, ein Enum-Wert sich ändert, eine Operation veraltet ist, ein Endpunkt eine neue Struktur zurückgibt, die Anmeldeanforderungen sich ändern oder eine Autorisierungsregel strenger wird. Während das normale Anwendungsverkehr weiterfließen kann, wird das MCP-Tool stillschweigend irreführend – daher verdienen OpenAPI-Updates denselben Überprüfungsprozess wie Code- und API-Veröffentlichungen.

Ein praktischer Wartungszyklus umfasst sieben Schritte:

1. Die OpenAPI-Definition aktualisieren, um die Änderung widerzuspiegeln.
2. Das Dokument validieren und alle Warnungen beseitigen.
3. Ermitteln, welche MCP-Funktionen betroffen sind.
4. Namen, Beschreibungen, Schemata sowie Sicherheitsanforderungen überprüfen.
5. Beispielhafte erfolgreiche und fehlgeschlagene Aufrufe testen.
6. Eine neue Version der MCP-Konfiguration veröffentlichen.

Überwachen Sie nach dem Rollout Fehler, Latenzzeiten sowie die Tool-Nutzung.

Nach dem Go-Live ist ein interaktiver Playground nützlich, um Funktionen zu überprüfen, Tools aufzurufen, Ressourcen und Anfragen zu testen, die Authentifizierung zu überprüfen sowie individuelle Nutzungslogs einzusehen.

Ein verwalteter Weg von API zu gehostetem MCP

Einerseits basiert ein Ansatz auf der Idee, dass SaaS-Teams ihre API nicht neu schreiben müssen, um bestimmte Funktionen über MCP anzubieten. Der Ablauf beginnt mit dem Import einer unterstützten API-Definition oder einer Postman-Kollektion sowie der Erkennung der verfügbaren Operationen. Anschließend werden Validierungsfehler und Warnungen überprüft, danach werden die für die KI-zentrierte Schnittstelle geeigneten Operationen ausgewählt und Tools, Ressourcen sowie Anfragen erstellt oder aktualisiert. Namen und Beschreibungen werden dort geändert, wo eine Verbesserung der Darstellung notwendig ist, die Authentifizierung während der Ausführung wird über die ursprüngliche API konfiguriert, und der gehostete Server wird vor dem Anschluss echter Nutzer getestet. Danach werden Konfigurationsversionen veröffentlicht und im Laufe der Zeit verwaltet.

In diesem Modell wird der generierte Server über Streamable HTTP gehostet, wobei die Plattform die Hosting-Infrastruktur betreibt, und lokale stdio-Server werden nicht unterstützt. Die API bleibt das zentrale System für die Geschäftslogik und Autorisierung. Die Plattform liefert die Konvertierung, einen gehosteten Endpunkt, Konfigurationssteuerungen sowie Betriebsansichten im Rahmen der MCP-Schnittstelle.

Fazit

OpenAPI ist weitaus mehr als nur eine Importdatei. Es handelt sich um einen Vertrag, der einer MCP-Integration mitteilt, was jede Operation bedeutet, welche Eingaben sie benötigt, wie die Authentifizierung funktioniert und was ein KI-Klient zurück erhalten sollte. Bei einem präzisen Vertrag kann die MCP-Schicht eine zuverlässige Abstraktion bleiben, die die richtigen Funktionen auswählt, sie klar präsentiert und sicher ausführt. Bei einem unklaren oder veralteten Vertrag führt die Codegenerierung lediglich dazu, dass die Unklarheiten schneller verbreitet werden.

Betrachten Sie OpenAPI als Quelle der Wahrheit und MCP als Schnittstelle für KI-Systeme, und verknüpfen Sie die Änderungen beider mit Validierung, Testing, Überwachungsfunktionen sowie Versionskontrolle. Dadurch wird eine bestehende API zu einer wartbaren Grundlage für KI-fähige Tools.