> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runchat.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CAD bridges

> Tools for driving a connected Rhino, Grasshopper, Blender, Revit, ArchiCAD or SketchUp session from the API, MCP or a workflow.

When the Runchat panel is open in a desktop app, that app is connected to your account through a bridge. Agents, scripts and workflows can then read the open document, run code in it and capture its viewport.

There are three ways to use a bridge:

* **Canvas API and MCP.** The tools on this page go through the [Canvas API](https://docs.runchat.com/api-reference/canvas-tools.md) endpoint and the [Runchat MCP server](https://docs.runchat.com/concepts/integrations/mcp.md), like any other canvas tool.
* **Code nodes.** A [Code node](https://docs.runchat.com/concepts/nodes/code.md) with a CAD language runs its script in the connected app each time the workflow runs.
* **Rhino app tools.** HTML apps installed in Rhino reach it through [`runchat.rhino`](https://docs.runchat.com/api-reference/app-bridge#rhino).

```json theme={null}
POST https://runchat.com/api/v1/{runchat_id}/canvas
Authorization: Bearer {api_key}

{
  "tool": "run_rhino_command",
  "args": { "command": "_-Circle 0,0,0 5 _Enter" }
}
```

Over REST, the `runchat_id` comes from the URL path. Over MCP, pass it as an argument to every tool except `install_cad_tool` and `uninstall_cad_tool`.

## Requirements

* The app is open with the Runchat panel signed in to the same account as the API key or MCP connection. See the setup guides for [Rhino](https://docs.runchat.com/plugins/rhino.md), [Grasshopper](https://docs.runchat.com/plugins/grasshopper.md), [Blender](https://docs.runchat.com/plugins/blender.md), [Revit](https://docs.runchat.com/plugins/revit.md), [ArchiCAD](https://docs.runchat.com/plugins/archicad.md) and [SketchUp](https://docs.runchat.com/plugins/sketchup.md).
* Tools that change the document need the panel's **run** permission. Read-only tools do not.
* Tools that change the document can only be used on runchats you own or share a team with.

### Sessions

If you have several windows of the same app open, each is a separate session. Tools use the most recently connected one unless you pass `session`. When more than one is open, the tool result lists the session ids.

## Supported apps

| App | Tools | Code node languages |
| - | - | - |
| Rhino | `run_rhino_command`, `get_rhino_context`, `take_screenshot` | `rhino-python`, `rhino-csharp` |
| Grasshopper | `grasshopper_*` | |
| Blender | `run_blender_command`, `take_screenshot` | `blender-python` |
| Revit | `take_screenshot` | `revit-csharp` |
| ArchiCAD | `take_screenshot` | `archicad-python` |
| SketchUp | `take_screenshot` | |

## Rhino

### `get_rhino_context`

A read-only snapshot of the open Rhino document. Use it before writing a script that needs to know what is in the model.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `session` | `string` | no | Session id to target |

Returns units and tolerance, object counts by type and busiest layer, layers and the current layer, the selection (id, name, layer, type, bounding box), the active view's camera and display mode, view and layout names, the block count, and `toolbar_tools`: the user's installed [CAD tools](https://docs.runchat.com/concepts/integrations/rhino-tools.md).

### `run_rhino_command`

Runs a Rhino command, or a one-off Python or C# script, in the connected Rhino.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `command` | `string` | yes | A command in scripted syntax (`_-Circle 0,0,0 5 _Enter`), or the script source |
| `language` | `"command"` \| `"python"` \| `"csharp"` | no | What `command` holds. Default `"command"` |
| `session` | `string` | no | Session id to target |
| `reason` | `string` | no | A short note for the log |

Returns `success`, `message` and any new console output.

* **Commands** use the non-interactive `_-` form with `_Enter`. Avoid commands that open dialogs or ask the user to pick.
* **Python** runs in Rhino 8's CPython 3 with `rhinoscriptsyntax` and RhinoCommon. `print()` output is returned.
* **C#** runs with `System`, `System.Linq`, `System.Collections.Generic`, `Rhino` and `Rhino.Geometry` imported. Console output and a `runchat_result` variable are returned. Needs plugin 0.3.77 or later on Rhino 8.

## Grasshopper

The Grasshopper tools read and edit the definition open in Grasshopper. Grasshopper opens automatically if it isn't already. Components are identified by their `instanceGuid`, which `grasshopper_read_canvas` and the create tools return.

| Tool | What it does | Main parameters |
| - | - | - |
| `grasshopper_read_canvas` | Every component with its position and parameters, the wires and any labelled groups | |
| `grasshopper_read_selection` | The components the user has selected | |
| `grasshopper_search_components` | Searches the installed component library and returns component GUIDs | `query` or `queries[]`, `category`, `limit`, `offset` |
| `grasshopper_read_component_values` | The current input and output values of components | `instanceGuids[]` |
| `grasshopper_create_components` | Adds components, including sliders, panels and toggles | `components[]`: `id`, `guid` or `name`, `x`, `y`, `min`, `max`, `value` |
| `grasshopper_create_python_script_components` | Adds Python 3 script components, or updates one in place | `components[]`: `id`, `x`, `y`, `code`, `inputs[]`, `outputs[]` |
| `grasshopper_connect_components` | Adds wires | `connections[]`: `{ from: { component, param }, to: { component, param } }` |
| `grasshopper_configure_components` | Sets flatten/graft, simplify and reverse per parameter, preview, enabled, or bakes to Rhino | `components[]`: `instanceGuid`, `inputs[]`, `outputs[]`, `preview`, `enabled`, `bake` |
| `grasshopper_group_components` | Wraps components in a labelled group | `instanceGuids[]`, `label` |
| `grasshopper_layout_canvas` | Arranges components left to right by data flow | optional `instanceGuids[]` |
| `grasshopper_disconnect_components` | Removes wires | `connections[]` |
| `grasshopper_delete_components` | Deletes components and their wires | `instanceGuids[]` |

All of them also take an optional `session`.

### Creating and wiring components

Give each new component an `id`: a temporary reference that identifies it in the result, where you get the `instanceGuid` to wire it with `grasshopper_connect_components`.

```json theme={null}
{
  "tool": "grasshopper_create_components",
  "args": {
    "components": [
      { "id": "r", "name": "Number Slider", "x": 0, "y": 0, "min": 1, "max": 20, "value": 5 },
      { "id": "c", "name": "Circle", "x": 250, "y": 0 }
    ]
  }
}
```

### Script components

For `grasshopper_create_python_script_components`, each input takes a `name`, an `access` of `"item"`, `"list"` or `"tree"`, an optional `typeHint` (`"int"`, `"float"`, `"str"`, `"bool"`) and `optional`. Outputs take a `name` and `access`. To update a script component, pass its `instanceGuid` as `id`: the fields you give replace the existing ones, and `inputs` and `outputs` replace the whole list.

Run `runchat use_skill --name grasshopper-canvas` for the full reference agents use.

## Blender

### `run_blender_command`

Runs Python in the connected Blender, with `bpy` available.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `code` | `string` | yes | The Python source. `print()` output is returned |
| `reason` | `string` | no | A short note for the log |

Returns `success`, `message` and the console output. Avoid code that blocks Blender's main thread for a long time, such as renders or heavy loops.

## Revit and ArchiCAD

Revit and ArchiCAD are scripted through Code nodes rather than a dedicated tool. Create a Code node with `language` set to `revit-csharp` or `archicad-python` (see [`create_code_node`](https://docs.runchat.com/api-reference/canvas-tools#create_code_node)) and run it with [`run_nodes`](https://docs.runchat.com/api-reference/canvas-tools#run_nodes). The script runs in the connected app.

## Screenshots

### `take_screenshot`

Captures the viewport of a connected app. Over MCP the image is attached to the agent's next turn so it can see the result.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `host` | `"rhino"` \| `"revit"` \| `"blender"` \| `"archicad"` \| `"sketchup"` | no | Which app to capture. Default: the most recently connected |
| `session` | `string` | no | Session id to target |
| `compare_to` | `string` | no | An image URL to attach beside the capture, such as a reference you are modelling from |
| `view` | `string` | no | Rhino: viewport, layout or named view. Default: the active view |
| `display_mode` | `string` | no | Rhino: `"Shaded"`, `"Rendered"`, `"Arctic"`, `"Technical"`, `"Wireframe"`, … |
| `camera_location` | `number[3]` | no | Rhino: camera position |
| `camera_target` | `number[3]` | no | Rhino: the point the camera looks at |
| `frame` | `string` | no | Rhino: zoom to `"all"`, `"selection"` or comma-separated object ids |
| `width`, `height` | `number` | no | Rhino: image size, 64 to 2048 pixels |

In Rhino the settings apply to this capture only and the user's view is restored afterwards. Set `host` after scripting a specific app, so the capture comes from that app rather than whichever connected last.

## CAD tools

CAD tools are Rhino toolbar buttons published as artifacts. See [Rhino tools](https://docs.runchat.com/concepts/integrations/rhino-tools.md).

| Tool | What it does | Parameters |
| - | - | - |
| `install_cad_tool` | Adds a CAD tool to the user's Rhino toolbar. It appears within a few seconds while the Runchat panel is open | `artifact_id` |
| `uninstall_cad_tool` | Removes it from the toolbar. The artifact is not deleted | `artifact_id` |

Tools you create are installed for you already; use `install_cad_tool` for a teammate's or a public one.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.