Documentation

Connect your outline to your AI apps

Use the Dotflowy Model Context Protocol (MCP) server to search your notes, capture ideas, and organize your outline from an AI app.

Connect from ChatGPT, Claude, Grok Bot, Cursor, and other AI apps that support remote MCP with OAuth. Availability varies by app, plan, and organization.

Connecting gives the AI app read and write access across your Dotflowy outline, not just selected nodes. It can change text, move nodes, and delete entire subtrees. Connect only apps you trust, and review their tool approval requests before allowing changes.

Connect Claude

You need a Dotflowy account with an Unlimited or Founding plan. The Free plan does not include MCP tool use. Your Claude account must support custom remote connectors, and your organization must permit the connection.

Use this server URL:

https://app.dotflowy.com/mcp
  1. In Claude, open Customize → Connectors.
  2. Select Add, then Add custom connector. Enter Dotflowy as the name and paste the server URL.
  3. Continue with OAuth authentication. If Claude asks how to identify its OAuth client, choose Register automatically. You do not need an API key or a manually supplied client secret.
  4. Sign in to your Dotflowy account when prompted. If you chose to sign in later, select Connect on the connector first.
  5. Enable Dotflowy for your conversation from Claude's connector controls.
  6. Ask Claude: Search my Dotflowy outline for #project. Do not change anything. A search result, or a response that no nodes match, confirms that a read tool works.

For Team and Enterprise workspaces, an authorized owner or admin must first add the custom connector in Organization settings → Connectors. Each member then connects with their own Dotflowy account. See Claude's custom connector guide for current interface labels, plan availability, and organization roles.

Other MCP clients

Dotflowy uses Streamable HTTP with OAuth 2.1, PKCE, and dynamic client registration. Use the same URL in a client that supports these features. For client-specific instructions, open Dotflowy Settings, then select Connections → Connect apps (MCP).

Available tools

A node is one item in your outline. A subtree includes that node and all its descendants. Connected apps discover the current tool inputs through MCP. Changes appear in your connected Dotflowy editor.

Read tools

get_outline
Read your outline, or one node and its subtree, with node IDs.
search_nodes
Find nodes by text, tags, and filters such as incomplete tasks.
export_opml
Export your outline or a subtree as an OPML document.

Write tools

add_node
Create a node under a parent or at the top level.
add_subtree
Create a nested outline in one atomic operation.
update_node
Change text, task status, completion, or collapse state. Editing a mirror changes its shared content everywhere.
delete_node
Delete a node and its entire subtree. The agent cannot undo this operation.
move_nodes
Move nodes with their subtrees, preserving their IDs and content.
add_to_today
Add a node to a daily note, creating the daily note if needed.
mirror_node
Place a mirror of an existing node under another parent or at the top level. A mirror shares content with its source, rather than making a copy.
mirror_to_today
Place a mirror of an existing node in a daily note.
import_opml
Import an OPML document as new nodes. Supports a dry run that previews the import without writing.

Usage limits

  • get_outline returns up to 500 nodes per call and reports truncation. Ask for a specific subtree to read more.
  • search_nodes returns 25 matches by default, up to 100 per page. The app must follow continuation cursors for more matches.
  • add_subtree accepts up to 500 nodes per call.
  • OPML import and export each accept up to 5,000 nodes. Requests over this limit fail rather than silently truncate.
  • For daily tools, provide a date or your IANA time zone, such as America/Chicago. Without either, today uses UTC and may differ from your local date.

Security and privacy

Account access and authentication

Dotflowy authenticates MCP requests with OAuth bearer tokens and routes them to the signed-in user's outline. The connector does not grant access to other users' outlines. You sign in with Dotflowy, rather than giving the AI app your Dotflowy password.

There is no Dotflowy read-only connection mode or per-subtree authorization. Scoping a tool call to a node limits that request, not the connection's permissions. Collapsing nodes, hiding completed nodes, or turning off an editor feature does not restrict MCP access. Use your AI app's tool controls to limit what it invokes, but do not treat them as a Dotflowy permission boundary.

Locked content

Locks set in the editor protect content in a node and its descendants from changes, including changes through mirrors. MCP clients cannot lock or unlock nodes. They can still read locked content and move a locked subtree intact. Locks are mutation protection, not secrecy.

Spoiler redaction

Spoiler text marked with ||hidden text|| becomes [spoiler] in MCP results, including exports and breadcrumbs. MCP search does not match text inside spoilers. This reduces accidental disclosure to an AI app, but it is not access control and does not make an untrusted connection safe.

If an app replaces a node's text using a redacted result, the hidden text is lost. Ask the app not to rewrite nodes containing [spoiler] unless you provide the intended full text.

Data handling

Tool results send outline content to the AI app you connect. Review that provider's data handling and retention policies before connecting sensitive notes. Dotflowy runs on Cloudflare and stores each user's outline in a separate database. Notes are not end-to-end encrypted. Read the Dotflowy privacy policy and terms of service for service-wide details.

Disconnecting and revocation

You can disable or remove Dotflowy in your AI app's connector settings. Dotflowy does not currently provide a page to list and revoke individual MCP client connections. Do not assume removal in an AI app invalidates credentials already issued by Dotflowy. If you suspect unwanted access, contact support@dotflowy.com.

Troubleshooting

The connector is unavailable in Claude
Check your Claude account's connector availability and organization policy. Team and Enterprise members may need an owner or admin to add it first.
Sign-in fails or requests are unauthorized
Check that the URL is exactly https://app.dotflowy.com/mcp, use automatic OAuth registration, and reconnect with the intended Dotflowy account. Opening the server URL directly in a browser is not a connection test.
Tools appear, but calls require an upgrade
Tool discovery can succeed on a Free account. Tool execution requires Unlimited or Founding on the Dotflowy account you used to connect.
A write is rejected
Read the tool's error. Locked content and protected daily-note structure can block changes. If appropriate, unlock the content yourself in Dotflowy before retrying.
Search results are incomplete
Ask the app to follow continuation cursors. If the outline changes during pagination, restart the search. Text inside spoilers does not match.

Get help

Email support@dotflowy.com for connection, privacy, or security questions. For reproducible bugs, you can also open a GitHub issue. Include your client name, the tool name, and a redacted error message. Never post tokens, passwords, or private outline content.