Rhino-GH MCP — Example Workflows

Setup Before you start

The server bridges two sides — a Rhino plugin (the rhino_* tools) and a Grasshopper canvas component (the gh_* tools). Both must be live before the agent can read or build anything.

Rhino 8 open, plugin service started — run _ToggleMcpService (listener on 127.0.0.1:9876).
Grasshopper open with the rhino-gh-mcp Server component on the canvas, Run = True (bridge on :9999).
Server registered in your AI client (Claude Desktop / Claude Code) — see the repo README for the config entry.
Sanity check — ask “check the Rhino and Grasshopper connection.” The agent should report gh_status and rhino_status both available.

The key idea The five modes

The canvas component gates what the agent is allowed to do through a single Scenario dropdown. Pick the mode before you prompt — it is the difference between “explain this” and “rebuild this.” The rest of this guide is one chapter per mode; the names below jump to them.

Mode

The agent may…

Reach for it when…

Inspect

read the canvas & document only — no edits

auditing or explaining a definition you were handed

Tune

change slider & parameter values only

iterating a finished definition on its exposed controls

Coach

tune, and add components from the Skill’s allowed set — no scripting

learning — it’s the default; every change is highlighted and explained

Execute

run curated components & scripts

running an existing or plugin workflow end-to-end

Author

add, wire, and script components freely

building a definition from scratch

Gate, not a suggestion

If a call comes back capability denied, the Scenario is too restrictive for what you asked — bump it up and re-prompt. Scope changes to the server component only take effect after a gh_recompute.

Scenario mode · read-only Inspect 1 workflow The agent may read the canvas and document only — it changes nothing. Point it at a definition someone handed you and get back a plain-language account of how it works.

01

Explain a definition

Inspectread-onlyany definition

The fastest way to onboard onto an unfamiliar file — or to audit your own before you hand it off. The agent traces the graph and narrates it; because it can’t touch anything, the output is safe to run on a client’s file.

Prompt · Inspect

Analyze this Grasshopper definition and explain its workflow. Identify the key components, what they control, how data flows through the definition, and what each input slider changes in the final geometry. Summarize the overall logic in clear, simple language.

The definition handed to Inspect — a twisted, notched tower (Polygon → stack → twist → ruled surface → boolean), ungrouped and unlabelled. Inspect reads it as-is and never touches it.

Rendered twisting stack of thin banded surfaces — the geometry the definition produces. — …and the geometry it produces — the twisting stack of banded surfaces. (Shown for context; Inspect only reads the definition, it doesn’t rebuild it.)

Inspect changes nothing on the canvas — the whole deliverable is the written read-out it hands back. Here is the actual response for this definition:

The Inspect chat output: a summary of what the definition builds, an ASCII data-flow pipeline, a numbered step-by-step of the main chain and cutter, a table of what each slider controls, and a plain-language summary. — Verbatim Inspect output — what it builds, the data-flow pipeline, a step-by-step of the main chain + cutter, a table of every slider’s effect, and a plain-language recap. Read-only: it offers to “nudge a slider and recapture,” never doing it unprompted.

Good to know

Inspect is hard-walled to reading. Ask it to “fix” or “tune” and it returns capability denied — that’s your cue to switch to Coach or Tune.
It pairs naturally with Coach: inspect first to understand, then re-open in Coach to reorganize.

Scenario mode · parameters only Tune 1 workflow The agent may change slider and parameter values only — never the topology. You keep the definition you built and re-aim its behavior through the controls it already exposes.

01

Re-aim a perforated facade

Tuneexisting definitionno rewiring

You already have a perforated facade with an attractor curve on the canvas. You don’t want it rebuilt — you want the behavior re-aimed: bigger holes overall, but tightening toward the curve. Tune finds the values that satisfy that intent.

Prompt · Tune

On my current canvas I have a perforated facade with an attractor curve. Change the parameters to make the overall perforations larger, with them getting smaller closer to the attractor curve.

Read the exposed sliders and find which map to hole min / max and the attractor falloff.
Raise the base hole scale, then invert the remap direction so proximity to the curve now shrinks holes rather than growing them.
Recompute and confirm no cell self-intersects at the new maximum.

1Input · before

Top view of the perforated facade before tuning — small, fairly uniform triangular perforations with the attractor curve running through it. — The starting facade — modest, fairly even triangular perforations. The black line is the attractor curve.

