Skip to main content
A shape draft lives in the Shapes Workbench until you materialize it. Before you commit, run a short validation pass: compile the draft, read its diff against the committed version, and preview what runtime agents and tools will actually see. Materialize last, once the surface looks right.
The Workbench MCP server is at https://penumbra-shape-workbench-mcp-server.penumbra.workers.dev/mcp. It accepts a Penumbra API key (pnbr-...) or OAuth. Every tool below is a design-time tool — nothing reaches the runtime until you call shape_workbench_materialize.

​
The workflow: compile early, preview before you materialize

1

Open a draft

Open the shape with shape_workbench_open in new, edit, or fork mode. Use inspect mode to look without editing.
fork creates a separate derived shape, not a new version of the original. Use edit when you want to revise the shape in place.
2

Compile early and often

Run shape_workbench_compile after meaningful edits. It returns the structure, denotative, and operative views plus version hashes, so you catch problems while the draft is cheap to change.
3

Diff against committed

Run shape_workbench_diff to see exactly what your draft changes relative to the committed shape.
4

Preview the runtime surface

Run shape_workbench_preview_operating_surface to see what runtime agents and generated tools will see once you materialize.
5

Materialize

When the diff and the preview both look right, call shape_workbench_materialize to commit the compiled shape to its project.

​
Compile the three views

shape_workbench_compile returns three views of the draft plus version hashes. Read them together — each answers a different question.
ViewWhat it shows
StructureThe types, properties, and relationships as authored.
DenotativeWhat the shape denotes — the meaning surface of the compiled shape.
OperativeHow the shape operates at runtime.
The version hashes let you tell drafts apart and confirm which compiled state you’re looking at. Compile after each round of edits so the hashes and views stay current.
Tool call
shape_workbench_compile
Compile early. The compiled views surface structural problems before you diff or preview, when the draft is still easy to revise.

​
Inspect the draft

shape_workbench_inspect reads the current draft state. Use it to confirm what you’ve authored so far — types, properties, and relationships — before you compile or diff.
Tool call
shape_workbench_inspect
You can also open a shape directly in inspect mode with shape_workbench_open when you want to look at a shape without starting an edit.

​
Diff the draft against committed

shape_workbench_diff compares your draft against the committed version of the shape. This is the change you’re proposing — read it before you materialize so nothing lands by surprise.
Tool call
shape_workbench_diff
Use the diff to confirm that every change is intentional: types you added, properties you renamed or edited, relationships you added or removed. If the diff shows something you didn’t mean to change, go back and fix the draft before continuing.

​
Export the schema

shape_workbench_export_schema exports the draft’s schema. Use it when you want the schema artifact in hand — to review the field-level shape of the data, share it, or check it into a downstream consumer.
Tool call
shape_workbench_export_schema

​
Preview the operating surface

shape_workbench_preview_operating_surface shows exactly what runtime agents and generated tools will see — the shape-to-tools compilation surface. Shapes compile into the runtime tool surface, so this preview is the last check before you commit.
Tool call
shape_workbench_preview_operating_surface
Read this before materializing. It tells you what agents and generated tools will receive once the shape is live, so you can confirm the tool surface matches your intent rather than discovering it after the shape is committed.
Preview is a read of the compilation surface, not the live runtime. It shows what the compiled shape would expose. The shape only reaches runtime once you call shape_workbench_materialize.

​
Materialize

When the diff is clean and the operating-surface preview matches what you want runtime agents and tools to see, commit the draft with shape_workbench_materialize. This materializes the compiled shape to its project.
Tool call
shape_workbench_materialize

​
A tight validation pass

Run this loop on every draft before you commit:
1

Compile

shape_workbench_compile — structure, denotative, operative views and version hashes.
2

Inspect

shape_workbench_inspect — confirm the draft is what you authored.
3

Diff

shape_workbench_diff — confirm every change against committed is intentional.
4

Export schema

shape_workbench_export_schema — review the schema artifact.
5

Preview operating surface

shape_workbench_preview_operating_surface — confirm the runtime tool surface.
6

Materialize

shape_workbench_materialize — commit when the above all look right.
See /shapes/overview for shape concepts and the /agents/connect guide for connecting the runtime tool surface to agents.