# kernelCAD

> CAD for agents: author editable .kcad.ts models, inspect and verify geometry,
> then deliver STEP, STL, drawings or a Studio link.

If the user says “look at kernelcad.com and install the mcp”, follow this guide
for the host you are running in. Reuse an existing kernelcad connection; do not
add a second plugin or MCP entry. Preserve unrelated host configuration.

## Recommended: hosted MCP

URL: https://mcp.kernelcad.com/mcp (Streamable HTTP). No local Node.js, CAD
engine or npm package is required. Anonymous use works; account features use
the host's OAuth prompt. Never ask the user to paste credentials into chat.

### Claude Code

```bash
claude mcp add --transport http --scope user kernelcad https://mcp.kernelcad.com/mcp
claude mcp list
```

For the hosted MCP plus workflow skills, use the existing plugin instead of
adding a separate MCP entry:

```bash
claude plugin marketplace add w1ne/kernelCAD-web
claude plugin install kernelcad@kernelcad
```

### Codex

```bash
codex mcp add kernelcad --url https://mcp.kernelcad.com/mcp
codex mcp list
```

For account features, run `codex mcp login kernelcad` and let the user complete
the host's OAuth flow. The optional hosted plugin and skills are documented
in the installation guide linked below.

### Cursor

Merge this entry into `~/.cursor/mcp.json` (create the file if absent):

```json
{
  "mcpServers": {
    "kernelcad": { "url": "https://mcp.kernelcad.com/mcp" }
  }
}
```

### VS Code / Copilot

```bash
code --add-mcp '{"name":"kernelcad","type":"http","url":"https://mcp.kernelcad.com/mcp"}'
```

### Claude Desktop / claude.ai and ChatGPT

Use the host's connector settings with https://mcp.kernelcad.com/mcp; the user
must complete that settings/sign-in step. Do not claim it was completed from
a terminal command. See https://app.kernelcad.com/connect for host-specific steps.

## Optional: local npm MCP and version-matched skills

Use this only when the user wants local CAD execution. Requirements:
Node.js >=22.12.0, npm >=10.0.0, and internet access for the initial package download.
No account or cloud token is needed for local stdio mode.

Resolve a published version once with `npm view kernelcad version`, then replace
`<version>` in ALL commands and config entries below with that exact version.
Do not leave the placeholder in host configuration. Pinning the same version
keeps the local server and its skills together.

Merge this entry into the host's MCP configuration (Claude Desktop or Cursor):

```json
{
  "mcpServers": {
    "kernelcad": {
      "command": "npx",
      "args": ["-y", "kernelcad@<version>", "mcp"]
    }
  }
}
```

Claude Code: `claude mcp add --transport stdio --scope user kernelcad -- npx -y kernelcad@<version> mcp`.
Codex: `codex mcp add kernelcad -- npx -y kernelcad@<version> mcp`.
On native Windows, use `cmd` with args `["/c", "npx", "-y", "kernelcad@<version>", "mcp"]`.
If a desktop host cannot find npx or node, use their absolute paths and the host's PATH configuration.
The existing `npx -y kernelcad@<version> install --help` also describes the local host installers.

The npm package includes `dist/cli/skills/kernelcad/SKILL.md` and its specialty
skills. Every packaged SKILL.md has `metadata.version` equal to the package
version; these are the docs for that local release, not the hosted server.
Install the matching SKILL.md documents into the host's skills directory:

```bash
npx -y kernelcad@<version> skill install ~/.claude/skills
```

For Codex, use `${CODEX_HOME:-$HOME/.codex}/skills` instead. For Cursor, use
`~/.cursor/skills`. For hosts without skills directories, export a context file:

```bash
npx -y kernelcad@<version> skill onefile ./kernelcad-skills.md
```

The existing installer copies SKILL.md documents, including nested skills;
supporting cookbook files stay inside the npm package at `dist/cli/skills`.

Load `kernelcad/SKILL.md` first and `kernelcad-authoring/SKILL.md` before writing
CAD source. On updates, choose the new published version and update both the
server entry and skills. The optional cross-agent skills repository is a
separate distribution; use the npm-bundled tree for local version matching.

## Verify before reporting success

1. Check the host's MCP list/configuration for exactly one kernelcad connection.
2. Start a new session or restart the host so the tools are loaded.
3. List the tools and call the read-only `lookup_api` tool with `{}`. A successful
   response proves the server is reachable and can return its runtime API.
4. For local npm mode, check the installed skill's `metadata.version` against
   the chosen package version and the server version returned by MCP initialize.

Report “configured” if only the config was written; report “connected” only
after a successful MCP call. If tools are unavailable in the installing session,
say that verification needs a new session. Stop and report the exact error if
installation fails. Do not silently switch between local and hosted execution.
A discovery call verifies connection, not CAD geometry or hardware acceptance.

## Documentation

- [Connect a host](https://app.kernelcad.com/connect): connector settings and OAuth.
- [Agent installation guide](https://github.com/w1ne/kernelCAD-web/blob/develop/docs/usage/agent-plugin-install.md): existing plugins, updates and uninstall.
- [Local CLI and MCP](https://github.com/w1ne/kernelCAD-web#readme): package usage and script workflow.
- [CAD reference](https://kernelcad.com/docs/): native kernelCAD modeling documentation.