The runtime Penumbra MCP server lets an AI agent operate a live graph from inside your client. The server runs at https://mcp.getpenumbra.ai/sse and authenticates with OAuth (browser consent on first connect).
This page lists every tool, grouped by purpose. For setup, see Connect an agent.
Connect
claude mcp add --transport sse penumbra https://mcp.getpenumbra.ai/sse
Mental model
Before you call a tool, hold the data model in your head:
- A shape defines one or more entity types.
- Each type has properties and relationships.
- Types carry semantic anchors and an adherence mode (
strict or loose).
- A traversal grammar governs how you walk relationships.
- Writes stage through a workspace — the membrane — before they commit.
Access is tiered. Tokens are org- or project-scoped, and some tools are admin-only and can be gated. As a builder, you may hit an access-tier prompt when calling a gated tool.
Discover and introspect
Find out what’s available and set the project you’re working in.
| Tool | What it does |
|---|
penumbra_introspect | Inspect the active project’s shape and types. |
penumbra_list_projects | List the projects you can access. |
penumbra_list_shapes | List the shapes available in the active project. |
penumbra_list_sources | List the sources in the active project. |
penumbra_project_manifest | Get a manifest of the active project. |
penumbra_context_get | Get the active project and context. |
penumbra_context_set | Set the active project and context. |
Start a session by calling penumbra_context_set to pick a project, then penumbra_introspect to learn its types before you search or write.
Retrieve
Read entities and sources, and search across the graph.
| Tool | What it does |
|---|
penumbra_omnisearch | Search across entities and sources. |
penumbra_traverse | Walk relationships from one entity to others. |
penumbra_read | Read entities or sources by id. |
penumbra_source_rag | Retrieve over source chunks. |
Write and workspace
Writes don’t go straight to the graph. You stage them in a workspace, validate, then submit. This is the staging-workspace lifecycle for governed writes.
| Tool | What it does |
|---|
penumbra_capture | Stage a structured entity. |
penumbra_workspace_open | Open a staging workspace. |
penumbra_workspace_read | Read the current contents of a workspace. |
penumbra_workspace_modify | Modify staged contents in a workspace. |
penumbra_workspace_validate | Validate staged contents against the shape. |
penumbra_workspace_submit | Submit the workspace for commit. |
penumbra_workspace_close | Close a workspace. |
penumbra_workspace_hydrate | Hydrate a workspace with existing data. |
penumbra_workspace_list | List your workspaces. |
penumbra_workspace_validate checks staged contents against the type’s adherence mode. Run it before penumbra_workspace_submit to catch problems while writes are still in the membrane.
Feedback
| Tool | What it does |
|---|
penumbra_agent_feedback | Send feedback from the agent. |
