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

  1. Install the complete JDesignCAD 1.1.3 package. Check that Customization\Mcp\JDesignCAD.Mcp.exe and its accompanying files exist.
  2. Open your AI client's MCP server configuration. Use the executable path in the example, changing it if CAD was installed elsewhere.
  3. Restart or reconnect the MCP client as required by that client.
  4. Start JDesignCAD as the same Windows user and open a test drawing in model space.
  5. 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

  1. cad_list_sessions returns candidate windows. Choose sessionId explicitly; do not assume the first result is correct.
  2. cad_get_document returns documentId, revision, object count and Undo/Redo state.
  3. cad_get_capabilities returns registered operation names, execution modes and license availability.
  4. cad_get_operation_schema returns exact JSON parameters for an operation.
  5. 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.

StateNext action
runningWait and query again, or cancel.
readyCommit explicitly or discard with cad_cancel_job.
committedThe drawing edit was applied. Repeating the identical commit request does not duplicate it.
completedA read-only data result is available; read cad_get_job_data. Do not commit.
failed / cancelledInspect 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

SymptomCheck
No server toolsExecutable path, complete Mcp folder, desktop runtime and client configuration.
No CAD sessionsCAD is running under the same Windows user. Open a drawing and reconnect the client.
cad_busyFinish or cancel the active CAD command or dialog.
session_not_found / cad_unavailableList sessions again; do not silently switch to a different drawing.
revision_conflictReinspect entities/topology and restart from the current drawing state.
license_requiredExplain requiredPlans and select an available operation.
message_too_largeReduce request/page size. Each bridge message is limited to 1 MiB.
worker_unavailableRestore the matching Automation.Worker files from the complete installer.
geometry_failed / invalid_resultReview 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.

Open drawings and switch model/layout views

Discover these operations with cad_get_capabilities and cad_get_operation_schema, then use the existing cad_execute_operation tool. No additional MCP connection configuration is required.

Supply the current documentId and expectedRevision and a fresh operationId. Only when no drawing is open on Home, use an empty documentId and expectedRevision=0. Unsaved edits cause unsaved_changes: first save with cad_save_document and wait for completed. Edits or document switches during loading also prevent replacement. After a transport timeout, retry the identical request and operationId; the drawing will not open twice. Use the new document identity in the successful response and reacquire entity IDs.

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.

C#/VB.NET guide