MDAN

One page for humans and agents.

MDAN (Markdown Action Notation) is a shared notation for interactive pages that stay readable and actionable for both humans and agents, from the same source, across any interface.

Same page. Same actions. Same experience.

That means one app can serve browsers and agents without splitting the interaction model across Markdown, prompts, JSON APIs, and UI glue.

What MDAN Is

MDAN treats the page itself as the unit of application behavior.

In one page source, you can keep:

page content is written in Markdown
executable operations are also defined in the page
Markdown fragments returned by the server are not just results, but the next interaction context
the same web app can be visited in a browser and used directly by an agent over HTTP

That makes MDAN a good fit for agent apps, skills apps, internal tools, and page-shaped applications with ongoing multi-step interaction.

@mdanai/sdk is the current TypeScript reference implementation for this format and its host behavior.

What Problem It Solves

When the same app needs to serve both agents and people, the architecture often drifts apart fast:

agents talk to one tool or JSON interface
browsers talk to a different page and interaction model
the server has to keep prompts, state, and follow-up actions in sync across both

MDAN brings that back into one readable application surface. As a result:

agents can read Markdown directly and keep going from there
agents can talk to the same web app over HTTP using tools like curl
agents do not need a headless browser to imitate human page interaction
browsers can keep using HTML without a second application model
the server can keep driving follow-up interaction by returning Markdown fragments
the app is less likely to drift across pages, protocols, tools, and UI

When To Use MDAN

MDAN is a strong fit when:

the same app needs to work for both humans and AI agents
your interaction model is naturally page-shaped and multi-step
you want content and actions to stay readable together
you want one server app to negotiate Markdown for agents and HTML for browsers

When Not To Use MDAN

MDAN is probably not the right fit when:

you only need a conventional browser-only app
your application is mostly a JSON API with no page-shaped interaction
your UI depends heavily on a large client-side SPA state model
you do not care about agent-readable interaction at all

How It Works

At a high level, MDAN works in three steps:

The page source uses Markdown to describe content and operations.
After an interaction happens, the server returns an updated Markdown fragment.
The agent or browser continues from that result.

For agents, the response is usually Markdown.
For browsers, the response is usually HTML.

That is:

Accept: text/markdown -> returns Markdown
Accept: text/html -> returns HTML

What changes is the returned form, not the underlying app.

Docs Guide

Start

Want to get something running in five minutes: Getting Started
Want a crisp definition and best-fit use cases: What is MDAN?
Want to compare MDAN with MCP: MDAN vs MCP

Core Concepts

Want to understand pages, blocks, and updates: Understanding MDAN
Want to understand how one app serves both humans and agents: HTTP Content Negotiation
Want to see how an agent consumes MDAN directly: Direct Agent Consumption
Want to see a real multi-step agent app flow: Agent App Demo

Build With MDAN

Want to choose the right integration path first: Developer Paths
Want to start building a real app: Application Structure
Want to plug MDAN into an existing backend: Server Integration
Want runnable repository demos: Examples

Spec

Want the public versioned spec entry: Spec v1
Want the full spec body in the repository: spec/spec.md

SDK Reference

Want to understand SDK boundaries: SDK Overview
Want to understand server-side hosting: Server Runtime
Want to understand browser-side continuation: Web Runtime
Want the public API surface: API Reference