re-grade sliders

2Output · after

Top view after tuning — perforations larger overall and tightening toward the attractor curve. — After: perforations larger overall, tightening toward the curve. Slider values only — the definition’s topology is untouched.

Good to know

Tune won’t add or rewire components. If the control you need isn’t already a slider, the agent hits a wall — that’s the signal to move up to Coach or Author.

Scenario mode · the default · edit & narrate Coach 2 workflows The default mode. The agent may tune values and add components from the active Skill’s allowed set — but not script. Every change is highlighted on the live canvas and explained in chat, each reply closing with a structured “What I changed” block — so a fix becomes a lesson, not a black box.

01

Reorganize & document a messy definition

Coachreadability pass~10 min

A working-but-illegible definition, cleaned up without touching what it produces — grouped into named stages, colour-coded, and every slider given a descriptive nickname. The explicit “don’t change the logic” guardrail keeps it a pure readability pass.

Prompt · Coach

In Coach Mode, reorganize this Grasshopper definition by grouping related components into clearly named sections, apply a consistent colour scheme to each stage of the workflow, and rename all number sliders with descriptive nicknames that reflect what they control. Do not change the definition’s logic or outputs — only improve its readability and organization.

Related components collected into named groups, one per workflow stage.
A consistent colour per stage, so the pipeline reads at a glance.
Sliders renamed to what they actually drive — no more Number ×20.
A closing “What I changed” block itemizing every edit; outputs verified identical.

1Before · handed over

The twisted-tower definition in plain grey, ungrouped, every slider labelled Number Slider. — Plain grey, ungrouped, every driver still called “Number Slider.”

reorganize

2After · Coach pass

The twisting banded tower geometry the definition produces, unchanged by the reorganize. — The geometry both versions produce — untouched by the reorganize. Only readability changed; the build is identical.

02

Fix a flagged node — narrated

Coachflagged components2 prompts

The same louver definition applied to two different surfaces — but on the larger one, the components turn red. Coach traces why, fixes it so the large set renders like the small one, and highlights exactly what it touched — then, in the same conversation, re-aims the twist.

Prompt 1 · fix the flagged set

Assess my current Grasshopper script. I’ve applied the same script onto two different surfaces in Rhino, but the script for the larger louver set is showing red components. Find out why and fix it so those louvers render like the first, small louver set. Highlight any changes made.

Prompt 2 · re-aim the twist

Now give these louvers the same incremental turn as the small set — but instead of opening to the right like the small set, make them open to the left.

1Before · flagged

The louvers on the building before the fix — the large set has not built its louvers. — On the building before the fix — the large set isn’t rendering its louvers.

Two louver definitions on one canvas: the Smaller Louver Set resolves; the Large Louver Set has red components near Thickness of Louvers. — …and its script — “Large Louver Set” goes **red** near *Thickness of Louvers*, while “Smaller Louver Set” resolves.

trace & fix

2Output · fixed & re-aimed

The large louver set rendering on the building with the graded twist opening the opposite way. — On the building after — the large set renders, with the graded twist re-aimed to open the other way.

The same canvas after the fix: the large set's corrected region highlighted teal, with yellow annotation notes explaining the change. — …and its script — Coach boxes the corrected region (teal) and drops annotation notes explaining what it changed.

What this teaches

Same script, different surface, red components. A definition that resolves on one surface can flag on another — Coach traces the flagged node upstream to find the cause instead of rebuilding from scratch.
The fix is narrated. Coach highlights the region it changed and annotates it right on the canvas, so you can see — and trust — exactly what moved.
Then keep designing. Once it renders, the same conversation re-aims the result — flipping the incremental twist — without ever leaving the canvas.

Scenario mode · run curated & plugin Execute 1 workflow · 4 parts The agent may run curated components and scripts — including third-party plugins. Proof it drives more than stock Grasshopper: a full Ladybug Tools climate study that ends in a facade answering the wind.

01

Climate analysis → wind-responsive facade

ExecuteLadybug Toolsneeds site model + .epw

Four parts, each its own prompt — the agent builds on the canvas it left. Weather data in, sun and wind analysed on the site, then geometry driven by the findings.

Ladybug canvas: EPW import feeding two sun paths, a wind rose, and Direct Sun Hours, wired into facade louver sliders. — The whole pipeline on one canvas — EPW import → two sun paths + wind rose + Direct Sun Hours → wired into the `[facade]` fin sliders.

