Canvas MCP Reference

Complete API reference for all Growhouse Canvas MCP tools.

Core Tools

list_canvases

List all canvases with MCP access enabled in the workspace.

Parameters: None required

Returns: Array of canvas objects with id, name, and metadata.

{
  "canvases": [
    {
      "id": "uuid",
      "name": "My Canvas",
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-15T12:00:00Z"
    }
  ]
}

get_canvas_overview

Get a high-level overview of a canvas including element counts, bounds, and content types.

Parameters:

Collaboration Context Object:

{
  "requesting_user_id": "your-user-id",
  "online_users": [{"user_id": "...", "display_name": "..."}],
  "cursors": [{"user_id": "...", "x": 100, "y": 200}],
  "selections": [{"user_id": "...", "element_id": "..."}],
  "text_locks": [{"user_id": "...", "element_id": "...", "locked_at": "..."}]
}

Returns: Canvas summary including element counts, bounds, and collaboration summary.

find_elements

Search for elements on a canvas by type, content, location, or collaboration status.

Parameters:

Filter Options:

{
  "type": "node",           // "node", "annotation", or "all"
  "subtype": "sticky",      // "sticky", "text-element", "media", "embed"
  "content_contains": "Q1", // Text content filter
  "quadrant": "top-left"    // "top-left", "top-right", "bottom-left", "bottom-right", "center"
}

Collaboration Filter Options:

{
  "only_available": true,         // Not locked AND not selected by others
  "only_locked": true,            // Currently locked for editing
  "only_selected_by_others": true,// Selected by other users
  "only_with_conflicts": true     // Locked OR selected by others
}

Element Subtypes:

• sticky - Plain text notes (editable)
• text-element - Rich text with Tiptap JSON (editable)
• media - Images/videos (create via create_media_element)
• embed - Social embeds (create via create_media_element)

get_element_details

Get detailed information about a specific element.

Parameters:

Include Options:

• content - Element content (default)
• styles - Visual styling (colors, fonts)
• position - x, y coordinates and dimensions
• context - Nearby elements, selection info, collaboration status

Content Format:

• For sticky: Plain text string
• For text-element: Tiptap JSON format

resolve_natural_ref

Convert a natural reference (e.g., "sticky-top-left-1") to an element UUID.

Parameters:

Natural Reference Format:

{subtype}-{quadrant}-{index}

Examples:
- sticky-top-left-1
- text-element-center-2
- media-bottom-right-1
- embed-top-right-3

Content Creation Tools

create_element

Create a new sticky note or text element on the canvas.

Parameters:

Content Format by Type:

For sticky (recommended for most use cases):

{
  "type": "sticky",
  "content": "Plain text content here"
}

For text-element (rich text):

{
  "type": "text-element",
  "content": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Your text here\"}]}]}"
}

Position Options (use ONE):

{
  "quadrant": "top-left"              // Position in canvas region
}
// OR
{
  "near_element": "sticky-top-left-1" // 50px right of another element
}
// OR
{
  "x": 100,                           // Exact coordinates
  "y": 200
}

Style Options:

{
  "sticky_color": "#FFFB91",  // Background for sticky notes
  "color": "#000000",         // Text color (hex)
  "font_size": 16             // Font size in pixels
}

Valid Sticky Colors:

create_media_element

Create an image, video, or social media embed from a URL.

Parameters:

Type: media For direct image/video files:

• .jpg, .png, .gif, .webp
• .mp4, .webm
• CDN URLs (Supabase Storage, Cloudinary, etc.)

Type: embed For social media content (auto-detected from URL):

• YouTube: https://www.youtube.com/watch?v=...
• Instagram: https://www.instagram.com/p/...
• TikTok: https://www.tiktok.com/@user/video/...
• Twitter/X: https://twitter.com/user/status/...
• LinkedIn: https://www.linkedin.com/posts/...
• Facebook: https://www.facebook.com/...
• Loom: https://www.loom.com/share/...

Display Options:

{
  "width": 340,           // Width in pixels
  "height": 400,          // Height in pixels
  "display_mode": "card", // "card", "player", or "inline" (embeds only)
  "show_caption": true,   // Show caption (embeds only)
  "muted": true           // Start muted (videos only)
}

update_element

Update an existing element's content, position, or styles.

Parameters:

*Use either element_id OR natural_ref, not both.

Important: Content format must match the element type:

• Sticky → plain text
• Text-element → Tiptap JSON

Use get_element_details first to check the current format.

delete_element

Remove an element from the canvas. This action is permanent.

Parameters:

*Use either element_id OR natural_ref, not both.

Intelligence & Collaboration Tools

get_clusters

Analyze spatial clustering and infer relationships between elements.

Parameters:

Returns: Clusters with inferred intent and relationships.

Cluster Intents:

• moodboard - Visual inspiration collection
• comparison - Side-by-side comparison
• sequence - Ordered flow or timeline
• brainstorm - Idea collection
• reference - Supporting materials

Relationship Types:

• labels - Text labeling media
• annotates - Annotation on content
• sequence_with - Part of a sequence
• compares_to - Comparison relationship

get_collaboration_status

Get real-time collaboration status for a canvas.

Parameters:

Returns:

• Online users with display names and colors
• Cursor positions of all users
• Element selections by user
• Text editing locks
• Potential conflicts

Error Handling

All tools return standard MCP error responses:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Canvas not found"
  }
}

Error Codes: