$cat mcp/README.md

> MCP server.

A Model Context Protocol server for MDflow. It lets MCP-capable agents pull markdown documents from your workspace, use folder descriptions as context, manage folders and documents you own, and control public and private sharing. Two ways to connect: the hosted remote server at https://mdflow.cz/api/mcp, or a local server that runs on your machine over stdio. Both expose the same tools and authenticate with a Personal Access Token.

$ls tools/

What it exposes

Tool	What it does
mdflow_auth_help	Shows token setup instructions. Does not require a token.
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.
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_update_document_sharing	Turns public sharing and comments on or off.
mdflow_delete_document	Deletes one document.
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.
mdflow_get_context	Finds topic context by ranking folder descriptions first, then titles, then fetching the best-matching markdown bodies.

Parameters use camelCase, but snake_case aliases are also accepted — e.g. mdflow_get_document takes both documentId and document_id.

$curl https://mdflow.cz/api/mcp

Configure hosted remote server

The hosted MCP server runs at https://mdflow.cz/api/mcp over the MCP Streamable HTTP transport. It works with any MCP client that can send an Authorization header and is always up to date. Create a Personal Access Token first; it starts with mdf_.

Claude Codeone command, applies to the current project

$bash

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

Claude Desktop (via mcp-remote)Settings → Developer → Edit Config · requires Node.js

$json

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

Cursornative Streamable HTTP · ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project)

$json

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

OpenAI Responses APIPOST https://api.openai.com/v1/responses — 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."
}

Security: the token belongs in your client configuration, never in chat prompts or tool arguments. Requests without a valid token receive 401 with a WWW-Authenticate challenge. Tokens grant workspace-level access, including write, delete, and sharing operations, and require an MDflow Pro account.

For agents: the server is stateless — no session IDs, plain JSON responses, one POST per JSON-RPC message. Rate limit is 30 requests per minute per token; 429 responses carry Retry-After in seconds. The same API is also available as REST — see the API reference and OpenAPI spec.

$node --version

Local server — prerequisites

Prefer a process on your own machine? The local stdio server exposes the same tools and talks to the same API.

›Node.js 18+ — the server relies on the built-in fetch.
›A terminal with npm.
›An MDflow Personal Access Token (created in step 3).

$./install

Local server — install

Download the server

Grab the files into a fresh folder.

$bash

mkdir mdflow-mcp && cd mdflow-mcp
curl -O https://mdflow.cz/mcp/server.mjs
curl -O https://mdflow.cz/mcp/package.json
curl -O https://mdflow.cz/mcp/README.md

Install dependencies

$bash

npm install

Pulls in @modelcontextprotocol/sdk and zod.

Create a Personal Access Token

Security: never paste your token into a chat prompt or tool argument. It belongs only in your MCP client config (next step). The server deliberately refuses to accept the token as a tool parameter. Tokens grant workspace-level API access, including write and delete operations.

Wire it into your MCP client

Point your client at the absolute path of server.mjs. Run pwd inside the mdflow-mcp folder to get it, then replace /absolute/path/to/… below.

Claude Desktop~/Library/Application Support/Claude/claude_desktop_config.json (macOS) · %APPDATA%\\Claude\\claude_desktop_config.json (Windows)

$json

{
  "mcpServers": {
    "mdflow": {
      "command": "node",
      "args": ["/absolute/path/to/mdflow-mcp/server.mjs"],
      "env": {
        "MDFLOW_API_TOKEN": "mdf_your_token_here"
      }
    }
  }
}

Codex~/.codex/config.toml

$toml

[mcp_servers.mdflow]
command = "node"
args = ["/absolute/path/to/mdflow-mcp/server.mjs"]
env = { MDFLOW_API_TOKEN = "mdf_your_token_here" }

Cursor~/.cursor/mcp.json (global) or .cursor/mcp.json (per project)

$json

{
  "mcpServers": {
    "mdflow": {
      "command": "node",
      "args": ["/absolute/path/to/mdflow-mcp/server.mjs"],
      "env": { "MDFLOW_API_TOKEN": "mdf_your_token_here" }
    }
  }
}

Restart your client and try it

Restart the app so it picks up the config, then ask:

>Get information about onboarding from mdflow.

>Use mdflow to get context about my API documentation.

>Create a document called meeting-notes.md in my project folder.

>Update my project folder description in mdflow.

$env | grep MDFLOW

Local server — environment variables

Variable	Required	Default	Purpose
MDFLOW_API_TOKEN	Yes	—	Personal Access Token, usually starting with `mdf_`. `MDFLOW_PAT` is accepted as an alias.
MDFLOW_API_BASE_URL	No	https://mdflow.cz	Override to point at local dev, e.g. `http://localhost:3000`.

$man mdflow_get_context

How get_context ranks results

mdflow_get_context is the main agent-facing tool. Given a topic it:

1.Lists folders and documents.
2.Scores folder descriptions highest — they define the intended context for the files they contain.
3.Scores folder names and document titles.
4.Fetches only the selected document bodies.
5.Returns a readable markdown context block plus structured data.

Defaults to 5 documents, each truncated to 12,000 characters. Callers can request up to 10 documents or 50,000 characters per document.

$cat NOTES.md

Client compatibility notes

The remote server works with any client that can attach an Authorization header to a remote MCP connection — Claude Code, Cursor, VS Code, the OpenAI Responses API, and MCP SDK clients. Claude Desktop can reach it through the mcp-remotestdio bridge, which requires Node.js. The ChatGPT app's custom connectors only support OAuth for authenticated servers, so they cannot connect with a Personal Access Token yet; OAuth support is planned. The local server works with clients that can launch a process — Claude Desktop, Codex, Cursor, and similar.

./api — the HTTP API it's built on →