CAD2026Codex-mcp — a stability-first MCP gateway for AutoCAD 2026

Stability-first MCP gateway: lets Codex (or any MCP host) drive a local, writable AutoCAD 2026 through a small set of curated, policy-guarded, precision-first tools.

Windows 10/11 x64 · AutoCAD 2026 (full version) · Python 3.11 / 3.12 · MCP Gateway · MIT License

This repository publishes the CAD Super MCP gateway so that users can plug a local, writable AutoCAD 2026 straight into Codex. Codex registration name: codex-CADmcp.

This is an MCP gateway, not several open-source projects crudely merged into one process. The goal is to keep the strongest, most stable capability of each backend while isolating dependencies, reducing tool conflicts and keeping high-risk operations under control — so the model draws accurately and collaborates like a human.

What this release (0.2) brings

Measured on the author's machine with AutoCAD not running (process/handshake/protocol overhead only, no real COM work): single call p50 0.74 s → 3 ms; cad_health cold start 8.4 s → 1.0 s, warm call 5.6 s → 15 ms; discovery when the official MCP is absent 59.5 s → under 1 s. See Known limitations and what still needs a real-machine pass.

Related MCP server: AutoCAD MCP Ultra

Table of contents

• Quick start

• Fusion principles and architecture

• System requirements

• Installation

• AutoCAD-side setup

• Run the doctor first

• Connect Codex

• Usage guide

• Tools exposed by the gateway

• Stability and safety policy

• Configuration reference

• Smoke test

• Upstream versions and compatibility

• ChatGPT desktop and the HTTP mode

• Known limitations and what still needs a real-machine pass

• Changelog

• Uninstall

• Upstream projects and licenses

• Verification status and disclaimer

Quick start

Target environment: Windows 10/11 + AutoCAD 2026 (full version) + Python 3.11/3.12 + Codex.

1. Download the ZIP from this repository (or git clone) into a simple path, e.g. C:\Tools\CAD-Super-MCP (do not put it inside a OneDrive-synced folder).

2. Double-click INSTALL.cmd: it creates 3 isolated virtual environments and generates the config (options in Installation).

3. Start AutoCAD 2026 and create/save a test DWG copy from acadiso.dwt or your own template.

4. Optional: if the Autodesk Assistant offers the AutoCAD MCP Tech Preview, run MCPHTTPSTART on the AutoCAD command line.

5. Optional: if you need the raw fallback, build the felix plugin with INSTALL.cmd -WithFelix and NETLOAD it inside AutoCAD; raw stays disabled by default.

6. Double-click DOCTOR.cmd. Do not continue until essential_ready is true.

7. Double-click REGISTER-CODEX.cmd: it first backs up your existing %USERPROFILE%\.codex\config.toml, then appends codex-CADmcp.

8. Fully quit and reopen Codex, type /mcp, and confirm codex-CADmcp is connected.

9. The first run should be the Smoke test on the test DWG only.

10. Drop the working rules for Codex into your project's AGENTS.md and Codex behaves much more like a meticulous drafter.

Important

• Geometry writes are never silently retried across backends — this is a deliberate stability decision.

• cad_raw_command / cad_eval_lisp are disabled by default.

• Delete, CADPlan Execute, Save/Export and other high-risk actions are re-checked and policy-controlled by the gateway.

• AutoCAD and MCP/Codex must run as the same Windows user at the same privilege level.

• Copy important drawings before working on them.

Fusion principles and architecture

Why the environments must be isolated

best-cad-mcp currently depends on MCP Python SDK 2.x, while Slacker is explicitly pinned to SDK 1.x (<2). Installing them into one Python environment creates dependency conflicts. This package therefore creates:

• .venv-gateway: the gateway / MCP SDK 2.x

• .venv-best: best-cad-mcp

• .venv-slacker: Slacker

The gateway uses the MCP SDK 2.x client, which can negotiate with both old and new protocol backends, so it can call all of them at runtime. For the SDK 1.x Slacker, protocol=legacy is used by default to skip the doomed server/discover probe.

Architecture

Codex / MCP Host
       |
       v
