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