OpenAPI zu MCP

In vielen Backend-Teams sind die wichtigsten APIs bereits über OpenAPI beschrieben. Damit ist ein großer Teil der fachlichen und technischen Vorarbeit erledigt. Was häufig noch fehlt, ist eine zusätzliche Schicht, über die ausgewählte Endpoints kontrolliert für KI-Agenten nutzbar werden. Genau hier setzt ein MCP-Server an, der aus einer bestehenden OpenAPI-Spec abgeleitet wird.

Die Konvertierung von OpenAPI zu MCP ist auf konzeptioneller Ebene gut greifbar, weil beide Ansätze Funktionen mit Input- und Output-Schemas beschreiben. Die eigentliche Herausforderung liegt weniger in der technischen Mechanik, sondern in der fachlichen Auswahl. Welche Endpoints sollen Agenten nutzen dürfen? Wie müssen Tools beschrieben sein, damit ein Agent sie sinnvoll einsetzen kann? Und wie bleiben Auth, Quotas und Audit auch in agentischen Workflows zuverlässig kontrollierbar?

Warum die Konvertierung von OpenAPI zu MCP sinnvoll ist

Viele Enterprise-APIs sind heute bereits mit OpenAPI dokumentiert. Wer KI-Agenten in bestehende Workflows integrieren möchte, kann damit auf eine Grundlage aufsetzen, die in den letzten Jahren aufgebaut, abgestimmt und gepflegt wurde. Einen MCP-Server aus dieser Basis abzuleiten, ist in der Regel deutlich effizienter, als parallel eine zweite Spezifikationswelt für Agenten aufzubauen.

Die wichtigsten Vorteile einer OpenAPI-zu-MCP-Konvertierung zeigen sich vor allem in drei Bereichen, nämlich bei der Wiederverwendung von Schemas, bei der zentralen Steuerung von Auth und beim Werterhalt bestehender Linter-Investitionen.

Schemas werden wiederverwendet. Was in der OpenAPI-Spec als Component-Schema definiert ist, kann als Tool-Input- oder Output-Schema in MCP übernommen werden. Felder, Required-Markierungen und Enum-Werte bleiben dadurch konsistent, unabhängig davon, ob ein Mensch oder ein Agent die API nutzt. Das reduziert die Gefahr, dass sich beide Nutzungswelten fachlich auseinanderentwickeln.

Auth bleibt zentral steuerbar. OAuth-2.0-Flows, API-Keys und JWT-Token, die in der OpenAPI-Spec deklariert sind, können über das MCP-Auth-Profil weitergereicht werden. Der Agent authentifiziert sich damit bei demselben Identity Provider wie menschliche Konsumenten. Die bestehende Berechtigungslogik im Backend muss nicht neu erfunden werden.

Linter-Investitionen zahlen sich weiter aus. Eine OpenAPI-Spec, die bereits durch einen API-Linter läuft, ist auch für die MCP-Exposition besser vorbereitet. Konsistente Naming-Konventionen, vollständige Schemas und gepflegte Beschreibungen werden in MCP-Tools unmittelbar sichtbar.

Ein weiterer Vorteil liegt in der organisatorischen Vorarbeit. Teams, die bereits Style Guides, Linter-Konfigurationen und Versionierungsprozesse für ihre OpenAPI-Specs aufgebaut haben, können diese Grundlagen für MCP weiterverwenden. Was für menschliche API-Konsumenten funktioniert, bildet auch für die MCP-Exposition eine stabile Basis. Ein separater MCP-Spec-Pfad würde dagegen viele Investitionen wiederholen, die im OpenAPI-Kontext bereits geleistet wurden.

Welche Endpoints sich für die MCP-Exposition eignen

Nicht jeder Endpoint eignet sich automatisch für die Nutzung durch KI-Agenten. Die Auswahl ist deshalb einer der wichtigsten Schritte bei der Konvertierung von OpenAPI zu MCP, und drei Kriterien helfen dabei, geeignete Endpoints zu identifizieren, nämlich Read-First-Vorgehen, klare Verantwortlichkeit und stabile Schemas.

Read-First. Die ersten MCP-Tools eines Teams sollten idealerweise lesende Endpoints sein. GET-Operationen sind vergleichsweise risikoarm, weil ein fehlerhafter Aufruf zwar unnötige oder unpassende Daten liefern kann, aber keine Zustände verändert. Schreibende Endpoints sollten erst folgen, wenn das Team verstanden hat, wie Agent-Aufrufe in der Praxis aussehen und wie sie im Audit nachvollzogen werden können.

Klare Verantwortlichkeit. Endpoints mit einer eindeutig abgegrenzten Wirkung im Backend eignen sich besser als Endpoints mit vielen Seiteneffekten. Eine Such-API ist für Agenten meist gut geeignet. Eine Workflow-Trigger-API, die mehrere Backend-Systeme anstößt, ist deutlich schwieriger zu kontrollieren. Als Faustregel gilt, dass jeder Tool-Aufruf mit einem klar verständlichen Audit-Eintrag rückverfolgbar sein sollte.

