Skip to content
flowplanDocumentationCommunityMarketplaceStart page

API and integrations

MCP: AI assistants

Connect Claude, ChatGPT and other AI assistants to your Flowplan using the Model Context Protocol (MCP). They search, read and write with exactly your permissions, nothing more.

9 min read

On this page
  1. Set up
  2. Claude Code
  3. Claude Desktop
  4. ChatGPT
  5. Cursor, VS Code, Windsurf and others
  6. Tools
  7. Change pages
  8. Workflows
  9. Permissions
  10. Security notes
  11. What is supported
  12. Examples

Looking for these docs in your assistant instead? See Flowplan docs in your AI.

Besides the optional built-in AI, MCP connects the assistant you choose. It works with your pages, databases and tasks. It sees only what you can see in Flowplan.

Set up

  1. Under Settings → API & AI assistants, create a personal API token for the assistant. Choose Read only if the assistant should only search and read. Choose Read and write if it should also create pages and records.
  2. Copy the address shown under AI assistants (MCP). It is your Flowplan address followed by /api/mcp, for example https://flowplan.example.com/api/mcp.
  3. Enter both in your client (examples below). The settings page has a ready-made configuration for each client and fills in a token you have just created.

Use a separate token for each assistant. That way you can see when each one was last used, and you can revoke one without affecting the others.

Claude Code

claude mcp add --transport http flowplan https://flowplan.example.com/api/mcp \
  --header "Authorization: Bearer fp_…"

With --scope user the connection is available in all your projects. In Claude Code, /mcp shows the connection and its tools.

Claude Desktop

Claude Desktop connects to remote MCP servers that use a token through the small mcp-remote bridge, which needs Node.js. Open Settings → Developer → Edit config, add the following to claude_desktop_config.json, and restart Claude:

{
  "mcpServers": {
    "flowplan": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://flowplan.example.com/api/mcp", "--header", "Authorization:${FLOWPLAN_AUTH}"],
      "env": { "FLOWPLAN_AUTH": "Bearer fp_…" }
    }
  }
}

The token goes in env, not in args: that way it does not appear in the process list.

ChatGPT

In ChatGPT, custom MCP connectors are available in developer mode, depending on your plan and workspace settings. Under Settings → Apps & Connectors, create a new connector with the address https://flowplan.example.com/api/mcp. If ChatGPT offers token or API key authentication, enter fp_… there.

If your ChatGPT version only offers OAuth or "No authentication", ChatGPT cannot connect to Flowplan yet. Flowplan currently signs in only with personal tokens (see What is supported). Never put the token into the address as a workaround: addresses end up in logs.

Cursor, VS Code, Windsurf and others

Clients that speak Streamable HTTP and accept their own headers use this configuration (the exact file depends on the client, e.g. .cursor/mcp.json or .vscode/mcp.json):

{
  "mcpServers": {
    "flowplan": {
      "type": "http",
      "url": "https://flowplan.example.com/api/mcp",
      "headers": { "Authorization": "Bearer fp_…" }
    }
  }
}

Tools

ToolWhat it doesToken
list_workspacesYour workspaces with your role and the spaces you can seeRead
list_pagesPages in a workspace, optionally in one space or below one pageRead
get_libraryA space as a library: books, chapters and pages you can read, with their counts Since 0.10.0; with workspaceId instead of spaceId all shelves of the workspace, your own and the shared ones, and "continue reading" New in 0.10.2, in the :beta imageRead
search_librarySearches all shelves of the library and groups the hits by level: shelves, books, chapters, pages and content with a snippet New in 0.10.2, in the :beta imageRead
searchFull-text search across pages, records, comments and file contents; also understands #tag, OR, NOT, created_by:, created:, type:, in:, title:Read
list_collectionsA workspace's collections (your own and shared ones) with their queryRead
run_collectionThe pages and records that match a collection now, with your permissionsRead
read_pageA page as Markdown; databases with their records, whiteboards with their racks, devices, ports and cablesRead
query_databaseRecords with properties by name, property definitions, views; text filter, a saved view, pagingRead
get_recordOne record with all properties and its record documentRead
my_tasksYour tasks from documents and records, with due datesRead
optimize_flashcard_parametersFits the FSRS parameters of a flashcard deck (or a part of it) to your ratings and recommends a retention with the workload per retention; stores nothing New in 0.10.2, in the :beta imageRead
create_pageNew document, database or whiteboard; documents can start with Markdown contentWrite
append_to_pageAppends Markdown to the end of a documentWrite
update_pageChanges a document's title and emoji, replaces its text or one section, or appends to it Since 0.9.8Write
move_pageMoves a page below another page or record, to the top of a space or next to a page Since 0.9.8Write
trash_pageMoves a page and the pages below it to the trash Since 0.9.8Write
set_taskChecks or unchecks a task, sets its state, due date and assignee Since 0.9.8Write
create_recordNew record; properties by name, optionally with its record document (document, Markdown)Write
update_recordChanges individual properties and/or the record document of a recordWrite
trash_recordMoves a record to the trash Since 0.9.8Write
save_collectionCreates a collection or changes its name, query, emoji and sharingWrite
delete_collectionMoves a collection to the trashWrite
set_flashcard_parametersStores your FSRS parameters for a deck, a part of it or all decks, or resets them New in 0.10.2, in the :beta imageWrite

