# classcad.ai

> Everything that lets AI agents build and verify CAD models with ClassCAD, the CAD engine by AWV Informatik AG. The ClassCAD MCP server gives an agent a live CAD session: it writes JavaScript programs against the ClassCAD API, runs them with `run_script`, renders the model with `snapshot`, and proves the result with mass properties and geometry probes. The MCP is self-contained: it runs the ClassCAD engine itself (WebAssembly), so there is no server to set up and no key to configure; it needs a free classcad.ch account, signed in once per machine with one click.

If a user asked you to install the ClassCAD MCP, follow "Install", "Configure the host" for the host you are running in, and then "Sign in". The install is not finished until the user is signed in: do that step yourself, right away, and do not leave it to the user. It all takes a minute or two.

## Install

Requirements: Node.js 20 or newer, and internet access on first use.

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

```bash
npx -y @classcad/mcp@latest
```

Use it exactly like that in every config below: `@latest` makes npx fetch the newest release instead of reusing an older cached one.

- No environment variables are needed. Do not install a ClassCAD server (classcad-cli): it is optional, and the MCP runs its own engine without it.
- 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. Wherever a config below runs `npx`, run `cmd` with the arguments `/c npx -y @classcad/mcp@latest` instead, in JSON `"command": "cmd", "args": ["/c", "npx", "-y", "@classcad/mcp@latest"]`. The Claude Code plugin needs no such change: it starts the server through `node` on every system.
- Only if npx cannot fetch the package at all, see "Last resort: build from source" below.

## Configure the host

No ClassCAD settings are needed. After configuring, the host has to start a new session (or be restarted) before the classcad tools appear.

Claude Code (terminal, and the Code tab of the Claude desktop app, on every system): install the ClassCAD plugin. It brings the MCP server and a ClassCAD skill that teaches the build-and-verify loop. Run the two commands one after the other (Windows PowerShell does not take `&&`):

```bash
claude plugin marketplace add awv-informatik/classcad-ai
claude plugin install classcad@classcad
```

Use the plugin, not `claude mcp add`. If `claude mcp list` shows a `classcad` server added by hand earlier, remove it with `claude mcp remove classcad --scope user`; otherwise every ClassCAD tool is there twice.

Check with `claude mcp list` (shows "Connected"). The tools appear in the next session; in a running one, `/mcp` reconnects.

Claude desktop app (Chat): edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows), then quit and reopen the app:

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

The app has no shell PATH. If it cannot start npx, use the absolute path of npx (`which npx`) as `command`; if it then cannot find node, add `"env": { "PATH": "<the folder that holds node>:/usr/bin:/bin" }` to the entry.

Codex, in `~/.codex/config.toml`:

```toml
[mcp_servers.classcad]
command = "npx"
args = ["-y", "@classcad/mcp@latest"]
```

VS Code (Copilot Chat, agent mode), in `.vscode/mcp.json` or the user MCP config:

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

Cursor, in `~/.cursor/mcp.json` (Windsurf and most other hosts take the same shape):

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

OpenCode, in `opencode.json`:

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

## Sign in (the last install step, once per machine)

The MCP works with a free classcad.ch account. Start the sign-in yourself, straight after configuring the host, always from a terminal:

```bash
npx -y @classcad/mcp@latest login
```

Do not call the classcad tools in the session that installed them: a session only loads MCP servers when it starts, so the new server is not reachable there yet (tools that seem to be listed may be stale). The command keeps running until the user has signed in (up to 15 minutes), so start it in the background and read its output.

It opens the sign-in page in the user's browser (Google, GitHub or email; one click if they already have an account) and prints the same link. When the command prints "signed in as …", the install is done.

Tell the user, in plain words and without talking about servers, sessions or the CLI:

1. ClassCAD is installed.
2. A sign-in page has opened in their browser. Give the link it printed as a clickable link on its own line, in case the tab is hidden.
3. Once they have signed in, they should start a new chat (or restart the app) and ask for a part, e.g. "make a box".

Later, if any ClassCAD call answers "Sign-in required", the sign-in page opens by itself: show the user the link from that answer and call `login`, which waits until they are done.

## First test

In a new session, ask for a box (if the sign-in was skipped, it comes first). The agent calls `run_script` and reports a volume. `session_info` should show `"transport": "wasm"`. The first call takes a few seconds longer because the engine (about 16 MB) is downloaded once, into `~/.classcad-mcp/wasm/`. After that, the engine starts in about a second and works offline.

## Plans

The account's plan decides what the MCP may do (https://classcad.ch/subscriptions). A new account has two weeks of Solo, then continues on Free unless the user chooses a plan.

- Free: local use, private and for evaluation: modelling with every tool, STL export, and the app on this machine.
- Solo, and the first two weeks: commercial work, STEP and OFB export, and live sharing with two guests.
- Pro and Business: every export format, live sharing with sixteen guests, and public use in the user's own web apps (one domain per seat with Pro, any number with Business); Business also runs ClassCAD on its own servers: the WebAssembly engine self-hosted, and the native engine.

When a call needs another plan, its answer says so and names the plans page: pass that on to the user as it is.

## Troubleshooting

- The tools don't appear: the host only loads MCP servers when a session starts. Start a new session or restart the host.
- "npx: command not found" or "node: command not found" in the Claude desktop app: use the absolute path of npx, and the PATH entry described under the app's config.
- Update: nothing to do. `@latest` fetches the newest release whenever the host starts the server; start a new session to pick it up.
- Status of the shared background process: `npx -y @classcad/mcp@latest status`.
- Details on every setting: https://github.com/awv-informatik/classcad-ai/blob/master/packages/mcp/README.md

## Last resort: build from source

Only when npx cannot fetch the package on this machine (for example, the npm registry is blocked). Choose a lasting location (for example `~/classcad-ai`, not a temp folder), because the host runs the server from there:

```bash
git clone https://github.com/awv-informatik/classcad-ai.git
cd classcad-ai
npm install
npm run build
```

Then, in every config above, replace `npx -y @classcad/mcp@latest` with `node /abs/path/to/server.js`, where the path is the checkout's `packages/mcp/dist/server.js` (from the repo root, `echo "$PWD/packages/mcp/dist/server.js"` prints it). The terminal commands become `node /abs/path/to/server.js login` and `... status`. To update later: `git pull && npm install && npm run build`.

## Using it

The MCP's own instructions tell the agent how to work: plan the build, fetch the method docs and recipes in one `docs` call, build with a few `run_script` programs, and always verify (mass properties plus `snapshot` renders).

- [MCP README](https://github.com/awv-informatik/classcad-ai/blob/master/packages/mcp/README.md): tools, engines, sessions, and joining a ClassCAD app by invite link
- [Recipes](https://github.com/awv-informatik/classcad-ai/tree/master/packages/skill/recipes): constrained sketching, verification, parametric parts, assembly parameters, patterns, direct modelling
- [ClassCAD documentation](https://classcad.ch/docs/)

## Contact

- Email: info@awv-informatik.ch
- Discord: https://discord.gg/MEbR7xyPMS
- GitHub: https://github.com/awv-informatik/classcad-ai
- AWV Informatik AG: https://awv-informatik.ch/