> ## Documentation Index
> Fetch the complete documentation index at: https://opencanvas.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect DesignJS to Claude Code

> Two ways to register DesignJS as an MCP server in Claude Code — automatic via designjs init, or manual via claude mcp add — plus verification steps.

DesignJS exposes a Model Context Protocol (MCP) server that Claude Code connects to over stdio. Once connected, Claude can read your canvas (component tree, HTML, CSS, screenshots) and write to it (insert components, update styles, delete nodes) — all without leaving the conversation. This page walks you through both the automatic and manual setup paths.

## Prerequisites

Before connecting, make sure DesignJS is running:

```bash theme={null}
pnpm dev
```

The canvas opens at `http://localhost:3000` and the WebSocket bridge starts listening on `127.0.0.1:29170`. The bridge status indicator in the top-right corner of the editor turns green when an MCP server process connects.

## Method 1 — Scaffold a fresh project

The `create-designjs` scaffolder (published on npm) drops `.mcp.json`, `CLAUDE.md`, and a `README.md` into a new directory in one command:

```bash theme={null}
npm create designjs@latest my-app
cd my-app
```

Then launch Claude Code **from inside `my-app`** (not its parent — Claude Code reads `.mcp.json` from the cwd it was launched in, and launching from the parent won't pick up the project config):

```bash theme={null}
claude
```

The `CLAUDE.md` that ships with the template includes explicit guidance nudging the agent toward the `designjs.*` tools and away from other design MCPs (Pencil, Paper, Figma) that might be configured globally.

<Warning>
  `create-designjs` refuses to scaffold into a non-empty directory. For existing projects, use Method 2.
</Warning>

## Method 2 — Manual configuration (existing projects)

Write `.mcp.json` by hand in the project root:

```json theme={null}
{
  "mcpServers": {
    "designjs": {
      "command": "npx",
      "args": ["-y", "@designjs/mcp-server"]
    }
  }
}
```

Or register DesignJS at **user scope** so it's available across every Claude Code project, not just this one:

```bash theme={null}
claude mcp add designjs --scope user -- npx -y @designjs/mcp-server
```

This writes into your Claude Code user config (`~/.claude.json`) instead of the project. Use `--scope project` if you want the current project only.

## Verifying the connection

<Steps>
  <Step title="Start a Claude Code session">
    Open Claude Code in your project directory where `.mcp.json` is located.
  </Step>

  <Step title="Run /mcp">
    Type `/mcp` in the Claude Code chat. It should list `designjs` along with all available tools.

    You should see 20+ tools including `ping`, `get_tree`, `get_html`, `get_css`, `get_screenshot`, `get_selection`, `add_components`, `update_styles`, and `delete_nodes`.
  </Step>

  <Step title="Test with ping">
    Ask Claude: "Call the designjs ping tool." If the canvas is running and the bridge is connected, the response will include `{ pong: true, at: <timestamp> }`. The bridge status dot in the editor will also turn green.
  </Step>
</Steps>

## Troubleshooting

<CardGroup cols={2}>
  <Card title="designjs not listed in /mcp at all" icon="circle-x">
    You launched Claude Code from the wrong directory. Claude Code reads `.mcp.json` from the cwd it was started in — `cd` into the project directory first, then `claude`. Also: if Claude Code is showing a trust-this-project prompt, accept it — project MCP servers stay disabled until you do.
  </Card>

  <Card title="designjs · ◯ connecting… never turns green" icon="clock">
    First launch downloads `@designjs/mcp-server` via `npx -y` — 10–30 seconds on cold cache, then instant. If it's stuck past a minute, run `npx -y @designjs/mcp-server </dev/null` standalone to confirm the install works.
  </Card>

  <Card title="designjs · ✘ failed" icon="triangle-alert">
    The MCP server started but couldn't reach the canvas bridge on `127.0.0.1:29170`. Start the canvas: `pnpm dev` in the DesignJS repo. Check the topbar bridge dot — grey means the canvas isn't running.
  </Card>

  <Card title="The agent used Pencil / Paper / Figma instead of DesignJS" icon="arrows-rotate">
    You have competing design MCPs registered globally in `~/.claude.json`. The `CLAUDE.md` that `create-designjs` drops tells the agent to prefer DesignJS — but you can reinforce it in the prompt itself ("use designjs, not pencil") or remove the competing entries from your user config.
  </Card>

  <Card title="Stale 'opencanvas' entry shows as failed" icon="arrow-rotate-left">
    Pre-rebrand entries in `~/.claude.json`'s `mcpServers` try to reconnect on every launch. Open the file and delete the `"opencanvas"` key from the `mcpServers` object; restart Claude Code.
  </Card>

  <Card title="Tool call hangs with no response" icon="hourglass">
    The MCP server started but the bridge dropped. Restart the canvas (`pnpm dev`), then start a fresh Claude Code session — the server reconnects automatically.
  </Card>
</CardGroup>

<Warning>
  If you have multiple MCP servers registered under the same `designjs` name (e.g., one project-scope and one user-scope), the last one registered wins. Run `/mcp` to audit.
</Warning>