Model Context Protocol in DesignJS

Learn how DesignJS implements MCP — the stdio server, the WebSocket bridge, and what bidirectional agent access to the canvas means in practice.

The Model Context Protocol (MCP) is an open standard that lets AI agents call external tools through a structured, transport-agnostic interface. DesignJS implements MCP to give agents — Claude Code, Cursor, Codex — direct read/write access to the visual canvas. When your agent is connected, it can inspect the design, take screenshots, insert HTML, update styles, and delete elements, all through standard MCP tool calls that the canvas executes in real time.

Architecture overview

DesignJS uses a two-layer communication architecture: a stdio MCP server that the agent talks to, and a WebSocket bridge that relays those calls to the browser where the canvas lives.

┌───────────────────┐     stdio      ┌─────────────────┐
│  Claude Code /    │──────────────▶│   MCP Server    │
│  Cursor / Codex   │     (JSON-RPC) │   (Node.js)     │
└───────────────────┘                └───────┬─────────┘
                                             │ WebSocket (127.0.0.1:29170)
                                             ▼
┌─────────────────────────────────────────────┐
│      Browser (Vite + React SPA)             │
│  ┌────────────┐  ┌───────────────────────┐  │
│  │ Editor UI  │  │  GrapesJS Canvas      │  │
│  │ (panels,   │  │  (iframe with         │  │
│  │  blocks,   │  │   real HTML/CSS       │  │
│  │  styles)   │  │   + Tailwind v4 CDN)  │  │
│  └────────────┘  └───────────────────────┘  │
└─────────────────────────────────────────────┘
                      │
              ┌───────┴───────┐
              │ .designjs   │
              │   .json       │
              └───────────────┘

Every agent-to-canvas interaction travels the same path: the agent sends a tool call over stdio → the MCP server validates the input and forwards it over WebSocket → the browser receives it, executes it against the GrapesJS API, and sends the result back → the MCP server returns it to the agent.

The stdio MCP server

The MCP server is a standalone Node.js process that uses stdio transport — it reads JSON-RPC messages from standard input and writes responses to standard output. This is the transport mode that Claude Code, Cursor, and VS Code all support natively for MCP servers.

Your agent spawns the MCP server process and communicates with it directly. The server handles the MCP handshake, registers all available tools, and routes incoming tool calls to the canvas over the WebSocket bridge.

All tools are registered automatically when the server starts. Every tool in the DesignJS tool set is available to your agent without any additional configuration.

The WebSocket bridge

The WebSocket bridge runs on ws://127.0.0.1:29170/designjs-bridge and is embedded in the Vite dev server process (started by pnpm dev). It acts as a relay between the MCP server and the browser.

Both peers — the MCP server and the browser canvas — connect to the bridge and identify themselves with a hello message:

{ "type": "hello", "role": "mcp-server" }
{ "type": "hello", "role": "canvas" }

When a tool call arrives from the agent, the MCP server wraps it in a request message and sends it to the bridge. The bridge routes it to the canvas peer. The canvas executes the tool, wraps the result in a response message, and sends it back through the bridge to the MCP server, which returns it to the agent.

The bridge is bound to 127.0.0.1 (loopback only) and is not accessible from other machines on your network. This is intentional — agent access to the canvas is local only.

Available MCP tools

DesignJS ships 20+ tools in v0.1, covering the full read/write surface of the canvas. A representative slice:

Category	Example tools	What they do
Inspect	ping, get_tree, get_html, get_css, get_screenshot, get_selection, get_jsx, get_variables	Observe the current canvas state (tree, HTML, CSS, screenshots, selection, computed JSX, design tokens).
Component mutation	add_components, update_styles, add_classes, remove_classes, set_text, delete_nodes	Insert HTML, change styles, manage Tailwind classes, edit text, remove nodes.
Artboards	create_artboard, list_artboards, find_placement, fit_artboard	Create named artboards at specific dimensions, list them, find non-overlapping placement, fit an artboard to its content.
Variables	set_variables, get_variables	Read and write CSS custom properties that apply to the iframe :root.
Selection	select, deselect	Drive the editor’s selection so agents can highlight what they’re about to change.

The full per-tool reference — input/output schemas, example prompts, failure modes — lives at MCP Tools Overview →.

Start any agent workflow with ping to confirm the canvas is reachable before issuing read or write calls.

What this means for you

From your perspective as a user or integrator, the MCP layer is mostly invisible. You connect the agent once (see Connect an AI Agent) and then interact with it naturally. Ask your agent to “add a hero section with a blue background” and it will call add_components with the appropriate HTML. Ask it to “make the headline text larger” and it will call get_selection or get_tree to find the right component, then call update_styles.

The bidirectional nature of the protocol matters in practice: the agent isn’t just reading a snapshot of your design — it’s operating on the live canvas, the same one you’re looking at. Changes appear immediately in your browser as the agent makes them. You can also select something in the editor and tell the agent “update what I have selected,” and it will call get_selection to find the right component IDs before acting.

Multi-peer support

The bridge supports multiple simultaneous connections. If you have the canvas open in two browser tabs, or you run the MCP server process twice, both connections are tracked. Requests from any MCP server peer are routed to the active canvas peer. This foundation supports concurrent agent sessions, which is planned for a future release.