> ## 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 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.

<Info>
  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.
</Info>

<Note>
  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.
</Note>

## Method 1 — `create-designjs` scaffolder (new projects)

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

```bash theme={null}
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`**:

```bash theme={null}
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.

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

## 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:

```json theme={null}
{
  "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:

```bash theme={null}
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

<Steps>
  <Step title="Confirm the canvas is running">
    ```bash theme={null}
    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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Troubleshooting

<Accordion title="/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.
</Accordion>

<Accordion title="/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:

  ```bash theme={null}
  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.
</Accordion>

<Accordion title="/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.
</Accordion>

<Accordion title="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."*
</Accordion>

<Accordion title="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.
</Accordion>

## 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)        |