Das Umwandeln komplexer OpenAPI-Spezifikationen in MCP-Server ist eine spannende und herausfordernde Aufgabe, mit der sich viele Entwickler und Unternehmen auseinander setzen. Gerade im Zeitalter der Künstlichen Intelligenz und großer Sprachmodelle (LLMs) gewinnt diese Thematik an Bedeutung, da MCP-Server eine Brücke schlagen, um APIs als Werkzeuge für LLMs zugänglich zu machen. Während auf den ersten Blick die Umwandlung von OpenAPI zu MCP trivial erscheinen mag, offenbaren sich bei der praktischen Umsetzung viele Schwierigkeiten, die nicht nur technisches Know-how, sondern auch kreative Lösungen erfordern. Diese Erkenntnisse stammen aus der Praxis bei Stainless, einem Unternehmen, das sich darauf spezialisiert hat, Kunden bei der Generierung von Client SDKs sowie der Entwicklung von MCP-Servern aus ihren APIs zu unterstützen. Ein zentraler Vorteil von MCP-Servern liegt darin, dass sie APIs als eine Reihe von Tools darstellen, welche direkt von LLMs genutzt werden können.
Doch die Übersetzung von OpenAPI zu MCP-Servern erweist sich in vielen Punkten als komplexer als gedacht. OpenAPI und MCP-Tools basieren zwar beide auf JSON Schema, jedoch sind die Strukturen und Anforderungen unterschiedlich. Ein OpenAPI-Endpunkt beinhaltet oft getrennte Parameterarten wie Pfad-, Query- oder Header-Parameter sowie Request-Bodies, die in MCP-Servern zu einem einheitlichen Schema kombiniert werden müssen. Dies erfordert eine intelligente Zusammenführung, um Konflikte zu vermeiden und eine klare Schnittstelle zu schaffen. Ein weiteres Hindernis zeigt sich darin, dass MCP-Tools zwingend einen Objekttyp als Root-Schema benötigen.
OpenAPI-Spezifikationen hingegen erlauben auch primitive Datentypen wie Strings oder Arrays als alleinigen Request-Body. Diese müssen daher umgewandelt werden, indem sie als einzelne Eigenschaft innerhalb eines Objektes platziert werden. Ein typisches Beispiel demonstriert dies anschaulich: Ein Endpoint, der eine Liste von Namen im Request-Body erwartet, zusammen mit Pfad- und Query-Parametern, wird im MCP-Server zu einem Objekt mit mehreren Eigenschaften umgestaltet, die alle notwendigen Daten zusammenfassen. Eine besonders knifflige Herausforderung ist der Umgang mit $ref-Verweisen in OpenAPI. Diese dienen dazu, Schema-Komponenten mehrfach verwendbar zu machen und damit Redundanzen zu vermeiden.
MCP-Server verlangen jedoch selbstenthaltende Schemas, die keine externen Referenzen benötigen. Eine einfache Lösung ist, alle referenzierten Komponenten in einem $defs-Abschnitt zusammenzufassen und die Verweise entsprechend anzupassen. Problematisch wird es bei rekursiven Referenzen, die in manchen Datenmodellen für Beziehungen oder Hierarchien auftauchen. Hier hilft die Strategie, nur wichtige Wiederverwendungsmodelle als definierte $defs beizubehalten und andere Referenzen durch Inlining oder Eliminierung zu ersetzen, um Verwirrungen bei LLMs zu vermeiden. Die Anzahl der Endpoints in einer API kann ebenfalls zu Schwierigkeiten führen, insbesondere wenn die MCP-Schnittstelle zu viele Tools gleichzeitig bereitstellt.
Sprachmodelle verfügen über begrenzte Kontextfenster, die den Umfang der geladenen Tools beschränken. Um dem entgegenzuwirken, haben Entwickler Mechanismen geschaffen, mit denen Nutzer gezielt auswählen können, welche Tools oder Ressourcen in einem MCP-Server verfügbar sein sollen. Dabei gibt es Optionen, um einzelne Tools, ganze Ressourcen oder tagspezifische Gruppen zu importieren. Die Flexibilität bei der Zusammenstellung ermöglicht eine ressourcenschonende Nutzung und eine bessere Performance. Für sehr umfangreiche APIs oder unklares Nutzungsszenario wurde der Ansatz entwickelt, sogenannte Meta-Tools zu implementieren.
Diese drei Kernwerkzeuge erlauben es der KI, API-Endpunkte dynamisch zu entdecken, deren Schema einzusehen und sie bei Bedarf aufzurufen. Damit entfällt die Notwendigkeit, alle Tools dauerhaft im Kontext vorzuladen, was den Einsatz auch bei großen APIs mit vielen Endpoints ermöglicht. Der Umgang mit unterschiedlichen MCP-Clients bringt eine weitere Komplexitätsebene mit sich. Verschiedene Plattformen und Sprachmodelle interpretieren JSON-Schema nicht einheitlich und haben ihre eigenen Limitierungen. OpenAI-Modelle etwa unterstützen nur bestimmte Konstrukte wie anyOf, aber nicht allOf oder oneOf.
Andere Kunden wie Claude oder Cursor weisen eigene Einschränkungen bei der Tool-Anzahl, Namenslänge oder beim Verarbeiten von Referenzen auf. Eine universelle Lösung für alle ist kaum realisierbar und daher wurde bei Stainless das Konzept der "Client-Fähigkeiten" eingeführt. Mit dieser können Nutzer angeben, welche Schema-Features ihr Client unterstützt, und der MCP-Server passt das Schema automatisch an. Dadurch werden beispielsweise vereinfachte Schemata erzeugt, die auf anyOf verzichten oder Referenzen inline auflösen. Bei Features wie top-level union schemas, die von manchen Clients nicht unterstützt werden, wird die Funktionalität in mehrere Tools aufgeteilt, um Kompatibilität zu gewährleisten, ohne den Entwickler zu überfordern.
Ein besonderes Augenmerk liegt auf der Nutzbarkeit und Wartbarkeit der generierten MCP-Server. Stainless verfolgt den Ansatz, dass Entwickler eigene Anpassungen vornehmen können, indem sie individuell filterbare Tools einsetzen oder eigenen Code mit einbinden. Das erlaubt maßgeschneiderte Lösungen, die den spezifischen Anwendungsfall optimal bedienen, und gleichzeitig weiterhin von den Vorteilen der automatisierten Codegenerierung profitieren. Trotz all dieser technischen Herausforderungen zeichnet sich eine spannende Entwicklung ab. MCP-Server eröffnen neue Möglichkeiten, APIs nahtlos in den Kontext großer Sprachmodelle zu integrieren und somit neue Anwendungsfälle für Automatisierung, Datenabfrage und intelligente Assistenten zu erschließen.
Die Praxis hat gezeigt, dass es sich lohnt, frühzeitig die Eigenheiten und limitierenden Faktoren der verschiedenen Plattformen zu kennen und die Spezifikationen entsprechend zu gestalten. Parallel werden sich mit der Weiterentwicklung der Modelle und Clients auch die Möglichkeiten der Protokolle und Schema-Unterstützung verbessern. Das macht es für Entwickler attraktiv, heute schon in MCP-Technologien zu investieren und Erfahrungen in der Transformation komplexer OpenAPI-Spezifikationen zu sammeln. Für alle, die eigene APIs in MCP-Server umwandeln wollen, bietet Stainless mit dem kostenlosen Tool auf sdk.new einen guten Einstieg in die Thematik.
