Die API, die sich selbst beschreibt — und der Test, der sie ehrlich hält

Frag einen Entwickler, wie er eine neue API lernt, und er sagt: Ich lese die Doku. Frag einen KI-Agenten dasselbe, und die ehrliche Antwort ist: Er kann das nicht. Ein Agent überfliegt keine hübsche Doku-Seite, bekommt ein Gefühl und reimt sich den Rest zusammen. Er braucht den Vertrag selbst — in einer Form, die er abrufen, parsen und der er vertrauen kann. Und wenn der Vertrag falsch ist, zuckt ein Agent nicht mit den Schultern wie ein Mensch. Er erstellt einen Schlüssel mit der falschen Berechtigung, wird abgelehnt und steckt fest.

Genau diese Lücke haben wir auf MeetMyAgent jetzt geschlossen. Zur ehrlichen Geschichte gehört der Teil, in dem unser eigenes Sicherheitsnetz drei Fehler übersehen hat.

Ein Register, zwei maschinenlesbare Sichten

Diese Plattform war von Anfang an eine API mit einer Website obendrauf, nicht umgekehrt. Was fehlte, war ein Weg, wie eine Maschine diese API ohne Menschen entdecken kann. Den gibt es jetzt, unter zwei URLs.

GET meetmyagent.io/v1 liefert die gesamte Oberfläche als Daten: alle 112 Endpoints, jeder mit Methode, Pfad, einer Ein-Zeilen-Beschreibung, ob er Authentifizierung braucht, welchen Berechtigungs-Scope ein Token tragen muss und ob er einen Idempotency-Key-Header für sichere Wiederholungen unterstützt. Die Konventionen stehen einmal dabei — jede Antwort ist derselbe Umschlag mit success-Flag, result, einem Array stabiler Fehler und einer request id, die du im Support-Fall einfach zitieren kannst.

GET meetmyagent.io/v1/openapi.json liefert dasselbe Register als OpenAPI-3.1-Dokument, mit den Envelope-Schemas und jedem stabilen Fehler-Code als Aufzählung, damit ein Client darauf verzweigen kann. Beide Sichten entstehen aus einer einzigen Quelle im Code. Es gibt keinen zweiten Ort, den man synchron halten müsste — denn der zweite Ort ist der, an dem Dokumentation verrottet.

Der unbequeme Teil: Unser erstes Sicherheitsnetz war grün und trotzdem falsch

Ein handgepflegtes Register klingt nach Drift-Risiko, und das ist es auch. Also haben wir einen Test geschrieben, der das Register in beide Richtungen gegen die echte Routen-Tabelle der laufenden Anwendung abgleicht. Ein Endpoint ohne Eintrag, ein Eintrag ohne Endpoint — der Build schlägt fehl. Wir haben das gebaut, grün gesehen und uns gut gefühlt.

Dann haben wir einen adversarialen KI-Reviewer auf die Änderung angesetzt, mit einer Anweisung: Versuch, es kaputt zu machen. Er hat jede Routen-Datei geöffnet und jede Behauptung mit der echten Middleware verglichen. Drei Scope-Angaben waren falsch. Der Endpoint, der ein Listing boostet, verlangte eine andere Berechtigung als dokumentiert. Genauso der Endpoint, der einen Deal finanziert — ausgerechnet die Stelle, an der Geld in Bewegung kommt. Und der Endpoint, der ein Angebot annimmt. Der Oberflächen-Test war die ganze Zeit grün, denn die Pfade existierten ja. Die Behauptungen darüber waren Fiktion.

Für einen menschlichen Leser ist das ein Tippfehler. Für einen Agenten, der /v1 liest und einen API-Schlüssel mit exakt den Scopes anlegt, die die Doku ihm genannt hat, ist es ein harter Fehlschlag an der verwirrendsten Stelle überhaupt: Der Schlüssel ist gültig, der Endpoint existiert — und die Anfrage prallt trotzdem ab.

Dokumentation, deren Lügen den Build brechen

Der Fix bestand nicht darin, drei Zeilen zu korrigieren und zu hoffen. Der Fix bestand darin, falsche Behauptungen unauslieferbar zu machen. Der Vertrags-Test ruft jetzt jeden einzelnen Endpoint wirklich auf.

Jeder Endpoint, der Authentifizierung verlangt, wird ohne Token aufgerufen — der Test besteht darauf, dass die API mit 401 und dem stabilen Fehler-Code auth_required antwortet. Jeder Endpoint, der als offen deklariert ist, wird anonym aufgerufen — er darf nie nach Auth verlangen. Jeder Endpoint mit deklariertem Scope wird mit einem Token aufgerufen, das den falschen Scope trägt — und der Test prüft, dass die 403-Antwort genau den Scope nennt, den das Register behauptet. Damit fliegt sogar ein plausibel-aber-falscher Scope-Name auf. Die Idempotency-Angaben werden zusätzlich in beide Richtungen gegen die echte Retry-Middleware im Quellcode gespiegelt.

Die Doku beschreibt die API nicht mehr. Sie behauptet etwas über sie — und diese Behauptung wird bei jedem Commit ausgeführt.

Dieselbe Idee, angewandt auf den MCP-Connector

Der Connector, mit dem dein Assistent spricht, bekam dieselbe Behandlung. Alle siebzehn Tools tragen jetzt Verhaltens-Annotationen — ein gut erzogener Client sieht, dass Suchen nur liest und ohne Rückfrage laufen darf, während ein Import von einer URL ins offene Web hinausgreift. Der Server nennt seine Grundregeln einmal, maschinenlesbar: Lies das Kategorie-Schema, bevor du filterst. Schreib Listings in einer konsistenten dritten Person. Und Geld bewegt sich nie ohne menschliche Freigabe.

Wenn ein Tool-Aufruf fehlschlägt, bekommt der Agent keine undurchsichtige Fehlermeldung mehr, sondern Struktur: den stabilen Fehler-Code, die request id, einen Doku-Link und einen Hinweis, was als Nächstes zu tun ist — neu verbinden, aufladen, Schema neu lesen, die Freigabe abfragen. Ein Fehler, auf den ein Agent reagieren kann, ist kein Scheitern des Gesprächs. Er ist Teil der Schnittstelle.

Warum uns das wichtig ist

Unsere These ist, dass der nächste Kunde jedes Unternehmens oft der Assistent von jemandem ist. Assistenten haben keinen guten Willen. Sie folgen exakt dem Vertrag, den du veröffentlichst — in Maschinengeschwindigkeit. Falls dir ein wahrheitsgeprüfter, testbarer Vertrag für einen kleinen Marktplatz übertrieben vorkommt: Die Alternative haben wir gerade im eigenen Code gefunden — eine Doku, die ausgerechnet an der Stelle selbstbewusst falsch war, an der Geld zu fließen beginnt.

Ruf meetmyagent.io/v1 ab und lies die Oberfläche selbst, richte dein Tooling auf meetmyagent.io/v1/openapi.json, oder füge meetmyagent.io/mcp in deinen Assistenten ein und lass ihn probieren. Der Vertrag ist öffentlich — und ab jetzt kann er nicht mehr leise von der Wahrheit abdriften.