DADL: describe REST APIs as MCP tools in YAML
30 lines of DADL replace a whole MCP server. DADL (Dunkel API Description Language) is a YAML format that describes REST APIs declaratively as MCP tools — no custom code, no runtime, no deployment, no maintenance.
Before: Claude → ToolMesh → MCP Server → REST APIWith DADL: Claude → ToolMesh → REST API (via .dadl file)Why DADL?
Section titled “Why DADL?”For every REST API, developers today build a dedicated MCP server — hundreds of Node.js/Python projects on GitHub that all repeat the same pattern: HTTP client + JSON schema + tool registration. A MCP server is structurally always a subset of the API it wraps.
DADL replaces this with a single YAML file.
LLM-Native Creation
Section titled “LLM-Native Creation”DADL files are not written by hand — they are generated by LLMs. A prompt like “Create a DADL for the Hetzner Cloud API — server list, create, delete, and power actions” is enough. This makes DADL the first API description format that is AI-native created and AI-native consumed.
Visit dadl.ai for the full specification, registry, and how-to guides.
Format Overview
Section titled “Format Overview”| Field | Required | Description |
|---|---|---|
spec | yes | URL of the DADL specification |
backend.name | yes | Unique backend identifier (slug) |
backend.type | yes | Always rest |
backend.base_url | yes | Base URL for API requests |
backend.auth | yes | Authentication configuration |
backend.tools | yes | Map of tool definitions |
backend.defaults | no | Default headers, pagination, errors, response |
backend.types | no | Type definitions (JSON Schema subset) |
backend.composites | no | Server-side multi-endpoint tools |
Authentication Types
Section titled “Authentication Types”| Type | Description |
|---|---|
bearer | Token in Authorization header |
basic | Base64-encoded username:password |
oauth2 | Client credentials flow with token caching |
session | Login → extract token → inject on requests → auto-refresh |
api_key | Key in header or query parameter |
Pagination Strategies
Section titled “Pagination Strategies”| Strategy | Description |
|---|---|
cursor | Cursor-based (Stripe, Slack) |
offset | Offset-based |
page | Page number-based |
link_header | RFC 8288 Link Header (GitHub) |
Pagination is auto by default — ToolMesh fetches all pages transparently. With expose, the LLM controls pagination via Code Mode.
Response Transformation
Section titled “Response Transformation”result_path— JSONPath to extract the relevant parttransform— jq filter for reduction/restructuringmax_items— array truncation against context overflowallow_jq_override— LLM can pass ad-hoc filters
Composite Tools
Section titled “Composite Tools”Server-side TypeScript for multi-endpoint orchestration:
- Access to
api.*(all tools of the backend) andparams(input) - Sandboxed: no
fetch(), norequire(), no filesystem access - Max 50
api.*calls per execution, 120s timeout - Each internal call is authorized and passes the pre-execution gate like a direct call
- Each internal call is individually recorded in the audit trail
Credentials and hosts
Section titled “Credentials and hosts”A DADL names the credentials it needs (credential: github_token), and ToolMesh takes them from the credential store as CREDENTIAL_GITHUB_TOKEN. Which credentials a backend may read, and where it may send them, is decided by its entry in backends.yaml, never by the DADL:
- A backend reads the credentials in the namespace of its entry (
CREDENTIAL_GITHUB_*for an entry namedgithub) and those the entry lists incredentials:or maps withenv:. Where namespaces overlap, the longest entry name wins. - It sends credentials, OAuth2 token requests and session logins only to the host and port of its
base_url, to other hosts of the same registrable domain on the default port, and to the hosts in the entry’sallowed_hosts:. Anhttpsbase_urlkeeps them on https. - A backend whose DADL reaches further is refused when it is loaded, and the log line
backend refusednames the line to add to its entry.
A DADL is still code you install: it decides which requests its backend sends with that backend’s credentials. Load DADLs only from sources you trust; the host binding is a second line of defense, not a guarantee against a malicious DADL.
The details are under Credential and host binding. When you write a DADL:
- Credential names consist of letters, digits and
_. Prefix them with the backend’s name (github_tokenforgithub), so they fall into the namespace of an entry named like the DADL. - A parameter default cannot name a credential:
default: "credential:<name>"is refused. - An absolute tool path (
https://uploads.example.com/...) cannot have a{placeholder}in its scheme, host or port.
A DADL that breaks one of these rules is refused when ToolMesh parses it.
Requests to REST backends
Section titled “Requests to REST backends”These rules apply to every REST backend, whatever its backends.yaml options:
- Redirects. A redirect to the same origin (scheme, host and port), or from
httptohttpson the same host, is followed unchanged. A redirect fromhttpstohttpis refused. A redirect to another origin keeps only content negotiation headers (Accept*,User-Agent,Range, conditional headers): credentials, other custom headers, theRefererand session cookies are dropped, and a307or308that would send the request body again is refused. Once a chain has left the origin, the rest of it counts as foreign, also a hop back to the original host. An API that needs credentials on another host names that host in its DADL. - Token and login requests (
oauth2,session) follow no redirects. They use the same connection rules as tool calls, soallow_private_urlandtls_skip_verifyapply to them as well. A session’slogin.pathstarts with/and stays on the host ofbase_url. - Path parameters. The values
.and..are refused, and a URL that would leave the scheme, host or path prefix ofbase_urlis refused before any request is sent. A/in a value is sent encoded (%2F) and stays one path segment. - Parameter types. Arguments are checked against their declared types before the Output Gate runs.
booleantakes onlytrueorfalse,integera whole number or a plain decimal string,numbera number or a plain decimal string,arrayandobjecttheir JSON forms. A number or boolean for astringparameter becomes its text, which the gate and the API both see, also in a JSON body ("42", not42); arrays, objects and other values without a text form are refused for it. File parameters are passed as given. A mismatch is answered withinvalid_inputand reaches neither the gate nor the API. Accepted numeric strings are sent as numbers ("007"becomes7; an integer beyond 2^53 stays a string to keep it exact), and declared defaults are filled in before the gate. - Error texts. A transport error names only scheme and host of the request, never its path or query. URLs in the text of an error result lose userinfo, query and fragment, and the audit log keeps the same reduced form.
- Private addresses.
allow_private_urlin thebackends.yamlentry (defaulttrue) lets a backend reach private addresses, but only at the destinations the configuration names: the host and port ofbase_url, oftoken_urland of absolute tool paths. Any other destination, such as the target of a redirect, must resolve to a public address. Withallow_private_url: false, a backend cannot reach loopback, private, link-local, carrier-grade NAT (100.64.0.0/10, which includes Tailscale addresses), benchmarking, documentation, multicast or reserved addresses, nor NAT64, 6to4 or IPv4-compatible IPv6 addresses that embed one of them, nor site-local IPv6 addresses; abase_urlon the unspecified address (0.0.0.0,[::]) is refused too. IPv6 addresses with a zone suffix (fe80::1%eth0) never pass these checks.
MCP backends follow a rule of their own: they stay on the origin of their configured URL (see MCP backends over HTTP).
Example
Section titled “Example”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]Learn More
Section titled “Learn More”- DADL Specification — full spec document
- DADL Registry — browse available API definitions
- How to Write a DADL — step-by-step guide