Properties are named by their name (or ID). Dates are written as YYYY-MM-DD, options by their name, people by e-mail address or name, and relations as a list of record IDs. Text properties (except the title) are formatted text: get_database marks them with markdown: true, and they are read and written as inline Markdown (**bold**, _italic_, ~~strikethrough~~, `code`, [label](https://…), \n; see Formatted text). update_record accepts the version from get_record: if someone changed the record in the meantime, the change is refused instead of being overwritten.

Write the record document with document as Markdown – when creating with create_record, later with update_record. update_record replaces the document; with documentMode: "append" the text is added at the end. The previous state is kept as a version, and open editors see the change right away.

Change pages Since 0.9.8

update_page replaces a document's text with Markdown (mode: "replace", the default), adds it at the end ("append"), or replaces one section: section names a heading, and the heading with everything below it up to the next heading of the same or a higher level is replaced. If the Markdown starts with a heading, it takes the old heading's place; otherwise the heading stays. If the heading doesn't exist or appears more than once, the assistant gets the list of headings (pick a duplicate with occurrence). Before every replacement Flowplan keeps the text as a version, and open editors see the change right away.

read_page also returns the document's revision. Pass it to update_page: if the page changed in the meantime – also through someone typing in the editor – the change is refused, and the assistant reads the page again instead of overwriting newer text. update_page only changes documents; locked pages and pages in encrypted spaces are refused.

move_page follows the same rules as moving in the sidebar: editor rights at both ends, and never below the page itself or one of its sub-pages. trash_page and trash_record only move to the trash – you restore from there under Trash → Restore, and the answer says how long the trash keeps it. Permanent deletion is not available over MCP.

set_task changes one task without replacing the text: check or uncheck it, set its state, its due date or its assignee (by e-mail address or name; the person is notified). read_page, get_record and my_tasks name each task by index and key; with both, set_task refuses if the task changed in the meantime. The task's text alone works too, as long as it is unique.

In addition, each page is available as a resource flowplan://page/<ID> (your favourites are listed). There are two prompts: Summarize a page and Plan my day.

Workflows

For workflows there are list_workflows, get_workflow, get_workflow_catalog, list_workflow_runs, get_workflow_run (reading) and, with a write token, save_workflow_draft (graph JSON into the draft, also as a new workflow page – with the check), test_workflow (always a dry run Since 0.10.0) and run_workflow (only workflows with a manual trigger). Activating and deciding approvals are not available over MCP – those are a person's decisions about rights. So an assistant builds drafts, and you check and activate them in Flowplan.

Over MCP, test_workflow only runs as a dry run without outside connections: no e-mail, no chat message and no HTTP request – not even one the node allows in dry runs. You start a real test run yourself in Flowplan. So an assistant misled by text it read cannot send data out by testing a draft it wrote itself. Since 0.10.0

Permissions

  • Every call acts as the person who owns the token, with exactly their rights. The same checks apply as in the browser: workspace membership and guest access, private spaces, page and group permissions, private records, and journals locked with a PIN.
  • Read tokens only offer read tools. A write call with a read token is refused.
  • Write tools run the same actions as the interface. That means automatic versions, mentions and task notifications, followers, the activity log and webhooks all work as usual. Locked pages stay locked.
  • Tokens never have administrator rights and cannot create or revoke tokens.
  • The public demo has no MCP access: demo accounts cannot create tokens, and browser sessions are not accepted by /api/mcp.

Security notes

  • Treat the token like a password. Anyone who has it can read (and with a write token change) everything you can. Revoke a token under Settings → API & AI assistants if you no longer need it or it might have leaked; the connection stops immediately.
  • AI assistants can be misled by content they read (prompt injection), for example by text on a page shared with you. Give an assistant a read token if it does not need to write. With a write token, use the client's confirmation prompts for tool calls.
  • Other people's content is marked as data Since 0.10.0: what members, guests, forms, e-mails or clipped web pages wrote comes back with the note that it is data, not instructions – JSON answers (from search, query_database, get_record, my_tasks, get_meeting_note, get_workflow_run, for example) carry a contentNote field, Markdown (read_page, resources) sits between a random boundary the content cannot close. The server's instructions to the client say the same: what the tools return does not decide which tools it calls or whom it contacts.
  • No remote images Since 0.10.0: Markdown written through MCP (create_page, update_page, append_to_page, record documents) keeps only images stored as files on this instance. An image with an outside address is left out and only its alt text stays – otherwise an image address could carry data out when the page is opened. Links stay as they are.
  • Answers can contain anything you can read in Flowplan. That content goes to the provider of your assistant, so check its privacy terms first.
  • /api/mcp accepts only tokens, not the sign-in cookie, so another website cannot use your browser session. Requests from a foreign Origin are refused.
  • Limits: 120 requests per minute per person, 2 MB per request, and answers are cut after 200,000 characters. Write tools have the same size limits as the interface.

What is supported

  • Transport: Streamable HTTP (POST /api/mcp, JSON answers, no session). Protocol versions 2025-06-18, 2025-03-26 and 2024-11-05.
  • Sign-in: personal API tokens as Authorization: Bearer fp_…. OAuth sign-in (for clients that only support OAuth) is not available yet.
  • Pages can be updated, moved and moved to the trash, records moved to the trash. Since 0.9.8
  • Not included: deleting content permanently, administration, files and uploads, whiteboard contents.

Examples

  • "Search Flowplan for the offer for Müller and summarize the open points."
  • "Read the page Team meeting and add a section Decisions with today's results."
  • "Show my overdue tasks and make a plan for today."
  • "Create a record in the Bugs database: title Login on iPad hangs, status Open, assigned to [email protected]."
Was this helpful?
YesThanks!
No – tell us what's missing

Found a mistake or something missing?Edit on GitHub