# MDflow

> A clean, no-noise markdown editor in the browser. Organize notes in folders, edit in Monaco, and publish any document at an unguessable public URL or share it privately by email. MDflow exposes an HTTP API and a Model Context Protocol (MCP) server — hosted remote (Streamable HTTP) and local (stdio) — so AI agents can read, create, update, organize, and share markdown documents.

## MCP server (for AI agents)

- Remote endpoint: https://mdflow.cz/api/mcp (MCP Streamable HTTP transport, stateless, JSON responses)
- Auth: `Authorization: Bearer mdf_...` header (Personal Access Token, created at https://mdflow.cz/settings, requires Pro)
- Tools: list/create/delete folders, update folder descriptions, list/get/create/update/move/delete markdown documents, topic-based context retrieval (mdflow_get_context), public link sharing (mdflow_update_document_sharing), and private email sharing (mdflow_list_document_shares, mdflow_add_document_share, mdflow_revoke_document_share, mdflow_revoke_all_document_shares).
- Unauthenticated requests receive 401 with a WWW-Authenticate challenge and setup instructions in the JSON body.

## Pricing

- MDflow Pro is €4.99/month with a 7-day free trial. The free plan allows 5 documents and 5 images.
- Agent control — the REST API, the MCP server, and Personal Access Tokens — requires Pro.
- Full pricing: https://mdflow.cz/pricing.md

## Raw markdown

- Every shared document has a raw markdown twin: append `.md` to its share URL, e.g. https://mdflow.cz/share/<slug>.md and https://mdflow.cz/share/c/<slug>/<documentId>.md. Served as text/markdown with YAML frontmatter (title, canonical_url, md_url, visibility) and open CORS for public documents.

## Docs

- [MCP server](https://mdflow.cz/docs/mcp): Connect to the hosted remote MCP server or install the local stdio server. Lets MCP-capable agents (Claude Code, Claude Desktop, Codex, Cursor, OpenAI Responses API) fetch markdown documents, use folder context, manage documents, and control sharing in MDflow.
- [Public API](https://mdflow.cz/docs/api): HTTP API for folders, markdown documents, public sharing, and private email sharing, authenticated with a Personal Access Token. Human-readable reference for all endpoints.
- [OpenAPI specification](https://mdflow.cz/openapi.json): Machine-readable OpenAPI 3.1 description of the public API.
- [Agent control guide](https://mdflow.cz/docs.md): One self-contained markdown page describing how an AI agent controls MDflow — auth, all MCP tools, REST endpoints, and client connect configs.
- [Agent card](https://mdflow.cz/.well-known/agent-card.json): Machine-readable discovery card (skills, interfaces, auth) at the standard well-known location.

## Comparisons

- [MDflow alternatives & comparisons](https://mdflow.cz/compare): Honest, side-by-side comparisons of MDflow with the note apps people switch from.
- [The OneNote alternative](https://mdflow.cz/compare/onenote-alternative): MDflow vs OneNote — real Markdown rendering, plain .md files you own, reliable search, sharing with comments, and API + MCP for AI agents.
- [The Evernote alternative](https://mdflow.cz/compare/evernote-alternative): MDflow vs Evernote — open .md files, no artificial note limits, free offline editing, and API + MCP, from €4.99/month.
- [The Obsidian alternative](https://mdflow.cz/compare/obsidian-alternative): MDflow vs Obsidian — markdown with zero setup, free cloud sync, clean reader sharing with comments, and a built-in MCP server (no plugin tax).

## API summary

- Base URL: https://mdflow.cz
- Auth: `Authorization: Bearer mdf_...` (Personal Access Token, created at https://mdflow.cz/settings)
- Rate limit: 30 requests per minute per token and per authenticated user
- `GET /api/v1/folders`: List folders.
- `GET /api/v1/folders/{id}/documents`: List documents in a folder.
- `GET /api/v1/documents`: List all documents (metadata only, no body).
- `GET /api/v1/documents/{id}`: Get one document, including its markdown body.
- `POST /api/v1/documents`: Create a markdown document in an owned folder.
- `PUT /api/v1/documents/{id}/sharing`: Turn public link sharing and comments on or off.
- `GET|POST /api/v1/documents/{id}/shares`: List or add private email shares.
- `DELETE /api/v1/documents/{id}/shares[/{shareId}]`: Revoke all or one private share.

## App

- [MDflow](https://mdflow.cz): The MDflow web app.