CAD Super MCP (MCP SDK 2.x)
   tool layer (server) -> ops layer (ops: point specs / read-back verification / staging / undo / batch) -> Router (policy choke point)
       |                                                            allow-lists · confirm gates · interlock · audit
       +-- best-cad-mcp (own venv, SDK 2.x, persistent session)
       |      drawing understanding / CADPlan / validation / vision / image-to-CAD / advanced CAD / geometry read-back
       |
       +-- Slacker AutoCAD MCP (own venv, SDK 1.x, persistent session)
       |      structured COM queries and common writes / precise handle edits
       |
       +-- Autodesk Official AutoCAD MCP (localhost:5001-5050/mcp)
       |      official Schema / Query / Aggregate / Canvas / Compliance
       |
       +-- felix .NET MCP (localhost:7410)
       |      raw command / AutoLISP fallback, disabled by default
       |
       +-- Autodesk Product Help MCP (remote HTTPS)
              official documentation search

Routing policy

• Common structured writes → Slacker only (a stable mm/degree boundary).

• Advanced / semantic / planning / vision → best-cad-mcp; best coordinates are drawing units (the gateway converts automatically for cad_text rotation/alignment).

• Official reads / analysis → the Autodesk official MCP.

• Documentation → Product Help.

• Raw commands / LISP → felix, only when explicitly enabled and confirmed.

• Each entrance can only reach its own tool set (e.g. cad_edit cannot reach execute_cad_plan); this mapping lives in cad_super_mcp/policy.py and a test compares it against the real upstream tool inventories.

Failure policy

• Backends use persistent sessions by default (session_mode: auto): they are recycled and rebuilt on error, timeout, 15 minutes of idleness or after 500 calls; a read-only call is retried once when a session breaks, a write is never retried automatically (an uncertain result is reported as uncertain). Set session_mode: per_call for the old behaviour.

• All CAD-related calls are serialised, and mutually excluded across every gateway process on the machine (see Stability and safety policy).

• Fallback happens only for clearly safe read-only/visual capabilities; geometry writes are never silently retried across backends, avoiding duplicated or mis-scaled geometry when schemas/units differ.

System requirements

Required:

1. Windows 10/11 x64

2. AutoCAD 2026 (full version, not LT), properly licensed

3. Python 3.11 or 3.12 x64 (the installer tries, in order: the -Python argument, the CAD_SUPER_PYTHON environment variable, the py launcher, python on PATH, a uv-managed Python; the Microsoft Store python.exe stub is skipped automatically)

4. Access to PyPI / GitHub during the first install

5. AutoCAD and Codex/the gateway using the same Windows user at the same privilege level; do not run one "as administrator" and the other normally

Optional:

• .NET 8 SDK: to build the felix AutoCAD 2026 plugin (-WithFelix)

• Autodesk Assistant Tech Preview: for the Autodesk official AutoCAD MCP

Installation

1. Get the source

Download the ZIP from this repository (or git clone) into a simple path, e.g.:

C:\Tools\CAD-Super-MCP

Do not put it inside a OneDrive-synced folder.

2. Open PowerShell

A normal PowerShell is fine; administrator is not required. Enter the directory:

cd C:\Tools\CAD-Super-MCP

If your PowerShell does not allow scripts, unblock it for the current window only:

Set-ExecutionPolicy -Scope Process Bypass

3. One-command install

Easiest: double-click in the repository root:

INSTALL.cmd

Or run in PowerShell:

.\scripts\install.ps1

The default CAD workspace is:

%USERPROFILE%\Documents\CAD-Super-Workspace

Common options:

.\scripts\install.ps1 -Workspace "D:\CAD\Workspace"      # custom workspace
.\scripts\install.ps1 -Python "C:\Python312\python.exe"  # pick an interpreter (uv-managed Pythons are found automatically, usually unnecessary)
.\scripts\install.ps1 -SlackerRef "<tag or commit>"      # pin the Slacker version (defaults to main)
.\scripts\install.ps1 -WithFelix                         # also build the felix raw plugin (not installed by default)

The installer creates the 3 isolated environments, installs the gateway, best-cad-mcp and Slacker, and generates:

%USERPROFILE%\.cad-super-mcp\config.json       # configuration
%USERPROFILE%\.cad-super-mcp\install-lock.txt  # the exact version of every package actually installed (reproducible, traceable)

AutoCAD-side setup

A. Basics

Start AutoCAD 2026 first and open a test DWG copy. On the very first run, do not work on your only production drawing.

B. Autodesk official MCP (recommended, but not a hard dependency)

