MCP-Tools als API Contracts: Dokumentiere, was deine Agenten dürfen
Vor ein paar Monaten haben wir API Contracts veröffentlicht: OpenAPI-, gRPC-, GraphQL- und AsyncAPI-Spezifikationen, direkt mit den C4-Elementen verknüpft, die sie implementieren und konsumieren. Die Idee war einfach — die präzise, maschinenlesbare Beschreibung einer Schnittstelle gehört in deine Architektur, nicht auf eine Notion-Seite, die niemand aktualisiert.
Eine Schnittstelle hatten wir noch nicht abgedeckt. Die neueste. Die, die deine Services zunehmend nicht anderen Services, sondern KI-Agenten anbieten: MCP.
Ein MCP-Server veröffentlicht eine Reihe von Tools — jedes mit einem Namen, einer Beschreibung und einem JSON Schema für seine Eingaben. Das ist ein Vertrag. Es ist der Vertrag, der entscheidet, was ein Agent mit deinem System tun darf. Und bis heute war er in deiner Architekturdokumentation komplett unsichtbar.
Damit ist Schluss. MCP ist jetzt ein vollwertiger API-Contract-Typ in Archyl — der fünfte, neben HTTP, gRPC, GraphQL und AsyncAPI.
Das Schwierige: MCP-Tools liegen nicht in einer Datei
Die anderen vier Contract-Typen teilen eine Annahme — es gibt eine Spec-Datei in einem Repo. openapi.yaml. schema.graphql. Du verweist Archyl darauf und wir rendern sie.
MCP bricht damit. Die Tools eines MCP-Servers sind im Code definiert, und die vollständige, maßgebliche Liste existiert nur zur Laufzeit, wenn ein Client tools/list aufruft und das Schema für jedes Tool zurückbekommt. Es gibt keine universelle mcp.yaml, auf die man verweisen könnte.
Also haben wir zwei Wege gebaut.
Zwei Wege, einen MCP-Contract anzulegen
Füge ihn ein. Wenn du dein tools/list-Ergebnis bereits hast, füge es ein. Archyl validiert es und rendert jedes Tool — seine Beschreibung und seine Eingabeparameter als übersichtliche Tabelle.
Oder gib uns einfach die URL. Sag Archyl, wo dein MCP-Server liegt, füge optional ein Zugriffstoken hinzu (als Header oder Query-Parameter), und klick auf Tools entdecken. Archyl verbindet sich, führt den Handshake durch und zieht automatisch jedes Tool und jeden Parameter herein. Kein Kopieren, keine handgepflegte Datei.
Wie die Live-Erkennung funktioniert — und warum sie sicher ist
Die Erkennung passiert in deinem Browser, nicht auf unseren Servern. Wenn du auf Tools entdecken klickst, spricht dein Browser direkt mit deinem MCP-Server.
Diese Entscheidung ist wichtig:
- Dein Token verlässt nie deinen Browser. Archyl speichert die entdeckten Tools und die Verbindungsdaten — die URL, den Transport, wo das Token hingehört — aber niemals das Token selbst.
- Kein serverseitiger Zugriff auf dein Netzwerk. Da der Aufruf von deinem Rechner ausgeht, kann er nicht auf die internen Dienste anderer gerichtet werden. Die gesamte Klasse der Server-Side-Request-Forgery-Risiken existiert hier schlicht nicht.
- Er erreicht localhost und private Server. Du testest einen Server, der auf deinem Laptop oder in deinem Netzwerk läuft? Es funktioniert, weil dein Browser ihn sehen kann.
Der einzige Kompromiss ist CORS: ein Drittanbieter-Server muss Archyls Origin zulassen, damit dein Browser die Antwort lesen kann. Bei Servern, die du kontrollierst, ist das eine Zeile Konfiguration; für den Rest gibt es immer die Einfügen-Option.
Mit deiner Architektur verknüpft, wie jeder andere Contract
Einmal angelegt, verhält sich ein MCP-Contract wie jeder andere. Verknüpfe ihn mit dem Container oder der Komponente, die den Server hostet. Durchstöbere jedes Tool und sein Eingabeschema. Erkenne ihn neu, wenn sich der Server ändert. Er erscheint neben deinen REST- und GraphQL-Contracts, denn für die Agenten, die ihn aufrufen, ist er eine genauso reale API.
Das macht deinen MCP-Contract zu etwas wirklich Neuem: einer Karte dessen, was deine KI-Agenten mit einem bestimmten Teil deines Systems tun dürfen — dokumentiert, verknüpft und überprüfbar.
Wir setzen es bei uns selbst ein
Archyl ist selbst ein MCP-Server — 178 Tools, mit denen du deine Architektur aus Claude Code, Cursor oder jedem MCP-Client heraus steuern kannst. Der erste MCP-Contract, den wir angelegt haben, war unser eigener: Archyl auf seinen eigenen Endpunkt zeigen, alle 178 Tools entdecken, mit der Plattform verknüpfen. Unsere Agenten-Schnittstelle dokumentiert sich jetzt selbst.
Probier es aus
Öffne ein Projekt, geh zu API Contracts, lege einen neuen an und wähle MCP. Füge dein tools/list ein oder gib eine URL ein und klick auf Tools entdecken.
Deine Services sprechen bereits mit Agenten. Jetzt weiß deine Architektur, worüber.