Connect first
The Workbench is a remote MCP server. Add it to your client, and theshape_workbench_* tools appear in your session.
pnbr-...) as a bearer token, or OAuth for
clients that support remote-MCP login. The Connect page has
the per-client config.
Sessions and modes
Everything you do in the Workbench happens inside a session. You open one withshape_workbench_open, edit a draft, compile to check it, and materialize when
you are satisfied. The draft does not touch the live graph until you materialize.
You open a session in one of four modes:
| Mode | What it does |
|---|---|
new | Start a fresh shape from nothing. |
edit | Open an existing shape to change it in place. |
fork | Create a separate derived shape from an existing one. The original is untouched. |
inspect | Open a shape read-only to look at it. |
What you shape
Inside a session you model three things: types, the properties on them, and the relationships that connect them.Types and properties
| Tool | What it does |
|---|---|
shape_workbench_add_type | Add an entity type. |
shape_workbench_edit_type | Edit a type. |
shape_workbench_edit_property | Edit a property on a type. |
shape_workbench_rename_property | Rename a property. |
shape_workbench_reserve_property | Reserve a property name. |
Relationships
| Tool | What it does |
|---|---|
shape_workbench_add_relationship | Add a relationship between types. |
shape_workbench_edit_relationship | Edit a relationship. |
shape_workbench_remove_relationship | Remove a relationship. |
The operating surface
This is the key idea. Shapes compile into the runtime tool surface. The types, properties, and relationships you define here become the tools and structure that runtime agents and generated tools operate against. You are not just describing data; you are defining what an agent downstream is able to do.shape_workbench_preview_operating_surface shows you exactly that. It renders the
shape-to-tools compilation surface: precisely what runtime agents and generated
tools will see once this shape is live. Run it before you materialize, and you
see the consequence of your model from the agent’s point of view, not just the
schema’s.
Preview the operating surface before you commit. The model that reads clean as
a schema is not always the model that produces the tool surface you want. The
preview closes that gap.
Compile, diff, and version
| Tool | What it does |
|---|---|
shape_workbench_compile | Compile the draft. Returns structure, denotative, and operative views plus version hashes. |
shape_workbench_inspect | Inspect the current draft state. |
shape_workbench_export_schema | Export the compiled schema. |
shape_workbench_diff | Diff the draft against the committed shape. |
shape_workbench_project_grammar | Inspect the project’s grammar. |
shape_workbench_version_graph | View the shape’s version history. |
shape_workbench_assert_version_alignment | Confirm a session is aligned to a version. |
shape_workbench_plan_migration | Plan a migration between versions. |
shape_workbench_access_status | Check what you can edit in this session. |
Materialize
When the model compiles cleanly and the operating surface looks right,shape_workbench_materialize commits the compiled shape to its project. That is
the handoff to run time: the shape now governs the project’s graph, and the tool
surface you previewed becomes the one runtime agents actually use. See
Materialize.
A typical pass
Preview the operating surface
shape_workbench_preview_operating_surface to see exactly what runtime agents
and generated tools will see.Next
Connect the MCP
Endpoint, key or OAuth, and client config.
Author shapes
The full tool reference and a worked session.