Use this skill when the user pastes a Motion invite URL (contains /invite/ or /agent/), asks to "edit a Motion document", "connect to Motion", "collaborate on a document", "write to Motion", or provides a document_id/agent_token/invite_token for real-time editing. Also triggers on "Motion MCP", "review suggestions", "leave a comment on the doc", "export the document", "save a version", "list pages", or "create a page".
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.
There are two auth methods:
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.
curl -X POST https://motion-mcp-server.fly.dev/sessions \
-H "Content-Type: application/json" \
-d '{"agent_token": "{TOKEN}", "agent_name": "Claude"}'
Extract from an invite URL: https://{APP_HOST}/invite/{INVITE_TOKEN}/{DOCUMENT_ID}
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"}'
Create a session without a document — browse, create, then connect:
# 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}'
If you know which document to edit, connect immediately:
curl -X POST $BASE/sessions \
-H "Content-Type: application/json" \
-d '{"agent_token": "{TOKEN}", "document_id": "{PAGE_ID}", "agent_name": "Claude"}'
Switch to a different document within the same session (workspace boundary enforced):
curl -X POST $BASE/sessions/:id/connect \
-H "Content-Type: application/json" \
-d '{"document_id": "{ANOTHER_PAGE_ID}"}'
curl -X DELETE $BASE/sessions/:id
switch_document and /connect validate that the target document belongs to the workspaceGET /sessions/:id/document to get all blocks with stable IDsAgents 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 marksYou can also:
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)
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
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)
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 the current document as Markdown or HTML. Returns content as text.
For endpoint details: read references/api-reference.md (Export section)
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)
| Action | Method | Path |
|---|---|---|
| Create session | POST | /sessions |
| Connect to document | POST | /sessions/:id/connect |
| List pages | GET | /sessions/:id/pages |
| Create page | POST | /sessions/:id/pages |
| Create page + connect | POST | /sessions/:id/pages (with auto_connect: true) |
| Rename page | PATCH | /sessions/:id/pages/:pid |
| Delete page | DELETE | /sessions/:id/pages/:pid |
| Restore page | POST | /sessions/:id/pages/:pid/restore |
| Move page | POST | /sessions/:id/pages/move |
| List folders | GET | /sessions/:id/folders |
| Create folder | POST | /sessions/:id/folders |
| Rename folder | PATCH | /sessions/:id/folders/:fid |
| Delete folder | DELETE | /sessions/:id/folders/:fid |
| Disconnect | DELETE | /sessions/:id |
| Action | Method | Path |
|---|---|---|
| Read document | GET | /sessions/:id/document |
| Insert block | POST | /sessions/:id/blocks |
| Format text | POST | /sessions/:id/blocks/:bid/format-by-match |
| Delete block | DELETE | /sessions/:id/blocks/:bid |
| List comments | GET | /sessions/:id/comments |
| Create comment | POST | /sessions/:id/comments |
| Save version | POST | /sessions/:id/versions |
| Export | GET | /sessions/:id/export?format=markdown |
| List suggestions | GET | /sessions/:id/suggestions |
| Accept suggestion | POST | /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
auto_connect: true when creating a page to start editing it immediatelyread_document first to understand block structure and IDsformat-by-match instead of offset-based formatting — it handles nested blocksinsert_block callagent:Claude in comments and suggestionsoccurrence parameterPOST /sessions/:id/connect to switch between documents without creating a new session