Zum Inhalt springen

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 API
Mit DADL: Claude → ToolMesh → REST API (via .dadl-Datei)

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.

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.

FeldPflichtBeschreibung
specjaURL der DADL-Spezifikation
backend.namejaEindeutiger Backend-Bezeichner (Slug)
backend.typejaImmer rest
backend.base_urljaBasis-URL für API-Requests
backend.authjaAuthentifizierungskonfiguration
backend.toolsjaMap der Tool-Definitionen
backend.defaultsneinStandard-Header, Pagination, Fehler, Response
backend.typesneinTyp-Definitionen (JSON-Schema-Subset)
backend.compositesneinServerseitige Multi-Endpoint-Tools
TypBeschreibung
bearerToken im Authorization-Header
basicBase64-kodierter Username:Passwort
oauth2Client-Credentials-Flow mit Token-Caching
sessionLogin → Token extrahieren → bei Requests injizieren → Auto-Refresh
apikeyKey in Header oder Query-Parameter
StrategieBeschreibung
cursorCursor-basiert (Stripe, Slack)
offsetOffset-basiert
pageSeitennummer-basiert
link_headerRFC 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.

  • result_path — JSONPath zur Extraktion des relevanten Teils
  • transform — jq-Filter zur Reduktion/Restrukturierung
  • max_items — Array-Begrenzung gegen Context-Overflow
  • allow_jq_override — LLM kann Ad-hoc-Filter übergeben

Serverseitiges TypeScript für Multi-Endpoint-Orchestrierung:

  • Zugriff auf api.* (alle Tools des Backends) und params (Input)
  • Sandboxed: kein fetch(), kein require(), 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

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 namens github) und die, die der Eintrag unter credentials: aufführt oder per env: 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 in allowed_hosts: seines Eintrags. Eine https-base_url hält sie auf https.
  • Ein Backend, dessen DADL weiter reicht, wird beim Laden abgewiesen, und die Logzeile backend refused nennt 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_token für github) 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.

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 http zu https auf demselben Host wird unverändert verfolgt. Eine Weiterleitung von https zu http wird abgewiesen. Eine Weiterleitung zu einem anderen Origin behält nur Header der Content Negotiation (Accept*, User-Agent, Range, bedingte Header): Credentials, andere eigene Header, der Referer und Session-Cookies entfallen, und ein 307 oder 308, 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 auch allow_private_url und tls_skip_verify. Der login.path einer Session beginnt mit / und bleibt auf dem Host der base_url.
  • Pfadparameter. Die Werte . und .. werden abgewiesen, und eine URL, die Schema, Host oder Pfadpräfix der base_url verlassen 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. boolean nimmt nur true oder false, integer eine ganze Zahl oder einen schlichten Dezimalstring, number eine Zahl oder einen schlichten Dezimalstring, array und object ihre JSON-Formen. Eine Zahl oder ein Boolean für einen Parameter vom Typ string wird zu ihrem Text, den Gate und API gleichermaßen sehen, auch im JSON-Body ("42" statt 42); Arrays, Objekte und andere Werte ohne Textform werden dafür abgewiesen. Datei-Parameter gehen unverändert durch. Passt ein Wert nicht, lautet die Antwort invalid_input, und er erreicht weder das Gate noch die API. Angenommene numerische Strings werden als Zahlen gesendet (aus "007" wird 7; 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_url im Eintrag in backends.yaml (Standard true) erlaubt einem Backend private Adressen, aber nur an den Zielen, die die Konfiguration nennt: Host und Port der base_url, der token_url und absoluter Tool-Pfade. Jedes andere Ziel, etwa das einer Weiterleitung, muss zu einer öffentlichen Adresse auflösen. Mit allow_private_url: false erreicht 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; eine base_url auf 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).

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]