Motion Document Agent#

You are a real-time collaborative document editor. Your edits appear live in the user's browser. You appear in the presence bar alongside human collaborators. Other users may be viewing and editing the same document simultaneously.

By default, your edits are wrapped in suggestion marks so humans can review and accept/reject them before they become permanent. You can also operate in direct mode.

Authentication#

There are two auth methods:

Agent token (preferred)#

Workspace admins generate agent tokens from Settings > Agent tokens. Each token grants full access to all documents in the workspace. The token is a 64-character hex string.

bash

curl -X POST https://motion-mcp-server.fly.dev/sessions \
  -H "Content-Type: application/json" \
  -d '{"agent_token": "{TOKEN}", "agent_name": "Claude"}'

Invite token (legacy)#

Extract from an invite URL: https://{APP_HOST}/invite/{INVITE_TOKEN}/{DOCUMENT_ID}

bash

curl -X POST https://motion-mcp-server.fly.dev/sessions \
  -H "Content-Type: application/json" \
  -d '{"invite_token": "{INVITE_TOKEN}", "document_id": "{DOCUMENT_ID}", "agent_name": "Claude"}'

Connection#

Workspace-first flow (recommended with agent tokens)#

Create a session without a document — browse, create, then connect:

bash

# 1. Create workspace-only session
curl -X POST $BASE/sessions \
  -H "Content-Type: application/json" \
  -d '{"agent_token": "{TOKEN}", "agent_name": "Claude"}'

# 2. List pages, create pages, manage folders — all without a document

# 3. Connect to a document when ready
curl -X POST $BASE/sessions/:id/connect \
  -H "Content-Type: application/json" \
  -d '{"document_id": "{PAGE_ID}"}'

# 4. Or create a new page and connect in one step
curl -X POST $BASE/sessions/:id/pages \
  -H "Content-Type: application/json" \
  -d '{"title": "My Doc", "auto_connect": true}'

Direct document session#

If you know which document to edit, connect immediately:

bash

curl -X POST $BASE/sessions \
  -H "Content-Type: application/json" \
  -d '{"agent_token": "{TOKEN}", "document_id": "{PAGE_ID}", "agent_name": "Claude"}'

Switch documents#

Switch to a different document within the same session (workspace boundary enforced):

bash

curl -X POST $BASE/sessions/:id/connect \
  -H "Content-Type: application/json" \
  -d '{"document_id": "{ANOTHER_PAGE_ID}"}'

Disconnect when done#

bash

curl -X DELETE $BASE/sessions/:id

Security Model#

• Agent tokens grant workspace-wide access — all documents, folders, comments, versions
• Agents can only access documents within their authorized workspace
• switch_document and /connect validate that the target document belongs to the workspace
• All page/folder mutations are workspace-scoped at the database level
• Tokens can be revoked by workspace admins at any time

Core Editing Workflow#

1. Read first — call GET /sessions/:id/document to get all blocks with stable IDs
2. Edit by block ID — always use block IDs (UUIDs), never array indexes. IDs persist across concurrent edits.
3. Use format_text_by_match for formatting — specify the text string, not character offsets
4. Re-read after edits if you need to continue editing or verify changes
5. Disconnect when done

Suggestion Mode#

Agents default to suggestion mode: edits appear as green underlines (additions) or strikethroughs (deletions) that humans can accept or reject.

All edit endpoints ( insert, update, replace, delete, find-and-replace) accept an optional "mode" field:

• "suggest" (default) — wraps edits in suggestion marks for human review
• "direct" — applies edits immediately without suggestion marks

You can also:

• List suggestions: see all pending suggestions in the document
• Accept/reject: review another agent's suggestions
• Bulk operations: accept-all or reject-all

Capabilities#

Page & Folder Management (workspace-level — no document connection needed)#

List all workspace pages and folders. Create, rename, delete, restore pages. Create, rename, delete folders. Move pages between folders and positions. These work even without a document connection.

For endpoint details: read references/api-reference.md (Page Management and Folder sections)

Document Editing (requires document connection)#

Read, insert, update, delete, move blocks. Apply formatting (bold, italic, links, etc.). Find and replace text. Full ProseMirror JSON support for rich content.

For endpoint details: read references/api-reference.md (Document Editing section) For block/mark JSON format: read references/block-format-reference.md

Comments (requires document connection)#

Read all comment threads on a page. Create new threads, reply to existing ones, resolve threads when discussion is complete, reopen resolved threads.

For endpoint details: read references/api-reference.md (Comments section)

Version History (requires document connection)#

List saved versions. Save a named version snapshot before making large changes. Useful for checkpointing your work.

For endpoint details: read references/api-reference.md (Versions section)

Export (requires document connection)#

Export the current document as Markdown or HTML. Returns content as text.

For endpoint details: read references/api-reference.md (Export section)

Suggestion Review (requires document connection)#

List all pending suggestions. Accept or reject individual suggestions by ID. Bulk accept-all or reject-all.

For endpoint details: read references/api-reference.md (Suggestions section)

Quick Reference: Key Endpoints#

Workspace-level (no document needed)#

ActionMethodPathCreate sessionPOST/sessionsConnect to documentPOST/sessions/:id/connectList pagesGET/sessions/:id/pagesCreate pagePOST/sessions/:id/pagesCreate page + connectPOST/sessions/:id/pages (with auto_connect: true)Rename pagePATCH/sessions/:id/pages/:pidDelete pageDELETE/sessions/:id/pages/:pidRestore pagePOST/sessions/:id/pages/:pid/restoreMove pagePOST/sessions/:id/pages/moveList foldersGET/sessions/:id/foldersCreate folderPOST/sessions/:id/foldersRename folderPATCH/sessions/:id/folders/:fidDelete folderDELETE/sessions/:id/folders/:fidDisconnectDELETE/sessions/:id

Document-level (requires document connection)#

ActionMethodPathRead documentGET/sessions/:id/documentInsert blockPOST/sessions/:id/blocksFormat textPOST/sessions/:id/blocks/:bid/format-by-matchDelete blockDELETE/sessions/:id/blocks/:bidList commentsGET/sessions/:id/commentsCreate commentPOST/sessions/:id/commentsSave versionPOST/sessions/:id/versionsExportGET/sessions/:id/export?format=markdownList suggestionsGET/sessions/:id/suggestionsAccept suggestionPOST/sessions/:id/suggestions/:sid/accept

For the complete API with request/response schemas: read references/api-reference.md For common editing patterns and examples: read references/examples.md

Tips#

• Use an agent token for workspace-wide access — no need to deal with invite URLs
• Create a workspace-only session first, list pages, then connect to the one you need
• Use auto_connect: true when creating a page to start editing it immediately
• Always call read_document first to understand block structure and IDs
• Use format-by-match instead of offset-based formatting — it handles nested blocks
• When building a list, send the entire list as one insert_block call
• Save a version before making large destructive changes
• The agent identifies as agent:Claude in comments and suggestions
• If the same text appears multiple times, use the occurrence parameter
• Use POST /sessions/:id/connect to switch between documents without creating a new session
• Callout blocks support variants: info, warning, error, success
• Agents can only access documents within their authorized workspace — cross-workspace access is blocked