MCP Tools Reference

vpick provides 34 MCP tools that allow AI Agents (like Claude) to directly control the canvas, create nodes, generate images/videos/audio/music, and manage projects.

Canvas Browsing

Tool	Description
`get_canvas`	Get the entire canvas data (nodes and edges)
`get_canvas_info`	Get canvas summary (node count, edge count, type distribution)
`list_nodes`	List all nodes with position, size, status, and generated results
`get_node`	Get complete data for a single node

Example: View Canvas

{ "method": "tools/call", "params": { "name": "get_canvas_info" } }

Returns:

{
  "nodeCount": 5,
  "edgeCount": 3,
  "nodeTypes": { "text": 1, "imageGenerator": 2, "videoGenerator": 1, "upload": 1 }
}

Node Operations

Tool	Description
`add_node`	Create a new node (supports all types)
`update_node`	Update node content, parameters, or position
`remove_nodes`	Delete one or more nodes
`duplicate_nodes`	Duplicate nodes

Supported Node Types

type value	Node Type
`text`	Text
`assistant`	AI Assistant
`imageGenerator`	Image Generator
`videoGenerator`	Video Generator
`audioGenerator`	Audio Generator (Voice Over)
`musicGenerator`	Music Generator
`lipsyncGenerator`	Lipsync
`vocalSeparator`	Vocal Separator
`voiceChanger`	Voice Changer
`audioCombine`	Audio Combine
`combine`	Video Combine
`upload`	Upload
`list`	List
`output`	Output
`group`	Group

Example: Create a Video Generator Node

{
  "method": "tools/call",
  "params": {
    "name": "add_node",
    "arguments": {
      "type": "videoGenerator",
      "name": "Product Ad Video",
      "x": 600,
      "y": 200
    }
  }
}

Example: Set Node Parameters

{
  "method": "tools/call",
  "params": {
    "name": "update_node",
    "arguments": {
      "node_id": "node-abc123",
      "data": {
        "prompt": "A golden retriever running on the beach at sunset",
        "model": "kling-3.0/video",
        "duration": 5,
        "mode": "std"
      }
    }
  }
}

Connection Operations

Tool	Description
`connect_nodes`	Connect two nodes (specify handles)
`disconnect_nodes`	Disconnect a connection

Common Handles

Source Handle	Target Handle	Description
`text-out`	`text-in`	Text connection
`image-out`	`image-in`	Image connection
`image-out`	`start-image-in`	Video start frame
`image-out`	`end-image-in`	Video end frame
`video-out`	`videos-in`	Video combine
`audio-out`	`audio-in`	Audio connection
`list-out`	`list-in`	List batch

Example: Connect Text to Video Generator

{
  "method": "tools/call",
  "params": {
    "name": "connect_nodes",
    "arguments": {
      "source_node_id": "node-text1",
      "source_handle": "text-out",
      "target_node_id": "node-video1",
      "target_handle": "text-in"
    }
  }
}

Generation

Tool	Description
`run_assistant`	Run AI Assistant (text generation)
`run_image_generator`	Run image generation
`run_video_generator`	Run video generation
`run_audio_generator`	Run voice generation (TTS)
`run_music_generator`	Run music generation
`run_lipsync_generator`	Run lipsync
`run_vocal_separator`	Run vocal separation
`run_voice_changer`	Run voice changer
`run_audio_combine`	Run audio mixing
`run_combine`	Combine videos

Example: Generate a Video

{
  "method": "tools/call",
  "params": {
    "name": "run_video_generator",
    "arguments": { "node_id": "node-video1" }
  }
}

Note: Generation tools automatically check credits. If credits are insufficient and auto-recharge is enabled, it will charge automatically.

Workflows

Tool	Description
`create_workflow`	Create a workflow (define execution order)
`run_workflow`	Run a created workflow

Workflows define multiple steps to execute in sequence. Perfect for "AI generates copy -> generate images -> generate videos -> combine" pipelines.

Project Management

Tool	Description
`list_projects`	List all projects
`create_project`	Create a new project
`switch_project`	Switch to a specific project

Layout & Groups

Tool	Description
`move_nodes`	Batch move node positions
`auto_layout`	Auto-arrange nodes (grid / row / column)
`create_group`	Create a visual group
`update_group`	Update group (add/remove members, resize)
`ungroup`	Dissolve a group

History & Upload

Tool	Description
`list_generated_files`	Query generation history
`get_generation_stats`	View usage statistics by model
`upload_image`	Download an image from URL and upload to canvas
`list_models`	List all available models and their specs

@ Reference Syntax

Use @node_name in prompts to reference a connected node's output:

Generate a product photo based on @Product Description

Supported reference sources:

Text node: References the content field
AI Assistant: References the result field
Image Generator / Upload: References the image URL
List: References list items

Important Notes

Avoid parallel modifications: MCP calls for the same project should be executed sequentially to avoid race conditions
Node naming: Use the name parameter when calling add_node for easy @ referencing
Auto-positioning: Omit the y parameter and nodes will automatically be placed below existing nodes
Duplicate prevention: Each generation tool uses claimNodeForProcessing() to prevent duplicate triggers