Skip to content
CADground Documentation
Documentation menu

MCP tools and permissions

Check which tools your client can use, which permissions they need, and the limits on requests and returned files.

4 min readUpdated

Which project and scene the client can access

Each connection gives access to one Cloud project. A workspace tool cannot switch the client to another project. Add a separate server URL and allow access for each project you want to use.

The connection uses the project’s saved active scene. Load the correct source in CADground before starting. At the start of each task, ask the client to read the current scene state. Do this again if you change the source.

The tables list CADground tool names. Your client may add a server name before each tool name. Each tool’s schema defines its required inputs, supported geometry types, and returned values. Use that schema. Do not guess the inputs from the tool name.

Read-only tools

ToolPurpose
list_workspaces, get_current_workspace, select_workspaceRead or select the workspace linked to the project. Selection does not grant access to another project.
get_scene_stateRead the current source, scene state, and other available information.
list_objects, get_objectRead object IDs, components, and metadata.
get_user_viewpointRead information about the user’s view, including a picture when available.
take_picture, take_orthographic_pictureTake a scene picture or an orthographic picture to inspect the scene and record measurements.
pick, pick_nearest_visibleFind scene points that match positions in an image, using the tool’s supported inputs.
measureCalculate measurements from supported coordinates or selected points.
evaluate_fitCheck how closely geometry matches the source, using the requested settings.

Write tools: view, selection, and focus

These tools require mcp:write. They change scene settings shared with other users and clients, even when geometry stays the same.

ToolPurpose
spawn_drone, select_drone, delete_droneCreate, select, or remove virtual cameras.
move_camera, rotate_camera, look_at, reset_cameraMove and turn a virtual camera.
set_viewportChange the active viewport mode or settings, using the tool’s supported inputs.
set_focus, clear_focusLimit inspection to a selected region or restore the wider scene.
set_visibility, select_objectChange which objects are visible or selected.
add_point_region, delete_point_regionAdd or remove named regions of source points.

Write tools: geometry and objects

ToolPurpose
import_modelImport a supported model already uploaded to this project. This tool cannot read arbitrary files from the client’s computer.
move_object, update_object, delete_objectChange object properties, move objects, or delete them.
merge_objects, unmerge_objectGroup or ungroup supported objects.
update_component, delete_componentEdit or remove supported components.
add_shape, update_shapeCreate or modify supported geometric shapes.
fit_minimum_oriented_boxFit a box around the selected source points. The box can be rotated to match the points. Check whether a box is a suitable shape.
fit_mesh_with_fixed_topologyFit a mesh with a defined structure to the selected source points.
fit_bspline_surfaceFit a smooth surface where this type of surface suits the source.
reconstruct_scan_surface_meshBuild a mesh from scan points. Start with one small region and review the result.
add_mesh, update_meshCreate or edit a mesh using the supported vertices/faces schema.
add_surface, update_surface, trim_surfaceCreate, change, and trim supported analytic or fitted surfaces.

Project files and reports

File tools work without opening a scene. Save reports in outputs/ and source models in files/. Saved files appear in the project’s Files panel. Refresh your client’s tool list if these tools are missing.

ToolsPurposePermission
list_files, read_fileBrowse folders, read text, and download binary files.Read
write_file, edit_fileCreate or replace a file, or replace literal text.Write
rename_file, delete_file, create_directoryMove or rename a file, delete one file, or create a folder.Write
begin_file_upload, upload_file_chunk, finish_file_upload, cancel_file_uploadTransfer a larger PDF, model, or other binary file in chunks.Write

Ask the client to save a text report with write_file. For a larger PDF, it must read its local bytes, begin an upload with the file size and SHA-256, send base64 chunks, then finish the upload. Sending only a filename from your computer is insufficient. The server does not fetch arbitrary URLs.

Each call transfers up to 512 KiB of decoded content; chunked files can be up to 8 GiB. Uploads remain private until their size and checksum match, expire after one hour, and belong to the connection that began them. Read larger files as base64 ranges, following next_offset.

Before overwriting, editing, renaming, or deleting a file, read its current revision and send it as expected_revision. A changed revision fails instead of applying an edit to newer content. Deletion is permanent and applies to one file.

Tools excluded from external access

create_object and extract_potential_surface are not available to external clients. They can start AI extraction paid for by CADground. Write permission does not enable them. External clients can still import a model already uploaded to the project or use the supported geometry tools.

Project file access is limited to files/ and outputs/ in the connected project. External MCP does not provide a general shell or access to hidden runtime files.

Read returned resources

A tool may return a resource, such as a picture, through a cadground://… URI. This is an address for the AI client to read through MCP’s authenticated resources/read capability. It is not a browser link or a permanent public download.

  • Resources belong to the authorized connection and project.
  • Temporary resource addresses expire after one hour. Generate the picture again if its address has expired.
  • The resource limit is 12 MB. Reduce the capture size if it exceeds this limit.
  • A resource address works only for the connection that created it. A different account or connection cannot use the same address.

Execution and capture limits

  • Run scene operations one at a time. Another external tool call or a built-in AI task can make the project busy.
  • External captures: at most 4096 pixels on either side and four million pixels total. A 1920 × 1080 capture fits; a 4096 × 4096 capture does not.
  • Tool time limits: server tools have a time limit. Your client may stop waiting sooner if its own limit is shorter. Use smaller tasks. Before retrying a tool that changes the scene, check whether it already made the change.
  • Access during a request: access can end if you revoke the connection, change project permissions or the plan, or archive the project.

For setup failures and resource errors, see Troubleshoot MCP.