MCP Servers

MDflow exposes its workspace through the Model Context Protocol, so AI agents can read and write your documents as a native capability rather than by scraping an API.

There are two servers offering the same tools:

• A hosted remote server at https://mdflow.cz/api/mcp — nothing to install.
• A downloadable local server running over stdio on your own machine.

Both require Pro. Docs: mdflow.cz/docs/mcp

Which one?

	Remote	Local
Install	None	Download and run
Auth	OAuth in the browser, or a token	Token in your client config
Works with	Claude.ai, ChatGPT, Claude Desktop, Claude Code, Cursor, Codex	Any stdio MCP client
Best for	Almost everyone	Air-gapped setups, custom wiring, development

Use the remote server unless you have a specific reason not to. With Claude.ai and ChatGPT you paste the URL, click connect, and authorize — there is no token to copy or store.

MDflow is also published in the official MCP registry as cz.mdflow/mcp.

The tools

Retrieval

• mdflow_get_context — start here. Ask for context on a topic and receive the most relevant markdown bodies.

Workspaces

• mdflow_list_workspaces, mdflow_create_workspace, mdflow_rename_workspace, mdflow_update_workspace_description, mdflow_delete_workspace

Folders

• mdflow_list_folders, mdflow_get_folder, mdflow_create_folder, mdflow_rename_folder, mdflow_update_folder_description, mdflow_move_folder, mdflow_delete_folder

Documents

• mdflow_list_documents, mdflow_get_document, mdflow_create_document, mdflow_rename_document, mdflow_update_document_body, mdflow_move_document, mdflow_delete_document

Sharing

• mdflow_update_document_sharing, mdflow_add_document_share, mdflow_list_document_shares, mdflow_revoke_document_share, mdflow_revoke_all_document_shares

How retrieval works

mdflow_get_context ranks:

1. Folder descriptions — the primary signal,
2. then folder names,
3. then document titles.

Then it returns the best-matching markdown bodies, as both readable markdown and structured content. You can limit results by document count and maximum characters per document.

Pass a workspaceId when the topic clearly belongs to one workspace; omit it for broad or ambiguous topics and it ranks across the whole account.

This is why folder descriptions matter. A folder called Notes with no description is nearly invisible to an agent. The same folder described properly becomes findable. If retrieval is disappointing, the fix is almost always better descriptions — not a better prompt. See 02 Folders and Subfolders.

For precise navigation instead of ranked retrieval, use mdflow_list_folders → mdflow_list_documents → mdflow_get_document. IDs are UUIDs returned by the list tools.

Things agents should know

• Ownership is enforced server-side. Other users' workspaces are never visible, whatever an agent asks for.
• Duplicate names are auto-disambiguated. The response contains the final name — read it back.
• mdflow_update_document_body replaces the whole body. It does not append. Get, concatenate, then update.
• Deleting a folder deletes the documents inside it. Deleting a workspace deletes everything in it, and you cannot delete your last workspace.
• Creating a document requires an existing folder ID — list or create a folder first.
• mdflow_create_folder takes workspace_id, not workspaceId. Passing the wrong spelling does not error — it silently creates the folder in your oldest workspace. Always check the workspace_id in the response.
• mdflow_move_folder only reparents within a workspace. Cross-workspace moves are web-app-only.
• Bodies are capped at 500 KiB UTF-8.
• Rate limit: 60 requests per minute, returning 429 with Retry-After.
• 401 means the credential is invalid, expired or revoked. 403 means the owner is not on Pro.

What MCP cannot reach

• Version history — private to the owner. An agent can overwrite a document but can never read what was there before. That asymmetry is deliberate: history is your recourse when an agent gets it wrong.
• Encrypted documents — an agent fetches ciphertext and cannot read it.
• Collections, comments, search and export — web app features.

A note on trust

An MCP-connected agent can read and write everything in your account and change what is publicly shared. That is the point, and it is also the risk. A token or OAuth grant is not scoped to a workspace or a folder.

Two mitigations that actually work: encrypt what no agent should read, and rely on version history to recover from what an agent gets wrong.