Connect an AI Agent to DesignJS

Register the DesignJS MCP server with Claude Code, Cursor, or VS Code — via the published create-designjs scaffolder or a hand-written three-line .mcp.json.

DesignJS exposes a stdio MCP server (@designjs/mcp-server, published on npm) that any compatible AI agent can connect to. Once registered, the agent gains access to the full canvas toolset — reading the component tree, capturing screenshots, inserting HTML, updating styles, creating artboards, and more.

There are two supported registration paths today:

1. create-designjs scaffolder — for a brand-new project directory. Writes .mcp.json, CLAUDE.md, and a README.md in one command.
2. Manual .mcp.json — for existing projects or non-default IDE config paths.

Make sure the canvas dev server is running (pnpm dev inside the DesignJS repo clone) before connecting an agent. The MCP server communicates with the canvas over ws://127.0.0.1:29170/designjs-bridge; if the canvas isn’t running, tool calls will hang.

An auto-detecting designjs init CLI (inspects your project and writes the right config per IDE) is in the repo but not yet published to npm. Until it ships, use one of the two paths below.

Method 1 — create-designjs scaffolder (new projects)

The scaffolder is the fastest path if you don’t already have a project directory:

npm create designjs@latest my-app
cd my-app

It creates my-app/ with:

my-app/
├── .mcp.json        # points at npx -y @designjs/mcp-server
├── CLAUDE.md        # tells agents to prefer designjs.* tools
└── README.md        # per-project quickstart + troubleshooting

Now launch your agent from inside my-app:

claude          # Claude Code — reads .mcp.json automatically
# or
cursor .
# or
code .

On the first tool call, the agent spawns npx -y @designjs/mcp-server and connects to the canvas.

create-designjs refuses to scaffold into a non-empty directory — this is intentional to avoid overwriting your work. For existing projects, use Method 2.

Method 2 — Manual .mcp.json (existing projects)

For a project that already has code, write the MCP config directly in the project root. The file name depends on your IDE:

IDE	Config path
Claude Code / Codex	.mcp.json (project root)
Cursor	.cursor/mcp.json
VS Code (Copilot / Continue)	.vscode/mcp.json

The contents are the same in all three:

{
  "mcpServers": {
    "designjs": {
      "command": "npx",
      "args": ["-y", "@designjs/mcp-server"]
    }
  }
}

On the first tool call from your agent, npx will download @designjs/mcp-server (~10–30s on first install, then cached) and start it.

User-scope registration (Claude Code only)

If you want DesignJS available across all your Claude Code projects rather than per-project, register it at user scope:

claude mcp add designjs --scope user -- npx -y @designjs/mcp-server

This writes into your Claude Code user config (~/.claude.json) so every session everywhere picks it up.

Verifying the connection

1. Confirm the canvas is running

   lsof -iTCP:29170 -sTCP:LISTEN   # should show a node process
   

   Or open http://localhost:3000 in a browser — if the editor loads, the bridge is up.

2. Launch your agent from the project directory

   Claude Code only reads .mcp.json from the directory you launch it in. If you cd into the project’s parent and run claude, the project’s MCP config is invisible — this is by far the most common “my MCP isn’t showing up” cause.

3. Run /mcp

   In Claude Code, type /mcp. You should see designjs · ✓ connected in the list.

   First launch: the status may read ◯ connecting… for 10–30 seconds while npx -y @designjs/mcp-server downloads the package on cold cache. Subsequent launches are instant.

4. Smoke-test with ping

   Ask the agent: “Call the designjs.ping tool.” It should return { pong: true, at: <timestamp> } within a second, and the bridge dot in the canvas topbar turns green.

Troubleshooting

/mcp doesn't list designjs at all

You ran claude from the wrong directory. Claude Code reads .mcp.json from the cwd it was launched in. Quit and relaunch it from inside the project directory that contains .mcp.json.

If the file exists in the right place and still isn’t being loaded, also check:

• Claude Code prompts to trust new projects on first visit. Until you accept the trust dialog, project-level MCP servers stay disabled. Look for pending prompts when you launch.
• In Claude Code’s user config at ~/.claude.json, the project entry’s enabledMcpjsonServers must include "designjs" (or be empty — empty means “all”). A previously-rejected server stays in disabledMcpjsonServers until you re-enable it.

/mcp shows designjs · ◯ connecting… and never turns green

Normal behavior on cold install — npx -y @designjs/mcp-server has to download the package the first time. Give it 30 seconds.

If it stays stuck past a minute, run the server standalone to check the install:

npx -y @designjs/mcp-server </dev/null

You should see [designjs-mcp] mcp server ready on stdio on stderr within a few seconds. If you see bridge connect errors (ECONNREFUSED 127.0.0.1:29170), the canvas isn’t running — start it with pnpm dev in the DesignJS repo.

/mcp shows designjs · ✘ failed or tool calls error with 'bridge disconnected'

The MCP server started but can’t reach the canvas. In a separate terminal inside the DesignJS repo, run pnpm dev and wait for it to report both http://localhost:3000 and the bridge on 127.0.0.1:29170. Then retry the prompt — the server reconnects automatically.

The agent used a different design MCP (Pencil, Paper, Figma) instead of DesignJS

You have competing design MCP servers registered globally (e.g. in ~/.claude.json’s user-scope mcpServers). They stay active across all projects, and when an agent sees multiple tools that can do the same job it picks somewhat arbitrarily.

Options:

• Use the CLAUDE.md that create-designjs drops — it explicitly tells the agent to prefer DesignJS and not fall back.
• Temporarily remove competing entries from ~/.claude.json’s mcpServers block.
• Restate the constraint in your prompt: “Use the designjs MCP for this, not pencil or paper.”

A previous OpenCanvas entry keeps showing as failed

Before the rebrand to DesignJS, a stale opencanvas MCP server may sit in ~/.claude.json’s user-scope mcpServers block and fail to reconnect on every launch. Open the file and delete that entry — the scope key (opencanvas) and its full object value. Restart Claude Code and it stops retrying.

Supported IDEs

IDE	Scaffold (new)	Manual (existing)	User-scope option
Claude Code	npm create designjs@latest	.mcp.json	claude mcp add --scope user
Cursor	npm create designjs@latest + move file to .cursor/mcp.json	.cursor/mcp.json	— (project scope only)
VS Code (Copilot / Continue)	npm create designjs@latest + move file to .vscode/mcp.json	.vscode/mcp.json	— (project scope only)