Skip to main content
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. The workspace is the membrane: changes accumulate there, 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 membrane, 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

ToolWhat it does
penumbra_workspace_openStart a staging workspace.
penumbra_workspace_hydrateLoad existing entities into the workspace so you can edit them.
penumbra_workspace_readRead the current staged state of the workspace.
penumbra_workspace_modifyAdd or change staged entities and writes.
penumbra_workspace_validateCheck staged changes against the types’ adherence modes.
penumbra_workspace_submitCommit the staged changes to the graph.
penumbra_workspace_closeClose the workspace without committing.
penumbra_workspace_listList 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

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

​
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.
  • 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.