Each part below is one prompt and the result it produced, in the order they were run:

Part 1 · Sun path · ~5 min

Based on the existing Rhino site model, show me how the sun moves across this site over the year.

Green annual sun-path dome rendered over the Vancouver site model. — The annual sun path arcing over the site (Vancouver Intl AP).

Part 2 · Direct sun hours · ~6 min

Map the direct sun hours for July 1st on the surfaces under the facade layer.

Direct sun hours mapped as a coloured mesh across the facade — blue for few hours, through yellow, to red for fully exposed — with surrounding context massing. — Direct sun hours on the facade for July 1st: blue (few hours) → yellow → red (fully exposed), with context massing as shading.

Part 3 · Wind rose · ~10 min

Map a wind rose for the building with the listed facade.

Wind rose diagram coloured by wind speed in metres per second. — The wind rose, petals coloured by wind speed (m/s).

Part 4 · Wind-responsive facade · ~20 min

Based on the wind findings, model a vertical louver facade on the existing facade surfaces that helps break up the wind load.

Site model with a red vertical louver facade modeled along one edge in response to wind. — The wind-responsive vertical louver facade, modeled on the facade surfaces.

Traps we hit

If Direct Sun Hours reads 0 everywhere, check your normals. A facade whose normals point into the building reports zero sun even at noon — ray-test the open side and flip it outward before blaming the weather file.
Ladybug lives outside the curated component scope — widen the canvas’s component scope to defaults or all so the agent can place its components. (That’s a different knob from the server’s policy preset — parameter / curated / full — set when the server starts.) Install via Rhino’s _PackageManager (search ladybug-tools).
The heavy LB components are slow to place; expect the agent to verify with gh_canvas_summary instead of re-adding on a timeout.

Scenario mode · build from scratch Author 2 workflows The agent may add, wire, and script components freely — the full build. Two proofs it isn’t facade-specific: a site and a product, both from an empty canvas.

01

Parametric landform

Authorpure native~10 min

A terrain definition that balances drama with buildable flats — and, because it was asked for, explains itself and comes out organized into stages.

Prompt · Author

Generate a realistic landform for a 50 × 50 m site that balances dramatic topography with usable flat areas. Explain how each parameter influences the landscape, and organize the definition into stages.

A native heightfield — layered Lorentzian hills and sine undulation over a grid — with the drivers grouped and labelled so the terrain stays legible and editable. No scripts.

Grasshopper canvas generating a parametric terrain heightfield, organized into labelled stages. — Staged, labelled landform definition — every driver exposed and named.

Rendered 50 by 50 metre terrain mesh with a dramatic central hill and flat surrounds. — The build it produces — a dramatic hill over the 50 × 50 m site, with usable flats around it.

02

Parametric jewelry ring

Author2 iterations~30 min

The same author-a-definition loop at millimetre scale — engraving, adjustable stones, bezels, faceted cuts — built and refined across two prompts.

Prompt · iteration 1

Create a customizable parametric jewelry ring with an engraved pattern and adjustable stone size. Three stones, each smaller than the band width.

Prompt · iteration 2

Add faceted brilliant-cut gems, standing on bezels.

Grasshopper canvas of the parametric jewelry ring — grouped Parameters, Band pipe-torus, engraved pattern, stone placement, size clamp, and faceted gems with bezels. — The ring definition — grouped Parameters → Band (pipe torus) → Engraved pattern → Stone placement → size clamp `Min(x, 0.9·y)` → Faceted gems + bezels.

1Iteration 1 · band + stones

Ring iteration 1 — an engraved band with three round bezel-set stones. — Engraved band with three bezel-set round stones.

add faceted gems

2Iteration 2 · gems on bezels

Ring iteration 2 — rendered gold ring with three blue faceted brilliant-cut gems on bezels. — Faceted brilliant-cut gems standing on the bezels — the finished ring.

Good to know

Author is the widest gate — it can script. It shouldn’t reach for one first, though: if a native recipe exists, that’s the build (see Traps).

Capstone · one object, every mode Cross-scenario 1 object · 4 modes The clearest way to feel the scenario dial: take a single object — a twisted, perforated lantern — and walk it through Author → Coach → Tune → Inspect. Same canvas, four completely different jobs.

Author · build itnative only~6 min

