tokyntraildocs

MCP-Server hosten: aus einer API-Spec

Sie haben eine REST-API, aber keinen MCP-Server? Dann brauchen Sie keinen zu bauen. tokyn.trail erzeugt einen aus Ihrer OpenAPI-Spec und betreibt ihn - mit denselben Regeln, derselben Inbox und derselben Evidenz wie ein Server, den Sie nur davorhängen. Der Unterschied ist allein die Herkunft der Tools; alles dahinter ist identisch.

Der Vorteil liegt weniger im Sparen von Arbeit als in der Reihenfolge: Die Freigaberegeln stehen ab dem ersten Aufruf, statt später an einen bereits laufenden Agenten geschraubt zu werden.

Anlegen#

Unter MCP-Server → MCP-Server aus API-Spec erzeugen geben Sie Ihr OpenAPI-Dokument als JSON oder YAML an - als Datei, über die URL, unter der es veröffentlicht ist, oder eingefügt. Aus jedem Endpunkt wird ein Tool.

  • Name - wie der Server in Inbox, Reports und Audit-Log heißt.
  • OpenAPI-Dokument (JSON oder YAML) - als Datei, als URL oder eingefügt. Eine URL holen wir einmal, beim Anlegen; danach ist der Katalog gespeichert, nicht der Verweis. Ziele in privaten Netzen lehnen wir ab, damit niemand unseren Server ins eigene Netz schicken kann.
  • API-Basis-URL - optional. Fehlt sie, wird der erste servers-Eintrag der Spec verwendet; ist der relativ (/api/v3), lösen wir ihn gegen die Adresse auf, von der die Spec kam.
  • Auth-Header - optional, AES-256-GCM-verschlüsselt gespeichert, nie geloggt. Er wird bei jedem Aufruf an Ihre API mitgeschickt.

Danach erhalten Sie dieselbe MCP-Server-URL wie bei jedem anderen Server und zeigen Ihren Client darauf - siehe Client-Setup.

Was aus der Spec wird#

Pro Operation ein Tool. Die Abbildung im Einzelnen:

  • Tool-Name: die operationId in snake_case. Fehlt sie, wird der Name aus Methode und Pfad gebildet - GET /pets/{petId} wird zu get_pets_by_pet_id. Doppelte Namen bekommen ein Suffix.
  • Beschreibung: summary, ersatzweise description.
  • Argumente: Pfad-, Query- und Header-Parameter sowie die Felder des application/json-Request-Bodys - flach in ein Schema gemischt. Pfadparameter sind immer Pflicht.
  • Hinweise: GET wird als readOnlyHint markiert, DELETE zusätzlich als destructiveHint. Darauf greift später der Lesen/Schreiben-Schalter zu.

$ref wird aufgelöst, auch verschachtelt und aus components/parameters. Rekursive Modelle enden in einem offenen Schema statt in einer Endlosschleife - ein selbstbezüglicher Typ kostet Ausdruckskraft, nicht den Import.

Schreibende Tools kommen ausgeschaltet an#

Nach dem Import ist jedes lesende Tool aktiv und jedes schreibende aus. Eine frisch importierte Spec, bei der DELETE /customers/{id} sofort scharf wäre, widerspricht dem Zweck des Produkts. Sie schalten frei, was Sie freischalten wollen - einzeln oder gesammelt.

Unabhängig davon gilt weiter der Rug-Pull-Schutz: Jedes neue Tool steht auf new und wird bei jedem Aufruf zur Freigabe gehalten, bis Sie es per Regel einordnen. Einschalten heißt „darf angeboten werden", nicht „darf ohne Freigabe laufen".

Ausgeschaltet ist nicht dasselbe wie verboten#

Der Unterschied ist wichtiger, als er klingt:

  • Ausgeschaltet - das Tool erscheint dem Agenten gar nicht erst im Katalog. Er zieht es nicht in Betracht.
  • Deny-Regel - das Tool ist sichtbar, der Agent ruft es auf und scheitert. Das kann gewollt sein, kostet aber einen Fehlversuch und taucht im Verlauf auf.

Ein ausgeschaltetes Tool wird auch dann abgelehnt, wenn ein Client mit veraltetem Katalog es beim Namen ruft - die Prüfung sitzt am Aufruf, nicht nur an der Liste. Ihre API sieht davon nichts.

Lesen und Schreiben#

