Save/export, five methods and MCP tools, formats, completion and errors
MCP integration
What MCP connects
The supplied JDesignCAD.Mcp.exe exposes 36 tools to an MCP-capable AI client. The client starts it over stdio. The server connects to a running CAD window through a same-Windows-user named pipe; it opens no TCP listening port. It does not provide a CAD engine or open a target drawing automatically.
Free can use MCP. Sheet-metal and analysis operations require active STD/Pro permissions, including when called through MCP. The Free restriction on loading custom ribbon DLLs does not disable the MCP server.
Register the server
- Install the complete JDesignCAD 1.1.3 package. Check that Customization\Mcp\JDesignCAD.Mcp.exe and its accompanying files exist.
- Open your AI client's MCP server configuration. Use the executable path in the example, changing it if CAD was installed elsewhere.
- Restart or reconnect the MCP client as required by that client.
- Start JDesignCAD as the same Windows user and open a test drawing in model space.
- Ask the client to list CAD sessions and select the intended window explicitly.
{
"mcpServers": {
"jdesigncad": {
"command": "C:\\Program Files\\JDesignCADV1\\Customization\\Mcp\\JDesignCAD.Mcp.exe",
"args": []
}
}
}The supplied Customization\mcp-config.json is a configuration example. The surrounding configuration file and setup UI depend on the MCP client. Keep the complete Mcp directory together. Do not run only the executable copied away from its DLLs. No special network endpoint or API token is required by this local bridge.
Inspect before editing
- cad_list_sessions returns candidate windows. Choose sessionId explicitly; do not assume the first result is correct.
- cad_get_document returns documentId, revision, object count and Undo/Redo state.
- cad_get_capabilities returns registered operation names, execution modes and license availability.
- cad_get_operation_schema returns exact JSON parameters for an operation.
- For an edit, create a new UUID operationId and use the latest document ID and expectedRevision.
Coordinates and lengths are WCS millimetres regardless of the displayed drawing unit. Angles are degrees. IDs are session-scoped and face/edge references expire when the revision changes.
Create one line
Call cad_execute_operation with the following structure. Replace the marked IDs, revision and UUID with live values. The line is created in one Undo batch.
{
"sessionId": "TARGET_SESSION",
"request": {
"documentId": "CURRENT_DOCUMENT",
"expectedRevision": 0,
"operationId": "NEW_UUID",
"operation": "geometry.create",
"parameters": {
"objects": [{"line": {
"start": {"x": 0, "y": 0, "z": 0},
"end": {"x": 50, "y": 0, "z": 0}
}}]
},
"selectResult": true
}
}Check the returned EditResult and updated document state. Do not interpret a dispatched GUI command as proof that a line was created. An example AI instruction is: “In the selected test drawing, create one 50 mm line along WCS X from the origin. Confirm the drawing before editing and report the returned entity ID.”
Calculate and then commit
Heavy operations use cad_start_operation with a request and timeoutSeconds, normally 120. Poll cad_get_job at a reasonable interval. running means queued or calculating. ready means that geometry is available but the drawing is unchanged. Verify that the drawing revision still matches the source, then call cad_commit_job with a new commit UUID. The start UUID must not be reused for the commit.
| State | Next action |
|---|---|
| running | Wait and query again, or cancel. |
| ready | Commit explicitly or discard with cad_cancel_job. |
| committed | The drawing edit was applied. Repeating the identical commit request does not duplicate it. |
| completed | A read-only data result is available; read cad_get_job_data. Do not commit. |
| failed / cancelled | Inspect errorCode/message; the calculation did not modify the drawing. |
At most four running/ready jobs are retained; one worker calculation runs at a time. Timeouts range from 1 to 1800 seconds. Start requests capture source geometry and revision. Merely supplying a newer revision to an old result cannot make it valid.
License errors visible to the AI
cad_get_capabilities includes license.currentPlan and operation availability. A denied operation has unavailableCode=license_required and licenseRestriction with the feature, operation, current plan and required plans. These details are also returned by schema and interactive-command discovery. Execution and committing a ready result recheck permissions.
{
"code": "license_required",
"message": "This API requires an active STD or Pro license.",
"licenseRestriction": {
"feature": "sheetmetal",
"operation": "sheet.loft",
"currentPlan": "Free",
"requiredPlans": ["STD", "Pro"],
"retryable": false
}
}This is an illustrative payload. MCP returns isError=true and a JSON error text. The AI should explain the restriction and required plan, then offer an available operation. Repeating requests or trying another API does not remove the restriction. The rejected operation leaves the drawing unchanged.
Transport failure and Undo
When a connection drops during an edit, resend exactly the same request and operationId to retrieve its result. Generating a new UUID blindly can duplicate edits. Worker calculations do not automatically stop when the client disconnects; retry the identical start request to recover the job ID.
cad_undo and cad_redo operate on the drawing's global history, including manual edits. They are not an MCP-only history. Query the current document state before using them, and do not undo an unrelated user action.
GUI commands are interactive
cad_get_interactive_commands lists GUI command IDs; cad_launch_interactive_command queues one for the user to complete. The result queued is an acknowledgement only. It does not confirm saving, printing, creation or a successful solve. Prefer structured operations from cad_get_capabilities for automation.
Troubleshooting
| Symptom | Check |
|---|---|
| No server tools | Executable path, complete Mcp folder, desktop runtime and client configuration. |
| No CAD sessions | CAD is running under the same Windows user. Open a drawing and reconnect the client. |
| cad_busy | Finish or cancel the active CAD command or dialog. |
| session_not_found / cad_unavailable | List sessions again; do not silently switch to a different drawing. |
| revision_conflict | Reinspect entities/topology and restart from the current drawing state. |
| license_required | Explain requiredPlans and select an available operation. |
| message_too_large | Reduce request/page size. Each bridge message is limited to 1 MiB. |
| worker_unavailable | Restore the matching Automation.Worker files from the complete installer. |
| geometry_failed / invalid_result | Review geometry, dimensions and operation limits. No universal BRep success guarantee is implied. |
Entity list pages contain up to 1000 items; topology and job-data pages up to 256. Large analysis inputs or transient frames can exceed the bridge limit. Unknown operations and arbitrary calls to internal CAD methods are not accepted.
Save and export
cad_get_file_formats → cad_save_document or cad_export_document → cad_get_file_operation. Cancel with cad_cancel_file_operation. Only completed confirms success. Inspect error for failed operations; do not use cad_commit_job for file output. Free formats are JDC, JSON and STL.
Inspect drawings through MCP
Execute view.capture with cad_execute_operation to render the model or a named layout to a local PNG. Layout images include native views, paper geometry and dimensions. Geometry, selection and revision are unchanged. Supply an absolute filePath, optional layoutName, width (320–4096), height (240–4096), and overwrite only when replacing an existing file. The folder must exist. Open the resulting image in the client to inspect it.
Use cad_query with kind layouts for available sheets or sheetDefaults for current sheet-metal settings. layout.create creates native model views, paper objects and scaled dimensions as one undoable operation. layout.activate switches sheets. Partial sheet.flange ranges use startDistance and endDistance. Discover each operation schema before execution.
Drafting rules for notes and dimensions
Use native text leaders for feature notes such as radii, hole counts, slots and chamfers. Query layoutAnnotations for current paper indices, then call layout.annotations at the same revision. Each leader has Text, Anchor (arrow tip), Landing (start of text shelf) and optional Elbows. Text, arrows and segments remain one editable annotation. Existing dimensions, models and viewports are preserved.
For circle/arc location or pitch dimensions, use exact centers when appropriate to the intended dimension, not tangent endpoints with coincident projected coordinates. Follow explicit overall, tangent or edge dimensions in the source drawing. Preserve existing dimensions when requested by the user. Inspect the result using view.capture.
Apply text or images to faces
Select Surface label from the annotation button dropdown, click a model face, choose text or an image, and preview its width, height, rotation and center before completing the command. Choose an existing label in Target label, select Edit or Remove, and commit with the checkmark. Face selection and settings changes do not commit automatically. The font dropdown initially uses the current drawing text font. Removing a label preserves its owner geometry and is undoable. The assignable command ID is MenuId.Constr.SurfaceLabel.
Planes, cylinders, spheres and freeform surfaces are supported. Labels continue across connected patches of the same surface and cylindrical seams, while real boundaries and holes clip the image. Dimensions use the tangent metric at the center; spherical/freeform labels may distort away from it. Singular centers and placements spanning a full period are rejected.
Labels do not change BRep geometry or volume. Embedded pixels survive JDC save/reload without the source image, follow move/copy, and appear in printing and PNG output. STEP/STL do not include raster labels.
Use cad_execute_operation with face.label. Obtain a current face reference from topology (entityId, revision, kind="face", index). Supply WCS center, width/height in mm, rotationDegrees, and either text or an absolute imagePath. Text also supports fontName and a six-digit RGB color. Discover the full schema first.
Query kind="surfaceLabels" with 1–100 explicit entityIds for face references, label IDs and placement. Mode add is the default; replace/remove require a labelId. Changes across connected patches form one Undo step.
User input, selection and previews
Start with cad_start_input and poll cad_get_input for user acceptance. cad_cancel_input cancels; cad_update_input_preview updates transient feedback; cad_select_region performs region selection. waiting and CursorPoint are not confirmed input.