Stabile Schemas. Endpoints mit häufig wechselnden Schemas oder sehr vielen optionalen Parametern sind für Agenten schwerer nutzbar. Wenn ein Tool in einer Woche zehn Felder erwartet und in der nächsten zwölf, steigt die Wahrscheinlichkeit fehlerhafter Aufrufe. Stabile, gut gepflegte Endpoints sind deshalb die bessere Grundlage für MCP-Tools.

In regulierten Branchen wird diese Auswahl noch wichtiger. Ein Banking-Team, das eine PSD2-API über einen MCP-Server exponieren möchte, muss zusätzlich prüfen, welche Tool-Aufrufe regulatorisch dokumentiert werden müssen. Bei einer Healthcare-API mit HL7-FHIR-Profil gelten vergleichbare Anforderungen, insbesondere wenn Patientendaten betroffen sind. Solche Compliance-Aspekte können einzelne Endpoints ausschließen, auch wenn sie technisch für Agenten geeignet wären.

Mapping OpenAPI zu MCP konkret

Das technische Mapping von OpenAPI zu MCP ist in vielen Fällen gut beherrschbar, und für die meisten Anwendungsfälle reichen vier zentrale Zuordnungen aus, nämlich Operation zu Tool, Schema zu Schema, Auth-Mechanismus zu MCP-Auth-Profil und die Anpassung der Beschreibungen für Agenten.

Operation zu Tool. Jede OpenAPI-Operation, also die Kombination aus Pfad und HTTP-Methode, kann zu einem MCP-Tool werden. Die operationId aus der Spec bietet sich als Tool-Name an, weil sie bereits eindeutig sein sollte und meist fachlich nachvollziehbar ist.

{
  "name": "getCustomerOrders",
  "description": "Liefert die Bestellungen eines Kunden, optional limitiert auf eine Anzahl",
  "inputSchema": {
    "type": "object",
    "properties": {
      "customerId": { "type": "string", "format": "uuid" },
      "limit": { "type": "integer", "default": 10 }
    },
    "required": ["customerId"]
  }
}

Schema zu Schema. Component-Schemas aus der OpenAPI-Spec können als Tool-Input- und Output-Schemas übernommen werden. JSON-Schema-Konstrukte wie oneOf, anyOf und allOf werden in beiden Welten unterstützt. Ab OpenAPI 3.1 ist die Spezifikation zudem vollständig an JSON Schema angelehnt.

Auth-Mechanismus zu MCP-Auth-Profil. OAuth-2.0-Flows aus der OpenAPI-Spec werden über das MCP-Auth-Profil weitergereicht. Der Agent authentifiziert sich dadurch bei demselben Identity Provider wie menschliche API-Konsumenten. Dadurch lassen sich Agent-Aufrufe in denselben Audit-Trail einordnen wie reguläre API-Calls.

Beschreibungen anpassen. Was in OpenAPI als summary und description für menschliche Entwickler geschrieben wurde, reicht für Agenten oft nicht aus. MCP-Tools brauchen klarere Hinweise dazu, wann ein Tool verwendet werden soll und wann nicht. Genau hier wird aus einer rein mechanischen Konvertierung ein bewusstes Tool-Design für Agenten.

Einige Edge Cases tauchen beim Mapping immer wieder auf. Multi-Format-Endpoints, die neben application/json auch application/xml anbieten, brauchen eine bewusste Entscheidung, welches Format der Agent tatsächlich verwenden soll. File-Upload-Endpoints lassen sich zwar technisch über MCP exponieren, passen aber oft schlecht zu typischen Agent-Workflows, weil das File-Handling außerhalb der eigentlichen Agent-Konversation stattfindet. Auch Endpoints mit komplexen Hypermedia-Verweisen, etwa HATEOAS-Strukturen, sollten geprüft werden, da Agenten meist besser mit klaren und flacheren Antwortstrukturen arbeiten.

Tool-Design für Agenten

MCP-Tools für Agenten brauchen eine andere Form der Beschreibung als klassische API-Endpoints für menschliche Entwickler. Besonders wichtig sind dabei drei Aspekte, nämlich Beschreibungen aus Agent-Sicht, eine bewusste Parameter-Reduktion und eine klare Output-Strukturierung.

Beschreibungen aus Agent-Sicht. Eine Tool-Description sollte so formuliert sein, dass ein Agent den Zweck des Tools eindeutig erkennen kann. „Liefert die letzten Bestellungen eines Kunden und eignet sich für Support-Anfragen, bei denen der aktuelle Bestellstatus benötigt wird" ist für einen Agenten deutlich hilfreicher als „GET /customers/{id}/orders". Die technische Pfad-Notation beschreibt zwar den Endpoint, erklärt aber nicht den sinnvollen Einsatzkontext.

Parameter-Reduktion. Viele optionale Parameter erhöhen die Wahrscheinlichkeit, dass ein Agent Werte rät oder falsch kombiniert. In einfachen Fällen funktioniert das oft, bei Edge Cases entstehen jedoch schnell unpassende Aufrufe. Optionale Parameter sollten deshalb nur dann übernommen werden, wenn die Beschreibung klar macht, wann und wie sie zu verwenden sind. Häufig sind zwei oder drei spezifische Tools besser als ein sehr universelles Tool.

