# DADL: describe REST APIs as MCP tools in YAML

> DADL is a YAML format that turns any REST API into MCP tools — 30 LOC replace a whole MCP server. Documents the schema, auth types, defaults, composites.

Canonical: https://www.toolmesh.io/en/dadl/

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)
```

## 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](https://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

```yaml
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](https://dadl.ai/specs) — full spec document
- [DADL Registry](https://dadl.ai/browse) — browse available API definitions
- [How to Write a DADL](https://dadl.ai/howto/write-a-dadl) — step-by-step guide