If your AutoCAD 2026 / Autodesk Assistant offers the MCP Tech Preview:

1. Open the Autodesk Assistant

2. Open the Tech Preview

3. On the AutoCAD command line, run:

MCPHTTPSTART

Autodesk picks a local port in 5001-5050, for example:

http://localhost:5001/mcp

You never fill in the port by hand. CAD Super MCP first runs a millisecond-level TCP pre-scan and only handshakes with ports that are actually listening, to confirm it is the Autodesk AutoCAD MCP. (Windows' own CDPSvc occupies port 5040; it is detected and ignored automatically.)

Inspect the status:

MCPCONFIG

Stop it:

MCPHTTPSTOP

If your Autodesk Assistant does not offer the Tech Preview, you can skip it (set backends.official.enabled to false). The gateway's best + Slacker core still works.

C. felix .NET plugin (optional last resort)

felix is not installed by default. Loading it leaves a localhost command endpoint (http://localhost:7410/) resident inside AutoCAD, and that endpoint is independent of the gateway's raw switch — any program on the machine may reach it once the DLL is loaded. Install and load it only when you genuinely need it.

When you do:

.\scripts\install.ps1 -WithFelix

If a .NET 8 SDK is found and the build succeeds, it prints the full path of Infomatik.AutoCAD.Mcp.dll. On the AutoCAD command line:

NETLOAD

Choose that file:

Infomatik.AutoCAD.Mcp.dll

After it loads, run:

MCPSTATUS

Note: this package ships enable_raw_felix=false by default. Even with the DLL loaded, the gateway will not use send_command / eval_lisp on its own.

Only when you explicitly want the last resort, enable it (this flips both the raw switch and the felix backend):

.\scripts\enable-felix-raw.ps1

Disable it:

.\scripts\enable-felix-raw.ps1 -Disable

Once enabled, raw calls still require confirm=true and must pass the gateway's checks:

• Commands: the first command must be on the allow-list (common draw/edit/layer/view commands), and every token is scanned against a deny-list of commands that load code, start programs, write files, close drawings or quit AutoCAD (NETLOAD, APPLOAD, SHELL, SCRIPT, SAVEAS, QUIT, ... no matter whether they are written _.NETLOAD, '_.SHELL or with another prefix); add extra commands explicitly in safety.raw_extra_commands (which can never override the dangerous-command list).

• AutoLISP: the expression is lexically parsed; the symbol in every function position must be allow-listed; command, eval, read, apply, startapp, file/registry/COM (vla-*/vlax-*) and friends are rejected, and setvar only accepts a handful of safe variables.

Note: this is still a "seat belt", not a sandbox. Enabling raw is the same as letting the model run AutoCAD commands / AutoLISP: use it on a test DWG only and review every call by hand. Editing config.json requires fully restarting Codex to take effect (the gateway reads config only at startup).

Run the doctor first

Make sure AutoCAD is running with an active drawing, then the simplest is to double-click:

DOCTOR.cmd

Or in PowerShell:

.\scripts\doctor.ps1

The doctor will:

1. list every backend (online, tool count, protocol version);

2. check the contract: whether the key tools the gateway depends on still exist, and whether upstream still accepts every parameter the gateway sends (Slacker's schema is strict — a renamed parameter fails even if the tool name survives);

3. live check: actually call best.check_runtime_environment(check_autocad=true) and Slacker autocad_status; on failure it prints the upstream remediation directly.

Output looks like:

  [OK  ] best          tools=210 protocol=2026-07-28
  [OK  ] slacker       tools=29 protocol=2025-11-25
  [--  ] official      Backend 'official' is disabled
  [OK  ] contract best tool & parameter contracts match upstream
  [FAIL] live slacker_autocad  AUTOCAD_NOT_RUNNING ...
         -> Start AutoCAD 2026 first and open a drawing

  essential_ready = false   (must be true to proceed; fix the FAIL items above first)

The important line is essential_ready = true. official and felix showing -- only means not enabled / not running and does not affect the core; product_help needs the network.

Additional options: --json (also print the full JSON report), --tools (include the full tool inventories in the JSON), --snapshot PATH (write the upstream tool-name snapshot used by the contract tests).

Connect Codex

This is currently the smoothest entrance for a local, writable AutoCAD.

Easiest: double-click in the repository root:

REGISTER-CODEX.cmd

It backs up your existing %USERPROFILE%\.codex\config.toml before touching it, then only appends the codex-CADmcp entry without overwriting your other Codex configuration. Paths containing single quotes (e.g. C:\Users\O'Brien) are escaped correctly.

• If an entry with the same name already exists it is left alone; after moving the installation, use REGISTER-CODEX.cmd -Force to regenerate (only the section this script creates is replaced).

• If the CODEX_HOME environment variable is set, the script writes the config.toml under that directory.

If you only want to look at the config without modifying anything:

.\scripts\print-codex-config.ps1

Sample output (see also examples/codex-config.toml):

[mcp_servers.codex-CADmcp]
command = 'C:\Tools\CAD-Super-MCP\.venv-gateway\Scripts\cad-super-mcp.exe'
enabled = true
startup_timeout_sec = 30
tool_timeout_sec = 240
default_tools_approval_mode = "writes"

[mcp_servers.codex-CADmcp.env]
CAD_SUPER_CONFIG = 'C:\Users\your-user\.cad-super-mcp\config.json'

default_tools_approval_mode = "writes" means Codex asks for approval whenever a tool is not marked read-only. The gateway marks the 18 read-only tools (cad_context, cad_measure, cad_plan_check, cad_stage_view, cad_verify, ...) as read-only, so "looking" and "checking" never interrupt you — only real drawing calls need your nod.

Paste it into:

%USERPROFILE%\.codex\config.toml

Then fully restart Codex.

Inside Codex, type:

/mcp

and you should see:

codex-CADmcp

Other MCP clients (generic stdio config)

The gateway is a standard stdio MCP server and can also plug into Claude Desktop / Claude Code / Cursor etc. Generic form:

{
  "mcpServers": {
    "codex-CADmcp": {
      "command": "C:\\Tools\\CAD-Super-MCP\\.venv-gateway\\Scripts\\cad-super-mcp.exe",
      "env": { "CAD_SUPER_CONFIG": "C:\\Users\\your-user\\.cad-super-mcp\\config.json" }
    }
  }
}

Every host/session starts its own gateway process; they mutually exclude each other through the workspace's .cad_super\cad.lock and will not drive AutoCAD simultaneously. But do not let several different MCP services (e.g. another AutoCAD MCP) write to the same AutoCAD at the same time — they do not honour this lock.

Usage guide

Recommended order of use

Read-only inspection

cad_health
→ cad_context (confirm the drawing, units, layers; add pin=true if the user may switch drawings)
→ cad_scan / cad_query_entities
→ cad_explain_entity / cad_measure

Regular safe writes (recommended)

cad_context
→ cad_line / cad_rect / cad_circle / cad_wall / cad_text / cad_dimension (use point specs; read-back verification is on by default)
→ look at data.verification.verified and the summary
→ cad_verify

Show me first, then commit (staging flow)

any drawing tool with stage=true      → draws onto the bright staging layer _AI_STAGE
→ cad_stage_view(action="preview")    → a screenshot right in front of you
→ you say "good": cad_stage(action="commit")   /   "no": cad_stage(action="discard")

The regret pill

cad_undo                  → previews exactly what would be undone
→ after you agree, cad_undo(confirm=true)
a whole cad_batch         → cad_undo(scope="group", group="b1", confirm=true)

Complex mechanical drawings / bulk edits

cad_recommend_tools
→ cad_scan
→ CAD-IR / semantic analysis (cad_understand)
→ cad_plan_check(action="validate")
→ cad_plan_check(action="dry_run")
→ user confirmation
→ cad_plan(action="execute", confirm=true)
→ cad_verify

Cross-checking with official data

cad_official(discoverAutoCADTypes)
→ cad_official(queryAutoCADObjects)
→ make the change
→ cad_official(queryAutoCADObjects) to confirm again

When an API/command is uncertain

cad_docs(search_help_content)

Prefer the current official Autodesk help over letting the model guess the 2026 API.

Point specs (no coordinate arithmetic)

Every parameter that accepts a "point" (start_mm, center_mm, vertices_mm, corner, at, each point of centerline, ...) can use any form below. Lengths may be plain numbers (millimetres) or unit-suffixed strings: "3600", "3.6m", "360cm", "12in", "2'6\"".

For example, "draw a 1.2 m round table 900 above the middle of the west wall":

{"tool": "cad_circle", "center_mm": {"name": "west wall", "snap": "mid", "dy": 900}, "diameter_mm": "1.2m", "layer": "A-FURN"}

Entity geometry is read fresh from AutoCAD (the cache is never trusted) and units are converted automatically; after a write, the entity is read back and compared with what was requested (default tolerance 0.01 mm).

Working rules for Codex (AGENTS.md template)

The MCP server ships its own working rules (the instructions), but hosts display them inconsistently. Putting the block below into your project's AGENTS.md (which Codex reads natively) is the most reliable way:

# CAD drafting rules (codex-CADmcp)

You are a meticulous interior/architectural drafter working on AutoCAD 2026 through codex-CADmcp.
1. Start with `cad_context`: confirm AutoCAD is online, the drawing name, units, layers. If the units are not millimetres, or are unset, tell me before doing anything.
2. Lengths are always millimetres (or unit-suffixed strings); never compute coordinates yourself - use point specs (relative / polar / midpoint / snaps / intersections).
3. Draw only onto existing, standard layers; if a layer is missing, ask me first - do not create it on your own.
4. After every write, look at `data.verification`: if `verified` is false or null, tell me honestly - never say "done".
5. When unsure, or when many entities are affected, draw with `stage=true` onto the staging layer first, show me `cad_stage_view(preview)`, and only `commit` after I agree.
6. On `NEEDS_CLARIFICATION`: relay `details.options` / `question` to me; do not guess.
7. Use `cad_batch` for multi-step work; undo with `cad_undo` (preview first, then `confirm=true` after I agree).
8. Delete, save, export and CADPlan execute only after I explicitly ask, and with `confirm=true`; never save automatically.
9. Report format: what was done (layer/size/handle) → verification result → suggested next step.

Suggested prompts

Tools exposed by the gateway

44 tools: 18 read-only tools, 26 write tools. All tools answer with the same envelope (ok / summary / data / warnings / error / meta); screenshots come back as native images; oversized output is trimmed structurally with a hint to narrow the scope.

Stability and safety policy

1. Every CAD call enters AutoCAD serially and is mutually excluded across processes: an async lock inside the process plus a file lock at .cad_super\cad.lock in the workspace — when Codex, Claude and other hosts each start a gateway, they still never drive AutoCAD at the same time; if the holder crashes the OS releases the lock automatically, so a dead gateway can never wedge the others. The networked-only Product Help does not take this lock. A lock timeout reports the holder's PID.

2. Handle-first: scan and confirm handles on the existing drawing before editing anything.

3. Read-back verification after writes: every drawing write reads the entity back and compares it by default (data.verification: verified / max_deviation_mm / per-item checks); when read-back is unavailable it is reported as "unverified" rather than pretending success. cad_verify = rescan + geometry validation + screenshot; deep=true also rebuilds CAD-IR, dimension bindings and constraint checks — the whole check runs under one lock.

4. CADPlan Execute is transaction-protected and has exactly one entrance: execute_cad_plan can only be reached through cad_plan(action="execute"); whatever the caller sends, the Router forces allow_modify=true + transactional=true + rollback_on_error=true + rollback_on_high_severity_validation=true + validate_after_plan=true + rescan_after_plan=true at the single choke point. The tool enums of cad_edit / cad_draw / cad_annotate do not contain it at all.

5. Deletes need confirmation by default: erase_entity requires it, and the confirm check happens before any backend I/O.

6. Save is a stand-alone action: confirm=true by default, so an agent can never silently save after editing.

7. raw is disabled by default: felix exists only as the last resort; once enabled it is allow-list + confirm (see the felix section).

8. Drawing pinning: after cad_context(pin=true), if the active drawing is swapped, writes are refused (DRAWING_CHANGED) — "scanning drawing A but writing drawing B" cannot happen; switching deliberately via cad_document(open/new) updates the pin automatically.

9. It does not quietly change your state: best's drawing/annotation tools like to make the target layer "current"; the Router reads CLAYER before the call and restores it afterwards (even on failure).

10. Honest results: a backend reporting failure inside a "successful" response ({"ok": false}, including the SDK-wrapped {"result": {...}} shape) is recognised as a failure, with a stable error code (AUTOCAD_NOT_RUNNING, AUTOCAD_BUSY, TIMEOUT, CONFIRM_REQUIRED, NEEDS_CLARIFICATION, DRAWING_CHANGED, ...) and a next-step hint; a backend crash/timeout no longer surfaces as ExceptionGroup: unhandled errors in a TaskGroup but as the real cause.

11. Audit log: written by default to:

    <workspace>\.cad_super\audit.jsonl

    Every call carries call_id, risk, elapsed_ms, outcome (including "cancelled, outcome unknown"); large arguments are recorded as size + hash only; the file rotates by size; and a failed audit write never turns a successful write into an error (which would invite duplicate retries).

12. Upstream dependency isolation: best and Slacker do not share a Python environment.

13. Only safe degradations: read-only feedback such as vision/screenshots may fall back from best to a Slacker screenshot; geometry writes are never silently retried across backends. Slacker and best have different parameter shapes and unit contracts — an automatic retry could duplicate entities or mis-scale them — so when the write backend is unavailable the gateway errors out instead.

14. HTTP mode binds to localhost by default: binding a non-loopback address is refused (unless --allow-remote is given explicitly, and that endpoint has no authentication).

Note: confirm=true is a call parameter that prevents accidental activation; it is not the same as human approval. Real human approval is performed by the MCP host (e.g. Codex's default_tools_approval_mode = "writes").

Configuration reference

Config file: %USERPROFILE%\.cad-super-mcp\config.json (the CAD_SUPER_CONFIG environment variable may point elsewhere). A config generated by v0.1 keeps working unchanged; a misspelled key produces a clear error listing the available keys. A full example lives in config.example.json.

backends.<best|slacker|official|felix|product_help>

safety

runtime

Smoke test

This test must run on your own Windows + AutoCAD 2026; an environment without AutoCAD cannot simulate a real Autodesk COM session. Do it on a test DWG copy only.

1. Basic connectivity

• AutoCAD 2026 is running.

• An active test DWG is open.

• DOCTOR.cmd has been run.

• essential_ready should be true.

2. Codex read-only loop

After /mcp shows codex-CADmcp in Codex, test in order:

1. cad_health

2. cad_context

3. cad_list_layers

4. cad_scan

5. cad_verify(render=true, deep=false) (you should see an image directly)

3. Exact mm writes and read-back verification

In an empty test drawing (first cad_layer(action="create", name="TEST")):

• cad_line(start_mm=[0,0], end_mm=[100,0], layer="TEST")

• cad_circle(center_mm=[50,30], radius_mm=10, layer="TEST")

• cad_arc(center_mm=[50,30], radius_mm=20, start_angle_deg=0, end_angle_deg=180, layer="TEST")

• cad_polyline(vertices_mm=[[0,0],[100,0],[100,60],[0,60]], closed=true, layer="TEST")

• cad_rect(corner=[0,0], width="3.6m", height=2400, layer="TEST")

Every one of them should return data.verification.verified = true. Then:

• use cad_query_entities to get handles;

• run cad_copy on one test entity;

• run cad_verify(deep=true).

4. Point specs and measurement

• cad_circle(center_mm={"handle": "<line handle>", "snap": "mid", "dy": 900}, diameter_mm="1.2m", layer="TEST"): the centre should sit exactly 900 above the midpoint of that line.

• cad_measure(kind="entity", handle="<line handle>"): the returned endpoints should match what you drew.

5. Stage → preview → commit / discard / undo

• Any drawing tool with stage=true: the entity should appear on the bright layer _AI_STAGE.

• cad_stage_view(action="preview"): should return a screenshot.

• cad_stage(action="commit"): the entities move to layer TEST; or discard: they are erased.

• cad_undo (preview first, then confirm=true): only undoes entities the gateway itself drew.

• Set the current layer to 0 in AutoCAD, then have Codex draw a rectangle onto layer TEST with cad_draw(tool="draw_rectangle", ...): afterwards your current layer should still be 0 (current-layer protection).

6. Delete and save protection

• cad_erase(handle=..., confirm=false) should be refused (CONFIRM_REQUIRED).

• cad_erase(handle=..., confirm=true) goes through.

• cad_save(..., confirm=false) should be refused.

7. CADPlan protection

For a small plan:

1. cad_plan_check(action="validate")

2. cad_plan_check(action="dry_run")

3. cad_plan(action="execute", confirm=true)

4. cad_verify(deep=true)

The gateway forces the transaction, rollback-on-error, rollback-on-high-severity-validation, validate-after and rescan-after parameters to true.

8. Official MCP (optional)

After running MCPHTTPSTART inside AutoCAD:

• cad_health should show the official backend online;

• call cad_official(tool="discoverAutoCADTypes", ...) or the official query tool for cross-validation.

9. felix (optional)

Enable it only when neither the structured tools nor best can cover the need. Do not enable raw by default.

Acceptance by prompt

If you prefer to run through it in natural language inside Codex, send these in order:

Read-only first:

Using codex-CADmcp, check the backend health, read the current drawing info and scan the current test DWG; do not modify anything. Tell me the active drawing, INSUNITS, layers and entity count.

Then a structured write:

Only in the current test DWG, create a line from [0,0] to [100,0] mm with cad_line, then a circle at [50,30] mm with radius 10 mm using cad_circle. Afterwards run cad_verify(deep=true) and tell me the read-back verification result for both. Do not save the drawing; wait for my confirmation.

Finally, the save boundary:

Tell me how you would save, but do not call cad_save until I explicitly confirm.

Upstream versions and compatibility

• best-cad-mcp is pinned to 1.7.0 by the installer, so a single upgrade cannot silently change a large tool surface.

• Slacker currently has no release tag this package relies on, so the installer pulls from its GitHub main by default (pin it with -SlackerRef <tag or commit>); the exact version of every package is recorded into install-lock.txt. The doctor verifies the key tool inventory this gateway depends on, and the parameter names it sends — if upstream ever makes a breaking change, the doctor fails instead of letting you believe it is "ready"; the test suite additionally keeps a snapshot of upstream tool names (tests/data/upstream_tools.json), and any allow-list drift fails CI immediately.

• The gateway itself uses MCP Python SDK >=2,<3; best and Slacker live in separate venvs so MCP 2.x / 1.x dependencies cannot shadow each other. The MCP SDK 2.x client negotiates with older-protocol backends.

• felix is an optional fallback; even after a successful source build enable_raw_felix=false stays the default.

This package does not claim to replace human engineering review of AutoCAD output. After the first install, verify units, layers, dimension styles, fonts and plot settings on a test DWG copy before deciding to use it on important drawings.

ChatGPT desktop and the HTTP mode

If you are on an individual Plus plan with the ChatGPT desktop app: do not treat "the ChatGPT desktop app itself" as a local writable MCP host. The full writable MCP beta in ChatGPT currently targets Business / Enterprise / Edu, and custom MCP connections point at remote endpoints; local MCP requires a Secure MCP Tunnel. For direct execution on a local AutoCAD 2026 today, the smoothest entrance is still Codex → CAD Super MCP → AutoCAD.

This gateway also speaks local Streamable HTTP:

.\scripts\start-http.ps1 -Port 8765

at:

http://127.0.0.1:8765/mcp

It binds to loopback by default (the SDK automatically enables Host/Origin validation for loopback to prevent DNS rebinding); binding another address is refused unless --allow-remote is given explicitly — and that endpoint has no authentication, so it should only sit behind a trusted tunnel. This exists so a supported secure tunnel/remote access can be added later; never expose this port to the open internet.

Known limitations and what still needs a real-machine pass

The 0.2 features were verified against "a fake AutoCAD + the real best/Slacker backend processes (AutoCAD not running)" and have not yet been checked item by item against a live AutoCAD 2026. Run the Smoke test on a test DWG; the following deserve particular attention:

• Read-back verification depends on the shape of best's get_entity_properties response (implemented from its source, parsed per entity type). If your best version answers differently, the result is shown as "could not verify by read-back" (verified: null) — it never falsely reports success.

• cad_text rotation/alignment goes through best (Slacker has neither), using draw_text + set_text_alignment; the tool adds a warning and suggests a stage=true preview first. Unrotated, left-aligned text goes through Slacker and is verified.

• Polylines are drawn by Slacker as lightweight 2D polylines; z is ignored and read-back verification compares 2D vertices.

• Layer lineweight/linetype: neither backend offers layer-level lineweight settings; cad_layer can change colour/locked/frozen/on-off only. Use cad_edit(tool="set_entity_properties") for per-entity properties.

• cad_undo only undoes entities the gateway itself created/moved; erases, layer changes and best edits cannot be undone automatically (each is spelled out in the result), and AutoCAD's own UNDO stack is never touched.

• Persistent sessions: on error/timeout/idleness/N calls they rebuild automatically; if you ever see strange connection behaviour, switch that backend's session_mode to per_call for the v0.1 behaviour.

• Staging preview screenshots: prefer the best render, fall back to a Slacker window screenshot (the AutoCAD window must not be occluded).

• Not yet provided: human confirmation via MCP elicit (confirm is still a parameter), one-shot plan tokens after dry_run, and JSON-Schema pre-validation of arguments. These are on the roadmap.

• One AutoCAD instance: with several AutoCAD instances running, Slacker attaches to "the running one" and the official MCP takes the lowest port — they may not be the same instance.

Changelog

0.2.0

• Precision: millimetres/unit strings; point specs; gateway-local geometry (rectangles, wall outlines, dimension-line positions); read-back verification after writes; cad_measure; cad_wall cad_rect cad_dimension cad_text.

• Collaboration: cad_context, stage/preview/commit/discard, cad_undo, cad_name, cad_batch, drawing pinning, narrative summaries, NEEDS_CLARIFICATION.

• Performance: persistent backend sessions; fast official-MCP discovery (60 s → <1 s); Slacker/Product Help skip the server/discover probe; cad_health no longer goes online by default.

• Safety and correctness: execute_cad_plan has a single entrance with forced transaction protection; fixed cad_image_trace(prepare) failing; raw commands/LISP moved to allow-lists; soft failures reported honestly (including SDK-wrapped dicts); audit with call_id, complete cancellation records, and audit-write failures no longer turning into errors; cross-process interlock; best drawing no longer quietly changes the current layer; HTTP refuses non-loopback binds.

• Responses: one envelope; native images; structural trimming of oversized output; stable error codes with advice.

• Tool surface: added cad_layer, cad_document, cad_plan_check, cad_stage, cad_stage_view, cad_undo, cad_name, cad_batch; cad_draw/cad_edit/cad_annotate tool parameters became enums.

• Engineering: installer supports uv/-Python, checks every step's exit code, felix became an explicit install, records install-lock.txt; register-codex.ps1 supports -Force and TOML-safe escaping; the doctor gained parameter-contract checks and a human-readable summary; 260+ automated tests.

0.1.0: first public packaging.

Uninstall

Deleting this directory removes the 3 virtual environments and the gateway. Also delete:

%USERPROFILE%\.cad-super-mcp

and remove the [mcp_servers.codex-CADmcp] section (plus its .env section) from %USERPROFILE%\.codex\config.toml.

The default workspace lives at:

%USERPROFILE%\Documents\CAD-Super-Workspace

Whether to delete the workspace is your call — it may hold output files, screenshots, SQLite state, entity aliases (.cad_super\names.json) and the audit log.

Upstream projects and licenses

This package does not copy upstream source and bundles no third-party code; the installer installs/builds those projects on your machine:

Respect the upstream licenses and Autodesk's product/service terms individually. This project itself is released under the MIT license — see LICENSE.

Verification status and disclaimer

Performed so far:

• 260+ automated tests (pytest): policy and safety regressions (including every raw probe that historically slipped past the old regexes), Router, point specs and the geometry kernel, read-back verification, staging/undo/batch, config, the doctor, plus session-pool tests with real MCP subprocesses and end-to-end tests over the full MCP protocol (with a fake AutoCAD); ruff static checks pass.

• Contract checks against the real best-cad-mcp 1.7.0 (210 tools in its core profile) and the real Slacker (29 tools): the allow-lists and the parameter names the gateway sends match the real upstream schemas.

• Smoke runs with the real backend processes (AutoCAD not running): protocol negotiation, persistent-session reuse, error envelopes and hints, audit fields, process recycling; the PowerShell install/register scripts were exercised for real in a sandbox HOME (including a TOML round-trip).

• Key upstream tool names/protocol behaviour were cross-checked against Autodesk, best-cad-mcp, Slacker, felix and the MCP Python SDK as of 2026-09-15.

Not covered: on-site testing against real COM / DWG writes (version 0.2.0, build date 2026-09-26 — see BUILD_INFO.json). After installing, DOCTOR.cmd and the smoke test on a test DWG are the final must-do steps.