An elliptical profile (Rx ≠ Ry so the twist reads) that rotates as it rises, lofted into a body, then opened into a continuous perforated shell with attractor-graded holes. Pure native components.

Prompt · Author

Generate a twisted parametric lantern with perforated patterns.

Profile + twist — Ellipse → Rotate Axis (angles from Range 0…twist) → Move up (Unit Z factors) into a stacked, progressively rotated stack.
Body — Loft the profiles into one untrimmed surface.
Panel grid — Divide Domain² → Isotrim cells → Area centroids.
Hole sizing — Distance centroid→attractor → Bounds → Remap into a (min, max) hole scale.
Perforated shell — per cell: naked Brep Edges → Join = outer boundary; Scale about centroid = hole; Loft [outer, inner] = an open frame. Adjacent frames share edges, so it reads as one continuous pierced shell.

The staged canvas — Profile Radius 25/16 · Height 120 · Twist 200° · 16 profiles · 24 × 30 holes · hole scale 0.20–0.85.

Rendered twisted lantern with a regular square grid of perforations. — Result — the Author build: a square grid of holes across the twisted shell.

Coach · change it, narrated~7 min

Re-pattern the shell — but have the agent show its work. The changed components are highlighted on the live canvas and the reply ends with a “What I changed” block.

Prompt · Coach

As coach, I now want you to change the perforations to be circular and more dense across the surface. Highlight the components added, and use the Grasshopper canvas to walk me through the changes made.

Rendered lantern after Coach edit — perforations now circular and packed more densely. — Result — holes reworked to circular and packed denser across the shell.

Tune · dial it in~2 min

The fastest loop of the four. No topology change — only the sliders the definition already exposes, hunting for the values that satisfy “bigger, but don’t let holes collide.”

Prompt · Tune

In Tune, adjust the sliders to make the lantern more twisted with a larger radius. I also want the circular perforations to be as large as they can without intersecting one another.

Rendered lantern after tuning — more twist, larger radius, holes opened to their maximum. — Result — more twist and a larger radius, holes opened to the edge of touching.

Inspect · explain it~20 min

Hand the finished canvas to someone who’s never seen it. Inspect touches nothing — it reads the graph and explains the data flow, which components drive what, and what each slider does.

Prompt · Inspect

Explain this definition to me.

The Inspect chat output for the lantern — a big-picture summary, the eleven driving sliders with current values, a five-stage walkthrough of the definition, and gotchas worth knowing. — The read-out it returns — a plain-language big picture, the eleven sliders and their current values, a five-stage walkthrough (Profile + Twist → Panel Grid → Hole Size → Circles → Perforated Shell), and gotchas like the vertical-only twist and the inverted U/V labels.

…plus tables summarizing the key design elements — their corresponding components and the parameters they’re set to:

Parameters table — the eleven sliders with value, range, and what each controls. — The parameters table — every slider with its current value, range, and what it drives.

Component pipeline table — each stage, its components, input to output, and purpose. — The component-pipeline table — each of the five stages, its components, the input → output, and its purpose.

Reference Traps we hit

Hard-won across the sessions above. Read these once and you’ll skip most of the dead ends.

Working with the canvas

Start with a summary when a definition already exists. Before touching an unfamiliar canvas, ask the agent to summarize the definition first — it forces the MCP to actually read and understand the base it’s working from, so its edits build on what’s already there instead of guessing at intent.
Don’t retry timeouts blindly. When the 3D preview is heavy, group / panel / component adds can time out on the MCP side yet still land on the canvas. A blind retry makes duplicates — verify with gh_canvas_summary first.
Tag and name your sliders. Give the controls that matter descriptive, prefixed nicknames — [facade] fin_depth, [site] slope, [twist] max_angle — instead of a wall of “Number Slider.” Labelled sliders make manual tuning far faster, and they let a later pass in another mode (a Tune sweep, a Coach edit) find and adjust — or clear — a whole subsystem in one go rather than guessing which grey node does what.

Native first — when scripting is actually warranted

The agent will sometimes jump to a Python script even when a native recipe exists. If a typology has a recipe, the recipe is the build — “smooth random”, “evenly spaced”, “wavy”, “attractor-driven” all have native graphs.
Reserve scripting for the genuine cases: (a) Voronoi/Delaunay with > 50 sites where graph nodes flood the canvas, (b) image-driven attractor fields, (c) RhinoCommon-only operations (e.g. Mesh.CreateFromBrep).