Output-Strukturierung. Tool-Antworten sollten so aufgebaut sein, dass der Agent die wichtigsten Informationen schnell erkennen kann. Sehr lange JSON-Strukturen mit vielen Feldern erschweren die Interpretation und erhöhen das Risiko, dass der Agent die falschen Details in den Vordergrund stellt. Hilfreich ist ein zusätzliches zusammenfassendes Feld, zum Beispiel summary: "3 Bestellungen, davon 2 offen".

Auth, Quotas und Audit

Ob ein MCP-Server produktiv betrieben werden kann, hängt nicht nur vom Mapping ab, sondern vor allem von drei Querschnittsthemen, nämlich Auth, Quotas und Audit.

Auth-Profil. Für produktive MCP-Server ist ein OAuth-2.0-basiertes Authentifizierungsprofil zentral. Der Agent erhält ein Token, das gegen dieselben Scopes geprüft wird wie bei menschlichen API-Konsumenten. Anonyme MCP-Server ohne Auth sollten auf Test- und Demo-Umgebungen beschränkt bleiben.

Quotas und Rate-Limits. Agenten können in kurzer Zeit viele Aufrufe auslösen, besonders wenn sie iterativ arbeiten oder mehrere Lösungswege ausprobieren. Ohne Quotas besteht das Risiko, dass ein Agent unbeabsichtigt eine Aufrufwelle erzeugt und Backend-Systeme belastet. Pro-Token-Quotas und globale Rate-Limits sind deshalb ein notwendiges Mindestmaß.

Audit. Jeder Tool-Aufruf sollte einen Audit-Eintrag erzeugen, der Token-Identität, Tool-Name, Parameter und Ergebnis enthält. Diese Spur ist nicht nur für Compliance relevant, sondern auch für die Weiterentwicklung des Tool-Designs. Wer die Audit-Logs in den ersten Wochen auswertet, erkennt schnell, welche Tools unklar beschrieben sind, selten genutzt werden oder häufig mit falschen Parametern aufgerufen werden.

In regulierten Umfeldern kommt häufig eine weitere Ebene hinzu. Compliance-Reporting kann verlangen, dass Tool-Aufrufe nicht nur protokolliert, sondern zusätzlich klassifiziert werden, etwa nach Datensensitivität oder Geschäftsprozess. Diese Klassifizierung sollte direkt in der Tool-Definition hinterlegt werden, idealerweise als Metadata-Block, der gemeinsam mit dem MCP-Tool versioniert wird. So bleibt die Auditierbarkeit auch über Tool-Änderungen hinweg konsistent.

Test- und Validierungs-Strategie

Ein MCP-Server braucht eine eigene Test- und Validierungsschicht. Die reine Prüfung der zugrunde liegenden API reicht nicht aus, weil Agenten Tools anders nutzen als menschliche Entwickler. Drei Test-Ebenen haben sich dafür bewährt, nämlich Tool-Schema-Validierung, Agent-Smoke-Tests und die Auswertung der Production-Audits.

Tool-Schema-Validierung. Vor jedem Deploy sollte geprüft werden, ob jedes Tool eine valide JSON-Schema-Definition hat und ob die description gepflegt ist. Diese Prüfung ist mechanisch und gehört in die CI-Pipeline.

Agent-Smoke-Tests. Ein realer Agent, etwa Claude, Cursor oder ein eigener Test-Agent, führt gegen den MCP-Server eine vordefinierte Reihe von Aufgaben aus. Dabei wird geprüft, ob der Agent die passenden Tools auswählt und ob die Tool-Aufrufe sinnvolle Ergebnisse liefern. Solche Tests sind weniger deterministisch als klassische Unit-Tests, decken aber Probleme auf, die bei rein syntaktischer Validierung verborgen bleiben.

Production-Audit-Auswertung. Die ersten Wochen nach dem Deploy zeigen, welche Tools tatsächlich genutzt werden, welche Parameter typisch sind und welche Tools kaum eine Rolle spielen. Aus dieser Auswertung entstehen die nächsten Iterationen im Tool-Design.

Wie api-portal.io OpenAPI zu MCP unterstützt

In api-portal.io lassen sich MCP-Server direkt aus bestehenden OpenAPI-Specs erzeugen. Die Endpoint-Auswahl ist konfigurierbar, Auth-Mapping erfolgt automatisiert und Audit-Logging ist integriert. Tool-Beschreibungen können gezielt für den Agent-Use-Case angepasst werden, ohne die zugrunde liegende OpenAPI-Spec zu verändern. Quota-Management, Token-Verwaltung und Versionierung stehen als Standardfunktionen bereit.

Der MCP Server macht bestehende APIs kontrolliert für MCP-Szenarien nutzbar und schafft damit die Verbindung zwischen vorhandener OpenAPI-Dokumentation und agentischen Workflows.