Skip to content

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

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.

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.

FieldRequiredDescription
specyesURL of the DADL specification
backend.nameyesUnique backend identifier (slug)
backend.typeyesAlways rest
backend.base_urlyesBase URL for API requests
backend.authyesAuthentication configuration
backend.toolsyesMap of tool definitions
backend.defaultsnoDefault headers, pagination, errors, response
backend.typesnoType definitions (JSON Schema subset)
backend.compositesnoServer-side multi-endpoint tools
TypeDescription
bearerToken in Authorization header
basicBase64-encoded username:password
oauth2Client credentials flow with token caching
sessionLogin → extract token → inject on requests → auto-refresh
api_keyKey in header or query parameter
StrategyDescription
cursorCursor-based (Stripe, Slack)
offsetOffset-based
pagePage number-based
link_headerRFC 8288 Link Header (GitHub)

Pagination is auto by default — ToolMesh fetches all pages transparently. With expose, the LLM controls pagination via Code Mode.

  • result_path — JSONPath to extract the relevant part
  • transform — jq filter for reduction/restructuring
  • max_items — array truncation against context overflow
  • allow_jq_override — LLM can pass ad-hoc filters

Server-side TypeScript for multi-endpoint orchestration:

  • Access to api.* (all tools of the backend) and params (input)
  • Sandboxed: no fetch(), no require(), 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

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 named github) and those the entry lists in credentials: or maps with env:. 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’s allowed_hosts:. An https base_url keeps them on https.
  • A backend whose DADL reaches further is refused when it is loaded, and the log line backend refused names 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_token for github), 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.

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 http to https on the same host, is followed unchanged. A redirect from https to http is refused. A redirect to another origin keeps only content negotiation headers (Accept*, User-Agent, Range, conditional headers): credentials, other custom headers, the Referer and session cookies are dropped, and a 307 or 308 that 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, so allow_private_url and tls_skip_verify apply to them as well. A session’s login.path starts with / and stays on the host of base_url.
  • Path parameters. The values . and .. are refused, and a URL that would leave the scheme, host or path prefix of base_url is 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. boolean takes only true or false, integer a whole number or a plain decimal string, number a number or a plain decimal string, array and object their JSON forms. A number or boolean for a string parameter becomes its text, which the gate and the API both see, also in a JSON body ("42", not 42); arrays, objects and other values without a text form are refused for it. File parameters are passed as given. A mismatch is answered with invalid_input and reaches neither the gate nor the API. Accepted numeric strings are sent as numbers ("007" becomes 7; 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_url in the backends.yaml entry (default true) lets a backend reach private addresses, but only at the destinations the configuration names: the host and port of base_url, of token_url and of absolute tool paths. Any other destination, such as the target of a redirect, must resolve to a public address. With allow_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; a base_url on 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).

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]