Der Schalter Nur lesen ↔ Schreiben erlauben auf der Serverseite ist eine Sammelaktion über genau diese Tool-Schalter: Er nimmt alle Tools ohne readOnlyHint aus dem Katalog oder stellt sie zurück. Es ist bewusst keine zweite Durchsetzungsmechanik neben den Regeln - sonst gäbe es zwei Systeme, die sich widersprechen können, und die Frage „unter welcher Policy lief das?" wäre nicht mehr sauber zu beantworten.

Eigene Tools#

Für den Endpunkt, den die Spec nicht kennt: Tool von Hand hinzufügen auf der Serverseite. Pfadparameter werden aus dem Template gelesen, statt sie zweimal zu tippen - /invoices/{id}/refund ergibt automatisch den Parameter id. Query-Parameter und Body-Felder geben Sie kommagetrennt an.

Von Hand angelegte Tools kommen eingeschaltet an - wer ein einzelnes Tool bewusst anlegt, ist nicht in derselben Lage wie jemand, der zweihundert Operationen auf einmal übernimmt. Sie überstehen jeden erneuten Import.

Tools bearbeiten und löschen#

Die Beschreibung ist der Text, an dem ein Agent entscheidet, wann er ein Tool benutzt - sie zu schärfen ist Ihr wirksamstes Mittel gegen Fehlgebrauch. Beim Speichern wechselt die Zuständigkeit: Das Tool gilt danach als manuell statt generiert, ein erneuter Spec-Import fasst es nicht mehr an. Umkehrbar durch Löschen und neu importieren.

Der Name bleibt unveränderlich - an ihm hängen Regeln und Belege; ein anderer Name wäre ein anderes Tool, kein geändertes. Eine geänderte Definition geht auf changed und will neu eingeordnet werden, genau wie eine Änderung aus der Spec. Löschen geht nur bei manuellen Tools: Ein generiertes käme beim nächsten Import zurück, dort ist Ausschalten das richtige Mittel.

Spec erneut importieren#

Ändert sich Ihre API, importieren Sie die neue Spec über denselben Server:

  • Geänderte Definitionen werden aktualisiert und gehen auf changed.
  • Ihre Schalter bleiben. Die Definition gehört der Spec, der Schalter Ihnen.
  • Operationen, die die Spec nicht mehr enthält, gehen auf removed und verlassen den Katalog. Die Zeile bleibt als Beleg erhalten.
  • Ein verschobener Endpunkt zählt als Änderung, auch wenn das Schema identisch bleibt: Derselbe Tool-Name tut dann etwas anderes, und das gehört neu eingeordnet.

Was nicht importiert wird#

Was der Import nicht übernehmen kann, wird im Klartext gemeldet - im Formular und dauerhaft auf der Serverseite. Ein Import, der stillschweigend die Hälfte weglässt, wäre schlimmer als einer, der scheitert.

Beispielmeldungen nach dem Import
GET /legacy/ping: skipped (marked deprecated).
POST /attachments: request body has no application/json variant (offers: multipart/form-data).
  • Swagger 2.0 - nicht unterstützt; auf OpenAPI 3 konvertieren.
  • Externe $ref auf andere Dokumente - nur lokale Referenzen werden aufgelöst.
  • Andere Body-Formate als application/json, etwa Datei-Uploads über multipart/form-data.
  • Als deprecated markierte Operationen - bewusst übersprungen.
  • cookie-Parameter.

Für alle diese Fälle bleibt der Weg über eigene Tools offen.

Wenn ein Aufruf scheitert#

Antwortet Ihre API mit einem Fehler, bekommt der Agent Statuscode und Antwortanfang als Tool-Fehler zurück - genug zum Diagnostizieren, ohne die Nutzlast ins Log zu kippen. Fehlt ein Pflicht-Pfadparameter, wird der Aufruf abgelehnt, bevor etwas Ihre API erreicht, statt auf eine kaputte URL zu laufen.

Ein solcher Fehler gilt als Fehlschlag, nicht als Vollzug: Die Aktion geht auf failed, und der Fehlertext Ihrer API steht als Grund im Beleg. Ein Nachweis, der eine Ausführung behauptet, die nie stattgefunden hat, wäre schlimmer als gar keiner - und der Fall trifft ausgerechnet den teuersten Pfad, weil vorher ein Mensch freigegeben hat.

Nur lesende Zugangsdaten hinterlegt? Dann schalten Sie die schreibenden Tools ab, statt sie über Regeln zu halten. Sonst bitten Sie Menschen um Freigaben für Aufrufe, die anschließend zuverlässig an 401/403 scheitern - der Schalter je Tool ist hier das richtige Mittel, nicht der Freigabeprozess.