Motion Skill

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 o...

Security Scan

The skill's instructions match a real-time Motion-style editor, but they direct the agent to send workspace-wide agent tokens and invite tokens to an unverified third-party endpoint (motion-mcp-server.fly.dev), which could expose sensitive data.

Purpose & Capability

Name/description (Motion document editing) align with the provided API and examples, but all HTTP calls point to https://motion-mcp-server.fly.dev — not an obvious official Motion domain. Using a third-party host as the API endpoint is disproportionate to the stated purpose unless the host is explicitly owned/endorsed by Motion or the user's org.

Instruction Scope

SKILL.md explicitly instructs the agent to POST agent_token (workspace-wide, full-access) or invite_token to the listed BASE URL to create sessions and connect to documents. The instructions do not reference unrelated files or env vars, but they do direct transmission of highly sensitive tokens to an external service under the skill's control, creating an exfiltration risk.

Install Mechanism

No install spec and no code files — instruction-only skill. This minimizes on-disk risk (no arbitrary binary downloads), but network calls still occur when the agent follows the instructions.

Credentials

The skill does not declare required env vars, but it requires the user/agent to provide agent_token or invite_token at runtime. Those tokens grant broad workspace access; sending them to the skill's specified host is not proportionate without proof the host is legitimate/trusted. The skill requests no other unrelated credentials.

Persistence & Privilege

always is false and the skill does not request persistent system privileges. It does allow normal autonomous invocation (platform default) but that alone is not flagged; combined with the instructions to transmit tokens to a third-party host increases risk.

What to consider before installing

This skill appears to perform Motion-like document editing, but it instructs the agent to send agent tokens (which grant full workspace access) or invite tokens to https://motion-mcp-server.fly.dev — an unverified third-party host. Before installing or using it: - Do not paste or provide real agent_tokens or invite URLs unless you trust the host. Treat tokens as highly sensitive. - Ask the skill author to confirm the ownership of motion-mcp-server.fly.dev and to provide a canonical official API endpoint (e.g., a Motion-owned domain) or endorsement. - Prefer skills that call the official Motion API or that let you self-host the proxy inside your org. - If you must test, use throwaway or least-privilege tokens and rotate/revoke them after testing. Monitor audit logs for unexpected activity. If the maintainer demonstrates that motion-mcp-server.fly.dev is an official Motion service or a trusted, org-owned proxy, this assessment could change to benign; otherwise treat it as a potential token-exfiltration risk.

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.

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}

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:

# 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:

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):

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

Disconnect when done

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)

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

Document-level (requires document connection)

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

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