---
title: "03 MCP Servers"
canonical_url: https://mdflow.cz/share/c/h0L7MvX5Cy5sST3qPnApqHOmrQ36JTVy169qJMtDMya9Kc30zm04cg9OuPSSPwvj/aad78a27-0654-4781-b4b7-6ced0b14dbfc
md_url: https://mdflow.cz/share/c/h0L7MvX5Cy5sST3qPnApqHOmrQ36JTVy169qJMtDMya9Kc30zm04cg9OuPSSPwvj/aad78a27-0654-4781-b4b7-6ced0b14dbfc.md
visibility: public
---

# 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](https://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](/doc/ee296c64-ecda-49e9-a03f-1834eb1746d1).

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.