DADL

DADL (Dunkel API Description Language) is a YAML format that describes REST APIs declaratively as MCP tools. It eliminates the need to build dedicated MCP servers for each API.

Before:   Claude → ToolMesh → MCP Server → REST API
With DADL: Claude → ToolMesh → REST API (via .dadl file)

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

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

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

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

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

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

Composite Tools

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 individually recorded in the audit trail

Example

spec: "https://dadl.ai/spec/dadl-spec-v0.1.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

DADL Specification — full spec document
DADL Registry — browse available API definitions
How to Write a DADL — step-by-step guide