MCP Tool Reference
These are the tools linkcad-mcp offers an agent. The agent reads their descriptions and argument schemas from the server, so you do not have to pass any of this on. This page is for checking what an agent can do and for reading its tool calls.
A drawing is identified by the handle that open_drawing returns, such as d1a2b3c-1. Paths must lie under the folders given with --root or --read-root (Connecting an AI Agent). Coordinates are integers in database units; summary.units_per_meter in inspect_drawing converts them.
Information
| Tool | Arguments | Result |
|---|---|---|
get_status | None | LinkCAD version, license state and the licenses held (Basic, Tools, Edit, View), the folders, and the open drawings. |
list_formats | direction: import or export (optional) | Every installed format with its exact name, file filter and whether the license covers it. Other tools take these names. |
list_options | filter: part of an option name, such as GdsIn or DxfOut; offset, limit | Conversion options with type, default and current value, and whether a tool call may set them. |
Drawings
| Tool | Arguments | Result |
|---|---|---|
open_drawing | paths (one or more files), format, export_format, options, layer_map | A drawing handle, its summary and the import log. The format is detected from the file when format is omitted. |
inspect_drawing | drawing, view, cell, layer, offset, limit | view is summary (units, bounds, counts), layers, cells, hierarchy (the cells one cell references), shape_counts (per cell, layer and shape type) or shapes (the shapes of one cell, paged). |
close_drawing | drawing | Frees the drawing. At most eight drawings are open at once. |
Give export_format to open_drawing when the drawing will be exported. LinkCAD assigns export layer numbers and cell names while it reads a file, as the conversion wizard does, so the export format cannot be changed later. A drawing opened without it can be inspected, changed and previewed, but export_drawing refuses it with no_export_format.
options sets format options by name for this call only, for example {"GdsInIgnoreText": true}. layer_map applies a layer map file while reading and needs export_format.
Changing a drawing
| Tool | Arguments | Result |
|---|---|---|
apply_tools | drawing, commands | Runs tool commands in order and returns the new summary and the log. |
set_layers | drawing, layers, delete | Changes layers. Each entry of layers names a layer and sets enabled (a disabled layer is not exported), color (#RRGGBB, the preview color) or rename_to. delete lists layers to delete together with their shapes. |
list_plugin_tools | None | The installed Python tool plugins, each with its options. |
run_plugin_tool | tool (as module:Class), drawing, options | Runs a plugin tool and returns its result text. Options take their short names, such as calculate_area. |
commands are the commands of --apply-tool, one per array element, for example ["SetUnits(um)", "MergeOverlappingPolygons()", "Offset(0.5)"]. Lengths without a unit are micrometers. Mode commands such as SetUnits, SetFillRule and SetLayerFilter apply to the commands after them. All commands are checked against the license before the first one runs. If a command fails, the ones before it stay applied and the error names the command that failed.
set_layers checks every layer name before it changes anything. A misspelled name changes nothing and never creates a layer.
Preview
| Tool | Arguments | Result |
|---|---|---|
render_preview | drawing, width (64 to 2048, default 1024), height (64 to 2048, default 768), window, layers, fill (default true), background (black or white) | A PNG of the main cell, drawn as the LinkCAD viewer draws it, and the scale in database units per pixel. window is [xmin, ymin, xmax, ymax] in database units; layers limits the picture to those layers. |
Writing files
| Tool | Arguments | Result |
|---|---|---|
export_drawing | drawing, path, overwrite | Writes the drawing in the export format chosen when it was opened and returns the files written and the export log. |
convert_file | input (one or more files), output, output_format, input_format, options, layer_map, commands, overwrite | Reads, runs tool commands and writes in one call, without leaving a drawing open. |
get_log | drawing, which (import or export), offset, limit | The full import or export log, paged. Tool results carry the first entries of the log. |
An export never replaces the file the drawing was read from. It replaces another existing file only with overwrite: true. The writer writes into a hidden folder beside the destination first, and only a successful export is moved into place, all its files together. A writer that produces several files, such as one file per layer, can be given a folder as path.
Python
| Tool | Arguments | Result |
|---|---|---|
execute_python | code, drawing | Runs Python code in LinkCAD’s embedded interpreter with the linkcad package. With drawing, that drawing is the global drawing. Returns standard output, standard error and the error, if any. |
execute_python exists only when the server was started with --allow-python. The code runs with your user’s privileges and is not limited to the folders.
Resources and prompts
The server also offers documents and prompt templates. Clients show resources as attachable context and prompts as commands, for example /mcp__linkcad__inspect_layout in Claude Code.
| Name | Kind | Content |
|---|---|---|
linkcad://guide/agent | Resource | How to use the tools: the workflow, units, option names, how to verify a conversion and what each error means. |
linkcad://reference/tool-apply | Resource | The grammar of the tool commands. |
linkcad://reference/python-api | Resource | The linkcad Python package. Only with --allow-python. |
inspect_layout | Prompt | Open a file and report its units, bounds, top cells, layers and log, with a preview. |
convert_and_verify | Prompt | Convert a file, reopen the output and compare it with the source. |
Errors
A failed call returns an error with a stable code, a message and, for reads and writes, the conversion log. The agent receives the same table in its guide.
| Code | Meaning |
|---|---|
invalid_arguments | The arguments do not match the tool’s schema. |
path_outside_roots, no_roots_configured | The path is not under a folder the server was given. |
path_not_writable | The folder is read-only (--read-root). |
path_not_found | The file does not exist. |
file_exists | The output exists and overwrite was not given. |
would_overwrite_input | The output is the drawing’s own source file. |
unknown_format, format_unavailable | No installed reader or writer has that name. |
format_not_licensed | The license does not cover the format. |
license_blocked, license_read_only, license_unavailable | The license does not allow this. get_status shows the state and the reason. |
basic_license_required, tools_license_required, edit_license_required, view_license_required | The named license is missing. Nothing was changed. |
no_export_format | The drawing was opened without export_format. |
read_failed, write_failed | The reader or writer failed; the log says why. |
tool_failed | A tool command failed. The commands before it were applied. |
option_rejected | The option does not exist or may not be set through the server, for example because it is an application setting or writes files of its own. |
unknown_drawing, unknown_layer, unknown_cell | No drawing, layer or cell of that name. Names are case-sensitive. |
too_many_drawings | Eight drawings are open. Close one first. |
python_unavailable, unknown_plugin_tool, plugin_tool_failed | Python could not start, the plugin tool does not exist, or it failed. |
python_error | The Python code passed to execute_python could not run. |
render_failed | The preview could not be drawn. |
timeout, worker_crashed | LinkCAD was restarted and every open drawing was closed. |
worker_start_failed, worker_protocol_error, internal_error | LinkCAD could not be started or answered incorrectly. The server’s log, shown by the client, says why. |
busy | Too many calls are waiting. |