# Controlling MDflow with AI agents

MDflow (https://mdflow.cz) is a markdown workspace: folders hold markdown
documents, and each folder has a description that defines the intended context
for the documents inside it. This page is the self-contained guide for AI agents
that read, create, update, organize, and share documents in a workspace.

There are two equivalent ways to control MDflow, both authenticated with a
Personal Access Token: the **MCP server** (preferred for agents) and the **REST
API**. Everything an MCP tool can do, a REST endpoint can do too.

## Quick start

1. The workspace owner creates a Personal Access Token at
   https://mdflow.cz/settings (starts with `mdf_`). Requires MDflow Pro — see
   https://mdflow.cz/pricing.md.
2. Connect an MCP client to `https://mdflow.cz/api/mcp` with the token, or call
   the REST API at `https://mdflow.cz/api/v1`.
3. Call a tool — e.g. `mdflow_get_context` to retrieve relevant markdown, or
   `mdflow_create_document` to write one.

## Authentication

- Send `Authorization: Bearer mdf_your_token_here` on every request.
- Tokens grant workspace-level access (read, write, delete, sharing) and require
  MDflow Pro. Free workspaces receive a `Pro plan required` error.
- Keep the token in client configuration, never in chat prompts or tool
  arguments — the server refuses a token passed as a tool parameter.
- Rate limit: 30 requests per minute, per token and per user. `429` responses
  carry `Retry-After` (seconds).
- Unauthenticated requests receive `401` with a `WWW-Authenticate` challenge and
  setup instructions in the JSON body.

## Control surface 1 — MCP server

The hosted remote server runs at `https://mdflow.cz/api/mcp` over the MCP
Streamable HTTP transport (stateless, plain JSON responses, one POST per
JSON-RPC message). It works with any client that can attach an `Authorization`
header.

**Claude Code**

```bash
claude mcp add --transport http mdflow https://mdflow.cz/api/mcp \
  --header "Authorization: Bearer mdf_your_token_here"
```

**Claude Desktop** (via the `mcp-remote` bridge; requires Node.js)

```json
{
  "mcpServers": {
    "mdflow": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mdflow.cz/api/mcp",
        "--header",
        "Authorization:Bearer mdf_your_token_here"
      ]
    }
  }
}
```

**Cursor** (`~/.cursor/mcp.json` or `.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "mdflow": {
      "url": "https://mdflow.cz/api/mcp",
      "headers": { "Authorization": "Bearer mdf_your_token_here" }
    }
  }
}
```

**OpenAI Responses API** (remote MCP tool)

```json
{
  "model": "gpt-5.2",
  "tools": [
    {
      "type": "mcp",
      "server_label": "mdflow",
      "server_url": "https://mdflow.cz/api/mcp",
      "headers": { "Authorization": "Bearer mdf_your_token_here" }
    }
  ],
  "input": "Get information about onboarding from mdflow."
}
```

There is also a local stdio server (same tools) for clients that launch a
process. Full install steps: https://mdflow.cz/docs/mcp.

### MCP tools

Parameters use camelCase, with snake_case aliases also accepted (e.g.
`mdflow_get_document` takes both `documentId` and `document_id`).

Folders:

- `mdflow_list_folders` — Lists folders with their descriptions — the primary context signal for the documents inside.
- `mdflow_create_folder` — Creates a folder with an optional description.
- `mdflow_update_folder_description` — Replaces a folder description.
- `mdflow_delete_folder` — Deletes a folder and the documents inside it.

Documents:

- `mdflow_list_documents` — Lists document metadata, optionally scoped to one folder.
- `mdflow_get_document` — Fetches one document by ID, including its body.
- `mdflow_create_document` — Creates a document inside an existing folder.
- `mdflow_update_document_body` — Replaces a document's markdown body.
- `mdflow_move_document` — Moves a document to another folder.
- `mdflow_delete_document` — Deletes one document.

Context retrieval:

- `mdflow_get_context` — Finds topic context by ranking folder descriptions first, then titles, then fetching the best-matching markdown bodies. Defaults to 5 documents truncated to 12,000 characters each; callers can request up to 10 documents or 50,000 characters per document.

Sharing:

- `mdflow_update_document_sharing` — Turns public sharing and comments on or off.
- `mdflow_list_document_shares` — Lists the people a document is privately shared with, including share IDs and pending/accepted status.
- `mdflow_add_document_share` — Privately shares a document with a person by email, optionally allowing comments, and returns a private link to give them. No notification email is sent.
- `mdflow_revoke_document_share` — Revokes one person's private access to a document.
- `mdflow_revoke_all_document_shares` — Revokes private access to a document for everyone it is shared with.

Local stdio server only:

- `mdflow_auth_help` — Shows token setup instructions (does not require a token). Exposed by the local stdio server only; the hosted remote server at `https://mdflow.cz/api/mcp` exposes the other 16 tools.

## Control surface 2 — REST API

Base URL `https://mdflow.cz`. Same auth, same rate limit. Machine-readable
schema: https://mdflow.cz/openapi.json.

| Method | Path | Purpose |
| --- | --- | --- |
| 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. |

## Concepts

- **Folder descriptions are the main retrieval signal.** `mdflow_get_context`
  ranks them above folder names and document titles. Keep them accurate.
- **Documents are plain markdown**, at most 500 KiB UTF-8. Creating one requires
  an existing folder ID — list or create a folder first.
- **Duplicate names** (folders, or document titles within a folder) are
  disambiguated automatically with a numeric suffix; the response carries the
  final name.
- **Sharing has two independent mechanisms.** Public link sharing produces an
  unguessable URL (anyone with the link); private sharing grants read/comment
  access to specific email addresses without making the document public.

## Raw markdown URLs

Every shared document has a raw markdown twin — append `.md` to its share URL:

- `https://mdflow.cz/share/<slug>.md`
- `https://mdflow.cz/share/c/<slug>/<documentId>.md` (collections)

These return `text/markdown` with a YAML frontmatter header (`title`,
`canonical_url`, `md_url`, `visibility`) and open CORS for public documents, so
an agent can fetch and cite a document in one request.

## Worked example

1. `mdflow_list_folders` → pick a folder ID (or `mdflow_create_folder`).
2. `mdflow_create_document` with that `folderId`, a `title`, and a markdown
   `body`.
3. `mdflow_update_document_sharing` to enable a public link.
4. Hand the human the `https://mdflow.cz/share/<slug>` page, or its `.md` twin
   for another agent.

## More

- Pricing & Pro: https://mdflow.cz/pricing.md
- OpenAPI spec: https://mdflow.cz/openapi.json
- Discovery card: https://mdflow.cz/.well-known/agent-card.json
- Human MCP docs: https://mdflow.cz/docs/mcp
- Human API docs: https://mdflow.cz/docs/api