appflowy

Working with AppFlowy

The appflowy MCP server exposes 22 tools over AppFlowy Cloud. Every call needs a workspace_id, and most need a page_id or database_id on top of that. You never know these IDs up front. Resolve them first.

Auth is automatic. Do not call get_auth_token unless a tool returns HTTP 401 twice in a row, or the user explicitly asks to mint a refresh token.

Always resolve IDs before acting

Work down this chain, and do not guess or reuse an ID from an earlier conversation:

1. get_workspace_list gives workspace UUIDs. If there is more than one and the user did not say which, ask.
2. get_workspace_folder(workspace_id, depth=3) gives the page tree. Match the user's page by name here.
3. get_databases(workspace_id) gives database IDs, which are distinct from page IDs.

get_workspace_folder defaults to depth=1, which shows only top-level items. Use depth=3 or higher when hunting for a nested page, or pass root_view_id to expand one branch instead of pulling the whole tree.

To create a page at the top level of a workspace, pass the workspace_id itself as parent_view_id.

Errors

Tools do not raise. They return {"error": "...", "details": ...}. Check for error in the result before you use it, and never treat a failed call as a success. Report the details payload to the user rather than paraphrasing it.

Writing documents

Three tools write document content. Picking the wrong one destroys the page's identity.

Goal	Tool	Effect
New page	create_document_from_markdown	Creates under parent_view_id.
Add to an existing page	append_markdown_to_page	Appends blocks. Keeps view_id and history.
Rewrite an existing page	replace_page_document	Recreates the page. New view_id, links break, history lost.

Default to append_markdown_to_page. replace_page_document cannot edit in place; AppFlowy Cloud has no such endpoint, so it creates a replacement page and trashes the original. Before calling it, tell the user the page will get a new ID and that any links to it will break. If they only want to add a section, append instead. If they want to edit one paragraph in the middle, say plainly that this server cannot do a surgical edit, and offer append or full replace.