The Shapes Workbench

The MCP surface for authoring shapes: open a session in new, edit, fork, or inspect mode, model types and relationships, and preview the exact tool surface the runtime will see.

The Shapes Workbench is an MCP server you connect to your AI client to author shapes. A shape is the type model that governs a project’s graph: its entity types, their properties, and the relationships between them. You design that model here, and it compiles into the tool surface your runtime agents use.

This page is the surface tour: how a session works, the four modes you open it in, what you can edit, and the one idea that makes the Workbench worth understanding before you start — the tools your shape exposes to agents.

The Workbench is the design-time half of Penumbra. To set up the connection, see Connect. For the full tool-by-tool reference, see Authoring.

Connect first

The Workbench is a remote MCP server. Add it to your client, and the shape_workbench_* tools appear in your session.

https://shapes.pnbr.io/mcp

It accepts a Penumbra API key (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 with shape_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.

fork does not edit the source shape. It produces a new, independent shape derived from it. Use edit when you mean to change the shape you opened; use fork when you want a divergent copy.

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_rename_relationship	Rename a relationship while preserving its identity.
shape_workbench_reserve_relationship	Remove a relationship and reserve its name (requires a rationale).
shape_workbench_remove_relationship	Remove a relationship.

The tools your shape exposes

This is the key idea. A shape compiles into the tools agents use at runtime. 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: the tools and fields runtime agents (and any generated tools) will see once this shape is live. Run it before you materialize, and you see your model from the agent’s point of view, not just as a schema.

Preview the tools before you commit. The model that reads clean as a schema is not always the model that gives agents the tools you want. The preview closes that gap.

Compile, diff, and version

Tool	What it does
shape_workbench_compile	Compile the draft to validate it and get its 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 tools look 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 tools you previewed become the ones runtime agents actually use. See Materialize.

A typical pass

1. Open

   shape_workbench_open in new, edit, fork, or inspect mode.

2. Model

   Add types and properties, then connect them with relationships.

3. Compile

   shape_workbench_compile to validate and get version hashes.

4. Preview the tools

   shape_workbench_preview_operating_surface to see exactly what runtime agents and generated tools will see.

5. Materialize

   shape_workbench_materialize to commit the shape to its project.

Next

Connect the MCP

Endpoint, key or OAuth, and client config.

Author shapes

The full tool reference and a worked session.