DADL: REST-APIs als MCP-Tools in YAML beschreiben
30 Zeilen DADL ersetzen einen ganzen MCP-Server. DADL (Dunkel API Description Language) ist ein YAML-Format, das REST-APIs deklarativ als MCP-Tools beschreibt — kein Custom-Code, keine Runtime, kein Deployment, keine Wartung.
Vorher: Claude → ToolMesh → MCP Server → REST APIMit DADL: Claude → ToolMesh → REST API (via .dadl-Datei)Warum DADL?
Abschnitt betitelt „Warum DADL?“Für jede REST-API bauen Entwickler heute einen dedizierten MCP-Server — Hunderte von Node.js/Python-Projekten auf GitHub, die alle das gleiche Muster wiederholen: HTTP-Client + JSON-Schema + Tool-Registrierung. Ein MCP-Server ist strukturell immer eine Teilmenge der API, die er wrapt.
DADL ersetzt das durch eine einzige YAML-Datei.
LLM-native Erstellung
Abschnitt betitelt „LLM-native Erstellung“DADL-Dateien werden nicht von Hand geschrieben — sie werden von LLMs generiert. Ein Prompt wie „Erstelle eine DADL für die Hetzner Cloud API — Server auflisten, erstellen, löschen und Power-Aktionen” reicht aus. Damit ist DADL das erste API-Beschreibungsformat, das KI-nativ erstellt und KI-nativ konsumiert wird.
Die vollständige Spezifikation, die Registry und How-to-Guides finden Sie auf dadl.ai.
Format-Übersicht
Abschnitt betitelt „Format-Übersicht“| Feld | Pflicht | Beschreibung |
|---|---|---|
spec | ja | URL der DADL-Spezifikation |
backend.name | ja | Eindeutiger Backend-Bezeichner (Slug) |
backend.type | ja | Immer rest |
backend.base_url | ja | Basis-URL für API-Requests |
backend.auth | ja | Authentifizierungskonfiguration |
backend.tools | ja | Map der Tool-Definitionen |
backend.defaults | nein | Standard-Header, Pagination, Fehler, Response |
backend.types | nein | Typ-Definitionen (JSON-Schema-Subset) |
backend.composites | nein | Serverseitige Multi-Endpoint-Tools |
Authentifizierungstypen
Abschnitt betitelt „Authentifizierungstypen“| Typ | Beschreibung |
|---|---|
bearer | Token im Authorization-Header |
basic | Base64-kodierter Username:Passwort |
oauth2 | Client-Credentials-Flow mit Token-Caching |
session | Login → Token extrahieren → bei Requests injizieren → Auto-Refresh |
apikey | Key in Header oder Query-Parameter |
Pagination-Strategien
Abschnitt betitelt „Pagination-Strategien“| Strategie | Beschreibung |
|---|---|
cursor | Cursor-basiert (Stripe, Slack) |
offset | Offset-basiert |
page | Seitennummer-basiert |
link_header | RFC 8288 Link Header (GitHub) |
Pagination ist standardmäßig auto — ToolMesh ruft alle Seiten transparent ab. Mit expose steuert das LLM die Pagination über Code Mode.
Response-Transformation
Abschnitt betitelt „Response-Transformation“result_path— JSONPath zur Extraktion des relevanten Teilstransform— jq-Filter zur Reduktion/Restrukturierungmax_items— Array-Begrenzung gegen Context-Overflowallow_jq_override— LLM kann Ad-hoc-Filter übergeben
Composite Tools
Abschnitt betitelt „Composite Tools“Serverseitiges TypeScript für Multi-Endpoint-Orchestrierung:
- Zugriff auf
api.*(alle Tools des Backends) undparams(Input) - Sandboxed: kein
fetch(), keinrequire(), kein Dateisystem-Zugriff - Maximal 50
api.*-Aufrufe pro Ausführung, 120s Timeout - Jeder interne Aufruf wird autorisiert und durchläuft das Pre-Execution-Gate wie ein direkter Aufruf
- Jeder interne Aufruf wird einzeln im Audit-Trail erfasst
Credentials und Hosts
Abschnitt betitelt „Credentials und Hosts“Eine DADL nennt die Credentials, die sie braucht (credential: github_token), und ToolMesh nimmt sie als CREDENTIAL_GITHUB_TOKEN aus dem Credential-Store. Welche Credentials ein Backend lesen darf und wohin es sie schicken darf, entscheidet sein Eintrag in backends.yaml, nie die DADL:
- Ein Backend liest die Credentials im Namensraum seines Eintrags (
CREDENTIAL_GITHUB_*für einen Eintrag namensgithub) und die, die der Eintrag untercredentials:aufführt oder perenv:abbildet. Überschneiden sich Namensräume, gewinnt der längste Eintragsname. - Es schickt Credentials, OAuth2-Token-Anfragen und Session-Logins nur an Host und Port seiner
base_url, an andere Hosts derselben registrierbaren Domain auf dem Standardport und an die Hosts inallowed_hosts:seines Eintrags. Einehttps-base_urlhält sie auf https. - Ein Backend, dessen DADL weiter reicht, wird beim Laden abgewiesen, und die Logzeile
backend refusednennt die Zeile, die in seinen Eintrag gehört.
Eine DADL bleibt dennoch Code, den Sie installieren: Die DADL bestimmt, welche Anfragen ihr Backend mit dessen Credentials sendet. DADLs sollten deshalb nur aus vertrauenswürdigen Quellen kommen; die Host-Bindung ist eine zweite Verteidigungslinie, keine Garantie gegen eine bösartige DADL.
Die Einzelheiten stehen unter Bindung an Credentials und Hosts. Für das Schreiben einer DADL gilt:
- Credential-Namen bestehen aus Buchstaben, Ziffern und
_. Mit dem Namen des Backends als Präfix (github_tokenfürgithub) fallen sie in den Namensraum eines Eintrags, der wie die DADL heißt. - Ein Parameter-Default kann kein Credential nennen:
default: "credential:<name>"wird abgewiesen. - Ein absoluter Tool-Pfad (
https://uploads.example.com/...) darf in Schema, Host und Port keinen{placeholder}enthalten.
ToolMesh weist eine DADL, die gegen eine dieser Regeln verstößt, schon beim Parsen ab.
Anfragen an REST-Backends
Abschnitt betitelt „Anfragen an REST-Backends“Diese Regeln gelten für jedes REST-Backend, gleich mit welchen Optionen in backends.yaml:
- Weiterleitungen. Eine Weiterleitung zum selben Origin (Schema, Host und Port) oder von
httpzuhttpsauf demselben Host wird unverändert verfolgt. Eine Weiterleitung vonhttpszuhttpwird abgewiesen. Eine Weiterleitung zu einem anderen Origin behält nur Header der Content Negotiation (Accept*,User-Agent,Range, bedingte Header): Credentials, andere eigene Header, derRefererund Session-Cookies entfallen, und ein307oder308, das den Request-Body erneut senden würde, wird abgewiesen. Hat eine Kette den Origin einmal verlassen, gilt der Rest als fremd, auch ein Schritt zurück zum ursprünglichen Host. Eine API, die Credentials auf einem anderen Host braucht, nennt diesen Host in ihrer DADL. - Token- und Login-Anfragen (
oauth2,session) folgen keinen Weiterleitungen. Für sie gelten dieselben Verbindungsregeln wie für Tool-Calls, also auchallow_private_urlundtls_skip_verify. Derlogin.patheiner Session beginnt mit/und bleibt auf dem Host derbase_url. - Pfadparameter. Die Werte
.und..werden abgewiesen, und eine URL, die Schema, Host oder Pfadpräfix derbase_urlverlassen würde, wird abgewiesen, bevor eine Anfrage hinausgeht. Ein/in einem Wert wird kodiert gesendet (%2F) und bleibt ein Pfadsegment. - Parametertypen. Argumente werden gegen ihre deklarierten Typen geprüft, bevor das Output Gate läuft.
booleannimmt nurtrueoderfalse,integereine ganze Zahl oder einen schlichten Dezimalstring,numbereine Zahl oder einen schlichten Dezimalstring,arrayundobjectihre JSON-Formen. Eine Zahl oder ein Boolean für einen Parameter vom Typstringwird zu ihrem Text, den Gate und API gleichermaßen sehen, auch im JSON-Body ("42"statt42); Arrays, Objekte und andere Werte ohne Textform werden dafür abgewiesen. Datei-Parameter gehen unverändert durch. Passt ein Wert nicht, lautet die Antwortinvalid_input, und er erreicht weder das Gate noch die API. Angenommene numerische Strings werden als Zahlen gesendet (aus"007"wird7; eine ganze Zahl über 2^53 bleibt ein String, damit sie exakt bleibt), und deklarierte Defaults werden vor dem Gate eingesetzt. - Fehlertexte. Ein Transportfehler nennt nur Schema und Host der Anfrage, nie Pfad oder Query. URLs im Text eines Fehlerergebnisses verlieren Userinfo, Query und Fragment, und das Audit-Log hält dieselbe gekürzte Form fest.
- Private Adressen.
allow_private_urlim Eintrag inbackends.yaml(Standardtrue) erlaubt einem Backend private Adressen, aber nur an den Zielen, die die Konfiguration nennt: Host und Port derbase_url, dertoken_urlund absoluter Tool-Pfade. Jedes andere Ziel, etwa das einer Weiterleitung, muss zu einer öffentlichen Adresse auflösen. Mitallow_private_url: falseerreicht ein Backend weder Loopback-, private, Link-Local-, Carrier-Grade-NAT- (100.64.0.0/10, darunter Tailscale-Adressen), Benchmarking-, Dokumentations-, Multicast- oder reservierte Adressen noch NAT64-, 6to4- oder IPv4-kompatible IPv6-Adressen, die eine davon einbetten, noch Site-Local-IPv6-Adressen; einebase_urlauf der unspezifizierten Adresse (0.0.0.0,[::]) wird ebenfalls abgewiesen. IPv6-Adressen mit Zonen-Suffix (fe80::1%eth0) bestehen diese Prüfungen nie.
MCP-Backends folgen einer eigenen Regel: Sie bleiben beim Origin ihrer konfigurierten URL (siehe MCP-Backends per HTTP).
Beispiel
Abschnitt betitelt „Beispiel“spec: "https://dadl.ai/spec/dadl-spec-v0.2.md"backend: name: github type: rest base_url: https://api.github.com auth: type: bearer credential: github_token defaults: headers: Accept: application/vnd.github+json pagination: strategy: link_header mode: auto tools: list_repos: method: GET path: /user/repos description: "List repositories for the authenticated user" params: sort: type: string enum: [created, updated, pushed, full_name]Mehr erfahren
Abschnitt betitelt „Mehr erfahren“- DADL-Spezifikation — vollständiges Spezifikationsdokument
- DADL Registry — verfügbare API-Definitionen durchsuchen
- How to Write a DADL — Schritt-für-Schritt-Anleitung