ClassCAD

@classcad/mcp

Model Context Protocol server for the ClassCAD CAD engine. Self-contained: it runs the ClassCAD engine itself (WASM), so there is no server to set up.

Lets MCP-capable hosts (Claude Code, the Claude desktop app, VS Code Copilot, Cursor, …) drive a live ClassCAD session: build parts and assemblies through scripts, inspect the structure tree, render snapshots, save and load STEP, STL and OFB.

The session is shared. The CAD app, Buerligons, docks into it: the user turns, selects and edits the same model the agent builds. Its link can be sent to a colleague or opened on another device (through the share relay), and the agent can also join the session of an app the user already has open.

---

How it works

 Claude tab 1 ── stdio ──► classcad-mcp (shim) ──┐

Claude tab 2 ── stdio ──► classcad-mcp (shim) ──┤ HTTP (MCP Streamable HTTP, 127.0.0.1:9097) VS Code ── stdio ──► classcad-mcp (shim) ──┘ ▼ classcad-mcp daemon (ONE per machine) session (one per host connection), its drawings (one per model): drawing d-… ── worker thread ──► ClassCAD WASM (the MCP's own engine) drawing d-… ── WebSocket ─────► ClassCAD worker (classcad-cli, optional) drawing d-… ── WebSocket ─────► a session an app shares (by invite) 127.0.0.1:9098 ◄── the app, docked into a drawing · apps that host a session of their own wss, dialled out ──► share relay (Cloudflare) ◄── the app on any other machine, by share link

• Self-contained. The MCP brings its own engine: the published ClassCAD WASM build, run in a worker thread of the daemon. No server and no key to configure: the engine's key comes with one sign-in with a free classcad.ch account. On first use it downloads the release assets (about 16 MB) once and caches them.
• Every host starts the MCP as a stdio child process (npx -y @classcad/mcp@latest). That process is a thin shim: it looks for the daemon on 127.0.0.1:9097, starts it if none runs, and forwards its host's JSON-RPC to it. The first tab starts the daemon, every later tab reuses it.
• The daemon is the actual MCP. It holds one session per host connection, and in it one MCP server instance per drawing (own engine, caches, tool queue, invites; see Drawings), and the one listener sessions are joined on (127.0.0.1:9098): the app docks into the MCP's sessions there, and apps that run the engine in their own page offer their sessions there. With no session left and no such app waiting it exits by itself after CLASSCAD_DAEMON_IDLE_MS (60 s). Nothing to install or manage: it is part of this package (dist/daemon.js) and lives only while it is used.
• Why a daemon: the MCP *listens* on a port, and a port belongs to exactly one process. With one daemon, every session's app link has the same address, and an app that looks for the MCP finds it.
• Shared with the user. Every drawing has a live CAD app, docked into the same engine: see The app. The session protocol is the one a ClassCAD server speaks, so any buerli app joins the same way: see Sharing.
• Shared beyond the machine. A session is also offered on the share relay (packages/relay, a Cloudflare Worker), so the app's link works on any machine. The MCP dials out to it; nothing on the machine listens for the outside. See Somebody elsewhere joins.
• Optional engines. If a classcad-cli worker is reachable (CLASSCAD_WS_URL, default ws://localhost:9094/), the default policy auto uses it instead of the local engine. See Engines.
• The engine is started lazily on a drawing's first tool call, so an idle session costs nothing, and a drawing that is not used gives its engine up (it sleeps, see Drawings).
• Fallback: if 127.0.0.1:9097 is held by something that is not a classcad daemon, the shim serves the MCP in-process (with a listener of its own, on a free port if 9098 is taken) and says so on stderr.

---

Prerequisites

• Node.js 20+ (node, npx)
• Internet access on first use (the package comes from npm, the engine from awvstatic.com; afterwards it works offline)
• A free classcad.ch account, signed in once per machine (Google, GitHub or email). The MCP asks for it by itself on first use; see Sign-in.

Nothing else: no ClassCAD server, no key.

---

Install

There is nothing to clone or build. Every host starts the server with one command:

npx -y @classcad/mcp@latest

@latest makes npx fetch the newest release instead of reusing a cached one; -y skips the install prompt. npx may warn that sharp's install script was not run; that is fine, sharp ships prebuilt binaries.

Windows (native, not WSL): hosts cannot start npx directly. Use cmd as the command with the arguments /c npx -y @classcad/mcp@latest, e.g. claude mcp add classcad --scope user -- cmd /c npx -y @classcad/mcp@latest, or "command": "cmd", "args": ["/c", "npx", "-y", "@classcad/mcp@latest"] in JSON configs. (The Claude Code plugin below needs no such change.)

From source, only where npm is not reachable: git clone https://github.com/awv-informatik/classcad-ai.git && cd classcad-ai && npm install && npm run build, then use node /abs/path/to/classcad-ai/packages/mcp/dist/server.js in place of the npx command (echo "$PWD/packages/mcp/dist/server.js" prints the path).

---

Configure your host

Every host needs the command above and a new session (or a restart), so it spawns the server. No environment variables are required.

Claude Code (CLI, and the Code tab of the desktop app)

The plugin brings the MCP server and a ClassCAD skill, on macOS, Linux and Windows alike:

claude plugin marketplace add awv-informatik/classcad-ai

claude plugin install classcad@classcad

Or the MCP server alone (one of the two, not both):

claude mcp add classcad --scope user -- npx -y @classcad/mcp@latest

--scope user writes to ~/.claude.json (all projects); --scope project writes .mcp.json in the current repo instead. Verify with claude mcp list — the entry should show ✔ Connected. Tools appear in the next session (each session spawns its own MCP process); in a running session use /mcp to reconnect.

Manual equivalent in ~/.claude.json / .mcp.json:

{

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

Claude desktop app (Chat / Cowork)

The chat side of the desktop app has its own config and does not read ~/.claude.json:

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

Add the same mcpServers block as above. The app runs one MCP connection for all its chats; every chat works on drawings of its own (see Drawings), so one chat never touches another's model. The app is not started from a shell, so it has no PATH: if it cannot start npx, use its absolute path as command (which npx tells you; macOS Homebrew: /opt/homebrew/bin/npx), and if it then cannot find node, add "env": { "PATH": " :/usr/bin:/bin" }. Quit and reopen the app — it spawns MCP servers only at startup. The server then shows up under Settings → Developer, and the chat renders snapshot images inline.

Codex

~/.codex/config.toml:

[mcp_servers.classcad]

command = "npx" args = ["-y", "@classcad/mcp@latest"]

VS Code — GitHub Copilot Chat (agent mode)

Command Palette → MCP: Add Server, or edit .vscode/mcp.json (workspace) / the user MCP config:

{

"servers": { "classcad": { "type": "stdio", "command": "npx", "args": ["-y", "@classcad/mcp@latest"] } } }

(Top-level key servers, and an explicit "type": "stdio".) Switch Copilot Chat to Agent mode; the classcad tools become selectable.

Cursor

~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project): the mcpServers block from the Claude Code section.

OpenCode

opencode.json:

{

"mcp": { "classcad": { "type": "local", "command": ["npx", "-y", "@classcad/mcp@latest"] } } }

Other hosts

Most hosts accept the Claude-style mcpServers JSON.

First test

In a new session, ask the agent to *make a box*. The first time, it shows a sign-in link: open it, sign in, and the agent carries on by itself. It should then call run_script and answer with a volume, and the app comes up with the box (in the desktop app's Browser pane, or in your browser); session_info with the drawing the answer named shows "transport": "wasm" (or "ws" when a worker is running). The very first call takes a little longer while the WASM assets download.

---

Drawings

Every tool that works on a model takes a drawing. The first call of a model passes "new": the MCP opens a drawing — an engine session of its own, with its own tool queue, checkpoints and app — and the answer names its id (d-k3v9q2xa). Every later call about that model passes that id. A second, unrelated model is a second drawing. docs, list_methods, describe_method, login and account take no drawing, and session_info without one answers for the MCP as a whole.

Why. Some hosts send many conversations through one connection: the Claude desktop chat app and Cowork start one MCP process for all their conversations, Cursor and VS Code one per window. Nothing in a request says which conversation sent it. With one drawing per connection, one conversation's clear or load is another one's lost model. A drawing's id is random, and only the conversation that opened it is told it, so no other conversation reaches it. A call without an id, or with one this connection does not know, is refused and changes nothing. Drawings run side by side: the scripts of two conversations do not wait for each other.

Drawings end with their session (the host's connection). To keep a model beyond that, save it (OFB keeps its features).

Idle drawings sleep. A local engine costs memory: the first one in the daemon about 850 MB, every further one about 350 MB. A drawing nobody used for CLASSCAD_DRAWING_IDLE_MS (10 minutes) gives its engine up: the drawing waits in the daemon as OFB, and its next call — or the next command of the app docked into it — starts an engine and loads it again, under the same ids and with its checkpoints. At most CLASSCAD_DRAWINGS_AWAKE (3) drawings of a connection stay awake; the least recently used one sleeps first. Waking takes a second or two. Drawings on a worker are the worker's sessions and do not sleep.

The app

Every drawing has a live CAD app: Buerligons, the buerli CAD app, docked into the drawing's own engine. The package carries a build of it and serves it itself, so there is nothing to install and it works offline.

• It comes up with the first model of a drawing and shows every change the agent makes as it happens. Where it comes up is the host's: in the Claude desktop app (Code tab) it is the app's own Browser pane, beside the conversation — the agent opens it there; everywhere else the MCP opens the user's default browser. The result of the script that makes the first model ends with the link (App: …), once per drawing: agents do not carry it into every answer. session_info names it, and view returns it and brings the app up again (unless the user already has it open: one tab per drawing is enough).
• The user works in it too. Tu