Capture and governed writes

Stage structured entities and graph writes through a workspace that commits only on submit.

Reads from the Penumbra MCP server are direct. Writes are not. Every write an agent makes — a captured entity, an edit to existing data — stages through a workspace before it reaches the graph. Changes accumulate in the workspace, get validated, and commit only when you submit. Nothing your agent does touches the live graph until that moment.

This page covers the two write paths:

• penumbra_capture — stage a single structured entity.
• Workspace lifecycle — open a staging workspace, modify it, validate it, and submit to commit.

Connect the server first. See Connect an agent for install steps. In short:

claude mcp add --transport sse penumbra https://mcp.getpenumbra.ai/sse

For JSON-config clients:

{ "mcpServers": { "penumbra": { "url": "https://mcp.getpenumbra.ai/sse" } } }

The data model

Before you write, know the shape of what you’re writing into:

• A shape defines an entity type.
• An entity type carries properties and relationships.
• Each type has an adherence mode — strict or loose — that governs how closely captured data must match the type.

A strict type rejects data that doesn’t conform. A loose type tolerates more variation. Validation results depend on the type’s mode, so inspect the type before you write.

Run penumbra_introspect to inspect the active project’s shape, types, and properties. This tells you what types exist and what each one expects — so your captures land cleanly instead of failing validation.

Set the active context

Writes land in the active project. Confirm or set it before you stage anything.

1. Check the current context

   Call penumbra_context_get to see the active project and context.

2. Set it if needed

   Call penumbra_context_set to switch the active project. Use penumbra_list_projects first if you need the project’s identity.

3. Inspect the target types

   Call penumbra_introspect to confirm the entity types and properties you’re about to write into.

Stage a single entity with penumbra_capture

penumbra_capture stages one structured entity. It does not write directly to the graph — it puts the entity into staging, where it waits for review and commit. This is the fast path for a single, well-formed entity.

Use it when:

• You have one entity to record and you know its type.
• You want the simplest write path without managing a workspace yourself.

The capture is governed the same way as any other write: it passes through the workspace, not around it.

A capture being accepted means it was staged, not that it is live in the graph. Staged writes are reviewed before they commit. Don’t report a capture as “saved to the graph” until it has committed.

Stage multiple writes with a workspace

When you have more than one change to make — several entities, edits to existing data, or writes you want to validate together — open a workspace. The workspace holds your changes as a batch, lets you read and modify them, validates the whole set, and commits everything on submit.

The lifecycle

Tool	What it does
penumbra_workspace_open	Start a staging workspace.
penumbra_workspace_hydrate	Load existing entities into the workspace so you can edit them.
penumbra_workspace_read	Read the current staged state of the workspace.
penumbra_workspace_modify	Add or change staged entities and writes.
penumbra_workspace_validate	Check staged changes against the types’ adherence modes.
penumbra_workspace_submit	Commit the staged changes to the graph.
penumbra_workspace_close	Close the workspace without committing.
penumbra_workspace_list	List open workspaces.

The flow

1. Open a workspace

   Call penumbra_workspace_open to start a staging session. This is where changes accumulate.

2. Hydrate, if you're editing existing data

   To change entities that already exist, call penumbra_workspace_hydrate to pull them into the workspace. Skip this step if you’re only adding new entities.

3. Modify

   Call penumbra_workspace_modify to stage your changes — new entities, edits, relationships. Use penumbra_workspace_read at any point to see the current staged state.

4. Validate

   Call penumbra_workspace_validate to check the staged set against the target types. Fix anything that fails before you submit. Validation reflects each type’s strict or loose adherence mode.

5. Submit to commit

   Call penumbra_workspace_submit. This is the moment the writes leave staging and land in the graph. Before this, nothing committed.

6. Close

   The workspace closes on a successful submit. If you decide not to commit, call penumbra_workspace_close to discard the staged changes and leave the graph untouched.

Validate before you submit. penumbra_workspace_validate is your chance to catch type mismatches while the changes are still staged and reversible. After penumbra_workspace_submit, they’re committed.

Capture vs. workspace: which to use

penumbra_capture

Reach for penumbra_capture when you have one entity and want the shortest path. It stages a single structured entity through the workspace. No workspace to manage, no explicit submit step to orchestrate.

Workspace lifecycle

Reach for the workspace when you have multiple changes, are editing existing entities (hydrate them first), or want to validate a batch before committing. You control when the set commits via penumbra_workspace_submit.

A practical agent workflow

A typical write session, end to end:

1. Orient

   penumbra_context_get to confirm the active project, then penumbra_introspect to learn the available types and their properties.

2. Open and stage

   penumbra_workspace_open, then penumbra_workspace_modify to stage your entities. Hydrate first with penumbra_workspace_hydrate if you’re editing existing data.

3. Verify

   penumbra_workspace_read to review the staged state, then penumbra_workspace_validate to check it against the types.

4. Commit

   penumbra_workspace_submit to commit. The writes are now in the graph.

After committing, read your writes back with penumbra_read or penumbra_omnisearch to confirm they landed as expected.

Access tiers

Tokens are scoped to an org or a project, and that scope determines what you can write. Some tools are admin-only and can be gated — if your token doesn’t carry the required tier, a write tool may return an access-tier prompt instead of staging your change. If you hit one, you need a token with broader scope or admin access for that operation.

Send feedback

If a write tool behaves unexpectedly, call penumbra_agent_feedback to report it from inside the session.

Related

• Connect an agent — install and authenticate the Penumbra MCP server.
• Read and search — the read-side tools (penumbra_omnisearch, penumbra_traverse, penumbra_read, penumbra_source_rag).
• Shapes overview — entity types, properties, relationships, and adherence modes.