PatchWork Technical Documentation

PatchWork is a high-performance visual node-based workflow automation platform for AI-powered image, video, and audio generation. It bridges human creators and autonomous AI agents via the Model Context Protocol (MCP).

Quickstart & MCP Setup

The PatchWork MCP server is packaged in tools/patchwork-mcp.mjs. It requires Node.js ≥ 21 (which includes native global WebSocket support) and zero extra npm dependencies.

┌─ offline ──▶ .nbflow files on disk        (no browser, no key needed)
agent ──MCP──┤
             ├─ headless ─▶ accounts API worker         (browser closed, requires account token)
             └─ live ─────▶ collab relay ──▶ browser    (canvas, storage, assets, video editor)
            

Claude Code Configuration

The repository ships a pre-configured .mcp.json file at the project root. Claude Code automatically reads it:

{
  "mcpServers": {
    "patchwork": {
      "command": "node",
      "args": ["tools/patchwork-mcp.mjs"],
      "env": {
        "PATCHWORK_AGENT_KEY": "YOUR_KEY_HERE"
      }
    }
  }
}

To register it globally across any folder via Claude Code CLI:

claude mcp add patchwork -- node /path/to/Patchwork/tools/patchwork-mcp.mjs

Cursor & Windsurf Setup

Add the following to your Cursor or Windsurf MCP settings file (~/.cursor/mcp.json or Workspace settings):

{
  "mcpServers": {
    "patchwork": {
      "command": "node",
      "args": ["C:/Users/Privat/Documents/Claude Code/Patchwork/tools/patchwork-mcp.mjs"],
      "env": {
        "PATCHWORK_AGENT_KEY": "ABC123.s_xxxxxxxx"
      }
    }
  }
}

Authentication & Security

PatchWork provides two distinct authentication tiers based on operational requirements:

Workflow Engine Specification

PatchWork workflows enforce strict execution invariants defined in WORKFLOW-SPEC.md. Agents creating or executing graphs must respect these rules:

Offline .nbflow Tools

Direct inspection, batch editing, and pre-spend validation of .nbflow files without needing a running browser or network connection.

{ "file": "workflows/cinematic-story.nbflow" }

{
  "file": "story.nbflow",
  "name": "Portrait Scene",
  "ops": [
    { "op": "add_node", "type": "Generation", "title": "Hero Shot", "properties": { "masterPrompt": "Cinematic portrait, golden hour", "outputCount": 4 } },
    { "op": "add_node", "type": "Video", "title": "Hero Motion", "properties": { "masterPrompt": "Gentle wind in hair, slow zoom" } },
    { "op": "connect", "from": 1, "to": 2 }
  ]
}

{ "file": "story.nbflow" }

Live Canvas Control

Control the active or background project in the user's running browser session.

{ "project": "Commercial_V1" }

{
  "project": "Cyberpunk_Teaser",
  "tab": "Scene 1",
  "mode": "gap-fill"
}

{
  "project": "Cyberpunk_Teaser",
  "nodeId": 14,
  "candidateIndex": 2
}

Projects Storage API

Direct access to project storage with background execution and optimistic concurrency guards.

Video Editor & Scene Builder

Full control over the non-linear timeline and multi-scene narrative sequence.

App Surfaces

Query model catalogues, asset repositories, workspace teams, and server-side cloud rendering.

In-App Claude Chat Channel

PatchWork includes an integrated chat panel (View → Claude Chat). Messages sent by the user in this panel are forwarded directly into your Claude Code session over the MCP claude/channel protocol.

PATCHWORK_CHANNEL=1 claude --dangerously-load-development-channels server:patchwork

{
  "chatId": "panel",
  "text": "Take 2 has sharper lighting and matches the reference style better. Sending it downstream now."
}

Autonomous Generation Operator Loop

How an autonomous agent drives end-to-end production runs:

Refusal & Error Code Reference