@synkit/nexus

Drive the Nexus procedural-design tool from any AI agent that speaks MCP.

@synkit/nexus is a Model Context Protocol server. It bridges your agent (Claude Code, Claude Desktop, Cursor, any MCP client) to a Nexus editor tab running in your browser, so the agent can read the canvas, create generators, tune parameters, save snapshots — all the things you'd otherwise do by hand in the inspector.

┌──────────────┐  stdio   ┌────────────────┐   ws://127.0.0.1   ┌──────────────────┐
│  Your agent  │ <──────> │  MCP server    │ <────────────────> │  Nexus editor    │
│  (MCP host)  │          │  (this pkg)    │                    │  (browser tab)   │
└──────────────┘          └────────────────┘                    └──────────────────┘

The server is a thin router: it tells the agent what tools are available, forwards each call to the editor over a local WebSocket, and returns the result. The actual logic — every layer mutation, every snapshot, every store read — lives in the editor.

Install

You don't install anything ahead of time. Your MCP client invokes @synkit/nexus via npx, which fetches and runs the latest version on demand.

Claude Code

claude mcp add nexus -- npx @synkit/nexus

Then restart Claude Code.

Cursor

Add to ~/.cursor/mcp.json (create if missing):

{
  "mcpServers": {
    "nexus": {
      "command": "npx",
      "args": ["@synkit/nexus"]
    }
  }
}

Restart Cursor.

Codex

Add to ~/.codex/config.toml (create if missing):

[mcp_servers.nexus]
command = "npx"
args = ["@synkit/nexus"]

Fully quit and reopen the Codex app — new threads inside the same session won't pick up the config change.

Claude Desktop

Add to your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "nexus": {
      "command": "npx",
      "args": ["@synkit/nexus"]
    }
  }
}

Restart Claude Desktop.

Other MCP clients

Any client that speaks the stdio MCP transport works. Invoke npx @synkit/nexus as the server command.

Open the editor

The agent needs a Nexus tab to connect to.

1. Go to nexus.synkit.net (or your local dev build).
2. Open the MCP menu from the top bar — you'll see your agent connect once the bridge is running.

The first time an HTTPS page (nexus.synkit.net) reaches the local bridge, Chrome will show a Private Network Access prompt asking you to allow the connection. Approve it once; subsequent sessions auto-allow.

What the agent can do

| Tool | What it does | |------|--------------| | ping | Health check — confirms the editor is connected. | | get_canvas_state | Full read-only snapshot of every layer (id, type, bounds, parameters, library). | | list_generator_types | The canonical generator type strings. | | add_layer | Create a new layer (any generator or shape type). | | list_array_variant_presets | Built-in shape presets for Array generators. | | add_array_variants | Inject preset shapes into an Array's library. | | set_array_variants | Replace an Array's library wholesale with curated shapes. | | update_layer_param | Change one parameter on one layer. | | update_layer_params | Change many parameters on one layer in a single render. | | bulk_update_layers | Apply ops across many layers in a single store mutation — the fast path for grid configurations. | | duplicate_layer | Clone a layer by id. | | set_layer_bounds | Move and/or resize a layer (partial bounds OK). | | remove_layer | Delete a layer. | | save_canvas_snapshot | Save the current canvas to a named localStorage slot. | | restore_canvas_snapshot | Restore a saved snapshot as a single undo checkpoint. | | list_canvas_snapshots | Enumerate saved snapshots. | | delete_canvas_snapshot | Delete a named snapshot. | | capture_layers | Snapshot the user's current host-side selection (PS layers / Figma nodes) and hand back URL refs to the raw bytes — without touching the plugin's interactive state. The agent-batch path for "I have N layers selected, do X to them". | | write_layer | Inverse of capture_layers. Replace a specific layer's pixels (via layerId) or create a fresh one. When the descriptor carries nexusMeta (auto-supplied by render_with_generator_stack), the written layer becomes parametrically re-editable: click it in the host doc and "Store current layer" in the plugin restores the exact generator + params that produced it. Pair with capture_layers for the full "apply X to my N selected layers" round-trip. | | render_with_generator_stack | Editor middle step. Run the canvas's configured generators against an external source bitmap (typically from capture_layers), get one rendered URL per generator. Each result also returns a nexusMeta blob (generator type + params + array library) so a subsequent write_layer can stamp the layer with round-trip-editable metadata. Zero canvas mutation — agent uses the editor as a library of "looks". Pair with write_layer to land results back in the host doc. |

Each tool has a long-form description visible to the agent — you can ask "what can you do with the canvas" and it'll enumerate.

Configuration

| Env var | Default | Notes | |---------|---------|-------| | NEXUS_MCP_PORT | 7811 | Port the WebSocket bridge listens on (always bound to 127.0.0.1). | | NEXUS_MCP_ALLOWED_ORIGINS | (unset) | Comma-separated extra origins allowed to reach the bridge. Localhost + *.synkit.net are allowed by default; set this if you're hosting Nexus on a custom domain. Example: https://my-nexus.example.com,https://staging.example.com. |

Security

• Localhost-only. The bridge binds to 127.0.0.1. Random sites on the internet can't reach it. Anyone with code running on your machine who can open a localhost socket can drive your editor — but at that point they could already do anything else with your account too.
• Origin allowlist. Browser-side requests are CORS-locked to localhost, 127.0.0.1, and *.synkit.net. A drive-by site (https://evil.com) gets the preflight back without Access-Control-Allow-Origin, so the request is blocked — even if you accidentally accepted Chrome's Private Network Access prompt for that origin. Extend the list with NEXUS_MCP_ALLOWED_ORIGINS if you host Nexus elsewhere.
• No auth. The bridge has no token. If you share a screen-recording or your machine is otherwise compromised, anyone with shell access can run curl http://127.0.0.1:7811/call.
• One connection per role. Each surface (editor, PS plugin, Figma plugin) gets its own slot. Editor + plugin can be connected simultaneously — that's how cross-surface handoffs work. Within a role, opening a second connection disconnects the first.
• You control sessions. The Nexus editor has a Disconnect button in the MCP menu — it closes the WebSocket and refuses to reconnect until you click Resume. Use this if you want to step away with the editor open but no agent attached.

Development

If you're hacking on the server itself (rather than just using it):

git clone https://github.com/SynkitNET/nexus.git
cd nexus/mcp
npm install
npm run dev          # tsx watch + stdio
npm run bridge       # bridge only, no MCP stdio — for curl/wscat
npm run typecheck    # tsc --noEmit
npm run build        # tsup → ./dist

The Nexus-side handlers live in src/lib/agentic/tool-registry.ts (in the main repo). Add a handler there, add a catalog entry in mcp/src/index.ts, done.

License

MIT