Connecting an AI Agent
linkcad-mcp is installed with LinkCAD 11.3 and later, in the installation folder beside linkcad:
| Platform | Path |
|---|---|
| Windows | C:\Program Files\LinkCAD 11\linkcad-mcp.exe (default installation folder) |
| Linux | /opt/linkcad/linkcad-mcp |
The agent’s application (the MCP client) starts linkcad-mcp itself and talks to it through its standard input and output. You do not start it, and it opens no network port. The installer does not change the configuration of any client; you register the server once per client, as described below.
Choose the folders
The server needs to know which folders the agent may use. Name each one when you register it:
--root <folder>lets the agent read and write files under that folder.--read-root <folder>lets it only read files under that folder. A--read-rootinside a--rootmakes that part read-only.
Both can be given several times, and each folder must exist. The agent cannot use a path outside these folders and cannot add folders itself. A relative path the agent gives is resolved against the first folder it may use.
Print the registration
linkcad-mcp --print-config <client> prints the registration for a client, with the path of this installation and the folders already in the form that client expects. The clients it knows are claude-code, claude-desktop, vscode and cursor.
& "C:\Program Files\LinkCAD 11\linkcad-mcp.exe" --print-config claude-desktop ` --root "C:\CAD\Work" --read-root "C:\CAD\Library"/opt/linkcad/linkcad-mcp --print-config claude-code --root ~/cadRegister it with the client
Claude Code
Run the claude mcp add command that --print-config claude-code prints. It looks like this:
claude mcp add --transport stdio --scope user linkcad -- /opt/linkcad/linkcad-mcp --root /home/me/cad--scope user makes LinkCAD available in every project. claude mcp list shows whether the server connected.
Claude Desktop
-
Open Settings > Developer > Edit Config. This opens
claude_desktop_config.json:%APPDATA%\Claude\claude_desktop_config.jsonon Windows,~/.config/Claude/claude_desktop_config.jsonon Linux. -
Merge the
mcpServersentry that--print-config claude-desktopprints into the file:{"mcpServers": {"linkcad": {"command": "C:\\Program Files\\LinkCAD 11\\linkcad-mcp.exe","args": ["--root", "C:\\CAD\\Work", "--read-root", "C:\\CAD\\Library"]}}} -
Quit Claude Desktop completely and start it again.
VS Code (GitHub Copilot)
Add the servers entry that --print-config vscode prints to .vscode/mcp.json in your workspace, then start the server from the MCP view or the Start action shown above the entry in the file. The Copilot CLI reads mcpServers from ~/.copilot/mcp-config.json or a workspace .mcp.json; use the claude-desktop form there.
Cursor
Add the entry that --print-config cursor prints to .cursor/mcp.json in the project, or to ~/.cursor/mcp.json for every project.
Other clients
Any MCP client that starts a server over stdio can use linkcad-mcp. Give it the program path as the command and the folder options as its arguments.
Server options
| Option | Meaning |
|---|---|
--root <folder> | A folder the agent may read and write under. Repeatable. |
--read-root <folder> | A folder the agent may only read under. Repeatable. |
--allow-python | Offer the execute_python tool, which runs Python code in LinkCAD’s embedded interpreter. The code runs with your user’s privileges and is not limited to the folders above, so enable it only for an agent you would let run scripts on your computer. |
--call-timeout <seconds> | How long one tool call may take before LinkCAD is restarted. Default 600; 0 disables the limit. |
--idle-timeout <seconds> | How long LinkCAD may stay idle, with no drawing open, before it is stopped to free its memory. Default 900; 0 keeps it running. |
--print-config <client> | Print the registration for claude-code, claude-desktop, vscode or cursor, and exit. |
--version, --help | Print the version or the option list, and exit. |
Check the connection
Ask the agent “What is the status of LinkCAD?”. It calls get_status, which reports the LinkCAD version, the license state, the licenses held, the folders and the open drawings. The first call takes a few seconds, because LinkCAD starts then.
Troubleshooting
| Symptom | Cause and remedy |
|---|---|
| The client shows the server as failed or disconnected. | Check the program path in the registration. On Windows, every backslash in a JSON file must be doubled, which --print-config does for you. |
The agent reports path_outside_roots or no_roots_configured. | The file is not under a folder named with --root or --read-root. Add the folder to the registration and restart the client. |
The agent reports path_not_writable. | The folder is a --read-root. Write under a --root folder instead. |
The agent reports a ..._license_required or format_not_licensed error. | The task needs a license this computer does not hold. See Licensing. |
The agent reports license_blocked. | The license does not allow LinkCAD to work on this computer, for example because it is not registered. get_status gives the reason. Start the LinkCAD application to register it. |
The agent reports timeout or worker_crashed. | LinkCAD was restarted and every open drawing was closed. The agent reopens the file and tries again. If a large file needs longer, raise --call-timeout. |
LinkCAD’s own log goes to the server’s standard error, which most clients show in their MCP log (in Claude Desktop, under Settings > Developer).
Every call starts from LinkCAD’s default options, not from the settings of the desktop application, and nothing the agent does is saved to those settings.