onshape-jamcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| ONSHAPE_UNITS | No | Unit system: `metric` for millimeters or `imperial` for inches. Angles are always degrees. | metric |
| ONSHAPE_BASE_URL | No | Onshape base URL. For Enterprise use your company's Onshape URL, e.g. `https://yourcompany.onshape.com`. | https://cad.onshape.com |
| ONSHAPE_READ_ONLY | No | Hide all tools that can modify a document. | false |
| ONSHAPE_ACCESS_KEY | Yes | Your Onshape API access key. Required. | |
| ONSHAPE_SECRET_KEY | Yes | Your Onshape API secret key. Required. | |
| ONSHAPE_SCREENSHOT_REVIEW | No | Send screenshots to the LLM (`true`) or only save them to disk (`false`). | true |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Onshape CAD server. Typical workflow:
get_settings - learn the length unit (metric mm by default, or imperial inches). Every length you send or receive uses that unit; angles are degrees.
list_documents / get_document - find document_id and element_id (a Part Studio tab). create_document + create_element start from scratch.
Model: create_sketch (shapes on Top/Front/Right or a face) -> extrude (operation new/add/remove) -> fillet / chamfer. Use list_features to check every feature reports OK.
Verify: get_part_properties (dimensions), get_body_details (face/edge IDs), capture_screenshot (visual check; images cost tokens only when screenshot review is on).
Custom features (Feature Studio scripts such as Thread Creator): list_custom_features -> add_custom_feature. ThreadCreator takes the selected face as the thread's MAJOR diameter (a nut's hole must be Ø10 for M10, not the tap-drill size) and defaults to internal ANSI threads: pass internalThreads, threadProfile (ISO_STD) and the pitch p explicitly. Check the result by volume, not only by status. Details: docs/threads.md in the repository.
Repeat and shape: circular_pattern / linear_pattern / mirror (pass feature_ids - the feature that makes ONE spoke or hole - so the copies merge or cut like it, or part_ids for separate copies), revolve (profile plus a construction-line axis), shell, boolean. Their replies carry
effect(parts and volume before/after) and a warning when nothing changed: Onshape can accept a feature that does nothing, so read it. Put counts in a variable ('#spokes') when they should be configurable.Anything else: onshape_api_request / add_feature / run_featurescript. Defaults for every model, unless the user says otherwise: (a) NAME things - give each part a descriptive name (extrude part_name / rename) and rename a tab that still says "Part Studio N" or "Assembly N"; keep names the user chose. Extrudes are named with their size by default ("Extrude 8 mm", "Cut 3 mm", "Extrude (head_h)"); pass hole=true for a drilled hole (named "Hole", no size). Never put "#word" in a name you choose: Onshape reads it as a parameter of that feature and shows "?" - write variables as (word). (b) Put key dimensions (diameter, length, pitch, wall, ...) in VARIABLES with set_variable and use "#name" for sizes in sketches (circle, rectangle width/height, hexagon), extrude depth, fillets and thread pitch; use plain numbers only for incidental values. Only when the user asks: ASSEMBLIES (insert_instance with the first part fixed, then add_mate: check the positions it returns - an accepted mate is not proof it moved anything) and CONFIGURATIONS (set_configuration_input, set_variable by_option, then pass configuration to get_part_properties / capture_screenshot). Fewer requests: set many variables with set_variable(variables={...}) and change several features with update_feature(updates=[...]) - each is one Onshape request however many. Onshape limits each endpoint per day: avoid needless list_features calls and read a 429 message that says "daily limit" as "stop retrying". Never guess IDs - read them from tool results.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| get_settingsA | Show this server's active settings: the unit system every length uses (metric = mm by default, or imperial = inches), whether screenshots are sent to you for visual review, read-only mode, and the Onshape API target. Never reveals API keys. Call this first so you know which unit to use for lengths. |
| whoamiA | Check that the configured credentials (API keys or OAuth sign-in) really work, by asking
Onshape which account they belong to: returns connected, user_id, name and the base_url in
use. Use it first in a session or whenever another tool answers 401, and to tell a wrong
key from a wrong document ID. Read-only, one request, nothing is changed. Onshape answers
200 with an empty body to credentials it does not recognise, so this call treats that
"anonymous" reply as a failure and explains how to fix the keys. It does not show which
permissions (read / write / delete) the key has - a 403 from a modeling tool means the key
lacks the write scope. For this server's own settings use |
| list_documentsA | Find Onshape documents: returns each one's document_id (every other tool needs it),
name, modified_at and owner, newest first unless |
| get_documentA | Describe one document: its main workspace ID and every element (tab) in it - Part
Studios, Assemblies, Drawings, imported files - with their element IDs and types. A tab
flagged has_default_name still carries Onshape's placeholder name: rename it with |
| create_documentA | Create a new, empty-looking Onshape document in the user's account and return its
document_id, workspace_id, name, url and the tabs it already has (Onshape usually adds a
'Part Studio 1' and an 'Assembly 1': reuse and |
| create_elementA | Add a new tab to a document and return its element_id, name and kind: a Part Studio
(where sketches, extrudes and the other features build parts) or an Assembly (where parts
are inserted and mated). Use it when the document has no suitable tab - a new document
already has a Part Studio and an Assembly, so check |
| list_featuresA | List the feature tree of a Part Studio in order: |
| list_partsA | List the parts (solid and surface bodies) a Part Studio currently produces: part_id,
name, body_type and hidden, one request, read-only. Use it to get the part IDs that other
tools take - |
| get_part_propertiesA | Measure geometry: the axis-aligned bounding box (min/max/size) plus volume, surface area, mass and centroid per part, in the configured length unit. Use it to verify dimensions and orientation after modeling. Mass is only meaningful if the part has a material assigned in Onshape. |
| get_body_detailsA | List the faces (and optionally edges) of each part with their IDs, geometry type,
area, a point on the face and its outward normal, all in the configured length unit. Use
face IDs as |
| get_assemblyA | Read an Assembly tab: what it contains, where everything sits and what is mated. Call it
before changing an assembly (to get the instance IDs |
| run_featurescriptA | Evaluate a read-only FeatureScript snippet against a Part Studio and return its result. Powerful for queries the other tools do not cover (face counts, distances, evaluating selections). It cannot modify the document. NOTE: lengths inside FeatureScript results are in METERS, not the configured unit. |
| list_variablesA | List the variables of a Part Studio: name, type, the expression it was set with and its current value (lengths in the configured unit, angles in degrees). A variable that depends on a configuration input also shows configured_by and its value per option. Reference a variable as '#name' in sketch sizes, extrude depths, fillet radii, thread pitch, etc. |
| set_variableA | Create a Part Studio variable, or change its value if it already exists. By default
model with variables: put every key dimension (diameter, length, pitch, wall thickness,
...) in a variable first, then use '#name' wherever the size is needed, so changing one
value reshapes the whole model. Pass |
| get_configurationA | List the configuration inputs of a Part Studio (for example a 'Size' list with M10 and
M18, or a 'Length'), with their options and defaults. Names are the labels shown in
Onshape; for an input made in Onshape's UI the generated |
| set_configuration_inputA | Add a configuration input to a Part Studio, or replace the input of the same name. Only
when the user asks for configurations. To make dimensions depend on a list input, use
set_variable with |
| insert_instanceA | Insert a part (or a whole Part Studio) into an Assembly and return the new instances' IDs and names. Name the Assembly tab (rename) if it still says 'Assembly N'. Only when the user asks for an assembly. Join parts with add_mate. |
| add_mateA | Join two part instances of an Assembly with a mate. Pick a spot on each: for a nut on a bolt use the bolt's circular end edge (at 'center') and a face of the nut (at 'centroid'), with mate_type 'cylindrical' (free to turn and slide) or 'fastened'. The first instance stays where it is if it is grounded; the second moves to satisfy the mate. Returns the real status and both instances' resulting positions. Only when the user asks for an assembly. Note: the centroid of a threaded face can sit ~0.2 mm off the thread's axis. |
| create_sketchA | Create a sketch of 2D shapes on a plane or planar face. Point coordinates are [x, y]
in the sketch's own axes, in the configured length unit (mm by default). Returns the
sketch's feature_id, to pass to |
| extrudeA | Extrude all closed regions of a sketch into a solid, or cut with it (operation 'remove'). The default direction follows the sketch plane's normal. For a sketch on a part's own face that normal points OUT of the part, so to cut a hole or pocket INTO the part pass opposite_direction=true (verified on live Onshape; without it nothing is cut). Always confirm with get_part_properties - the volume must drop. For operation 'new' the reply lists the created parts (parts_created) and names them when part_name is given. |
| filletA | Round edges with a constant-radius fillet: a smooth, curved blend between the two faces
that meet at each edge. Use it to soften corners and sharp edges; use |
| chamferA | Bevel edges with an equal-distance chamfer: a flat, angled cut that takes the same
distance off both faces at each edge (a 45 degree bevel on a right-angle edge). Use it for
lead-in bevels, bolt and shaft tips and to break sharp edges; use |
| update_featureA | Change parameters of existing features (for example make an extrude deeper or a
fillet larger) without rebuilding them. Dependent features rebuild automatically. To
change several features at once pass |
| delete_featureA | Permanently remove one feature from a Part Studio (an extrude, a fillet, a variable, a
pattern, ...). Use it to undo a feature that went wrong (status ERROR, or a warning that
nothing changed) or that is no longer wanted; to change a feature instead, use
|
| add_featureA | Advanced escape hatch: add any Onshape feature from raw JSON - revolve, patterns,
sweeps, holes, and so on. Copy the structure from an existing feature
( |
| circular_patternA | Repeat parts, features or faces around an axis (a wheel's spokes, bolt holes on a circle). Pattern the FEATURE that makes one spoke or hole (feature_ids) so the copies merge or cut as it does; pattern parts (part_ids) to get separate copies. Put the count in a variable ('#spokes') when it should be configurable. The default name shows the count ('Circular pattern x6'). The reply says what changed (parts, volume). |
| linear_patternA | Repeat parts, features or faces in a straight line (a row of holes, ribs, legs); add
a second direction for a grid. |
| mirrorA | Mirror parts, features or faces across a plane. Mirroring a part gives a second part (operation 'new') or merges the copy into the original ('add'); mirroring the feature that makes one half builds a symmetric part. The default name shows the plane ('Mirror (Right)'). The reply says what changed (parts, volume). |
| revolveA | Revolve the closed regions of a sketch around an axis into a solid of revolution (a bottle, a pulley, a washer) or cut a groove with it (operation 'remove'). Draw the profile on one side of the axis and, in the same sketch, the axis as a construction line. The reply says what changed (parts, volume) and lists the created parts. |
| shellA | Hollow out a part with walls of the given thickness. Give |
| booleanA | Combine whole parts: join them (union), cut one with another (subtract: a bolt hole shaped like a part) or keep what they share (intersect). Part IDs change when parts merge, so call list_parts afterwards. The reply says what changed (parts removed, volume). |
| renameA | Give a part, or a whole tab (Part Studio / Assembly), a descriptive name. Do this by default: a part still called 'Part 2' or a tab still called 'Part Studio 1' says nothing. Keep a name the user chose; rename only placeholders (flagged has_default_name by get_document and list_parts) unless the user asks otherwise. |
| list_custom_featuresA | List custom features (Feature Studio scripts such as Thread Creator) that add_custom_feature can add: feature_type, namespace and every parameter with its type, unit, default and options. Also lists the custom features this Part Studio already uses. Built-in Onshape features are not listed - use the dedicated tools for those. |
| add_custom_featureA | Add a custom feature (a Feature Studio script such as Thread Creator) to a Part Studio. Find its feature_type and parameter IDs with list_custom_features first. Returns the new feature_id and its health status; if that is ERROR or WARNING, inspect it with list_features(feature_id=...), then fix it with update_feature or remove it with delete_feature. |
| capture_screenshotA | Render a shaded screenshot of a Part Studio or Assembly from one or more standard
camera angles. Images are always saved to disk. Whether they are also returned to you for
visual inspection depends on the |
| export_modelA | Export a Part Studio or Assembly to a CAD/mesh file (STEP, STL, Parasolid, IGES) on the machine running this server and return the file path. Does not modify the document. STL sizes follow the configured unit system. |
| onshape_api_requestA | Escape hatch: call any Onshape REST endpoint directly. Use it for things the dedicated tools do not cover. WARNING: this is the raw API - lengths are in METERS (no unit conversion), POST/DELETE can change or destroy data, and in read-only mode only GET is allowed. Large responses are truncated. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 37 tools
Most tools target a clearly distinct resource+action (sketch, extrude, revolve, shell, fillet, chamfer, pattern, boolean, mate, variable, configuration), and the descriptions explicitly cross-reference alternatives (fillet vs chamfer, shell vs extrude-remove). The main friction is the three escape hatches — add_feature, add_custom_feature and onshape_api_request — plus update_feature, which all overlap in 'add/change arbitrary geometry'; the guidance differentiates them but an agent must read carefully to pick correctly.
Most tools follow a snake_case verb_noun pattern (list_documents, create_element, get_settings, set_variable, add_mate, update_feature, delete_feature). However, a large block of modeling tools is named after the bare feature (extrude, revolve, fillet, chamfer, shell, boolean, mirror), and there are further outliers like circular_pattern/linear_pattern (no verb) and whoami. Readable and intuitive by domain convention, but the conventions are genuinely mixed.
37 tools exceeds the comfortable range, and the surface spans modeling, assemblies, variables, configurations, custom features, export and two escape hatches. Most tools are distinct and earn their place in a real CAD workflow, but it is heavy enough that an agent faces a non-trivial selection problem each turn.
Coverage is strong: document/element lifecycle, the feature tree (sketch, extrude, revolve, patterns, mirror, boolean, shell, fillet, chamfer), parts and body inspection, assemblies and mates, variables and configurations, custom features, screenshots, export and raw API access. The notable gaps are deletion of documents and elements (explicitly admitted for documents), plus no drawing/version-management tools, which agents can partially work around via escape hatches.