Skip to main content
The Penumbra runtime MCP lets an AI agent operate a live graph from inside its client. This page covers the read and retrieve tools: how to inspect what a project knows, search it, walk its relationships, and pull source text. Writes are covered separately under Capture and stage.

​
Connect

The runtime MCP is a hosted SSE endpoint at https://mcp.getpenumbra.ai/sse. It uses OAuth, so the first connection opens a browser consent flow. 
claude mcp add --transport sse penumbra https://mcp.getpenumbra.ai/sse
Access is tiered. Tokens are scoped to an org or a project, and some tools are admin-only. A builder calling a gated tool may hit an access-tier prompt rather than a result.

​
Mental model

The read tools are precise because the graph is typed. A few terms make the tool calls land where you expect.
  • Shape → entity type → property → relationship. A shape defines the entity types in a project, each type’s properties, and the relationships that connect types. When you introspect a project, this is what you get back.
  • Semantic anchors. Types and properties carry semantic anchors — the meaning the type is bound to. This is why search and traversal can be specific to a type rather than free-text matching alone.
  • Adherence mode. Each type is either strict or loose. Strict types hold a tight contract on their properties; loose types tolerate more variation. Knowing the mode tells you how reliable a property is when you read it.
  • Traversal grammar. Walks aren’t arbitrary graph crawls. The traversal grammar governs which relationships you can follow from a given type, so penumbra_traverse moves along defined edges.
Reading is non-destructive. Writes go through a separate staging workspace before they commit.

​
The read and retrieve tools

ToolWhat it does
penumbra_introspectInspect the active project’s shape and types
penumbra_omnisearchSearch across entities and sources
penumbra_traverseWalk relationships from an entity
penumbra_readRead entities or sources by id
penumbra_source_ragRetrieve over source chunks
Supporting tools for orientation: penumbra_list_projects, penumbra_list_shapes, penumbra_list_sources, penumbra_project_manifest, and penumbra_context_get / penumbra_context_set to read or set the active project.

​
Start by setting context

Most read tools operate against the active project. Confirm or set it first.
1

See where you are

Call penumbra_context_get to read the active project and context.
2

List what's available

Call penumbra_list_projects if you need to pick a different project.
3

Switch if needed

Call penumbra_context_set to make another project active.

​
penumbra_introspect

Use penumbra_introspect to see the active project’s shape and types before you search or traverse. It tells you which entity types exist, their properties, their adherence mode, and the relationships that connect them — the map you need to write good queries.
Introspect first. Knowing the type and relationship names up front makes penumbra_omnisearch and penumbra_traverse calls precise instead of speculative.

​
penumbra_omnisearch

Use penumbra_omnisearch to find things across both committed entities and ingested sources. This is the entry point when you have a topic or name but not an id.

​
penumbra_traverse

Once you have an entity, use penumbra_traverse to follow its relationships. Traversal respects the grammar, so you move along the relationships the shape actually defines.

​
penumbra_read

Use penumbra_read to fetch entities or sources by id — for example, an id returned from omnisearch or a relationship target returned from traverse.

​
penumbra_source_rag

Use penumbra_source_rag to retrieve over the chunked text of sources. Where omnisearch finds which entities and sources are relevant, source RAG pulls the underlying passages so the agent can read and quote the original material.

​
A typical exploration flow

1

Orient

penumbra_context_get, then penumbra_introspect to learn the types and relationships.
2

Find an anchor

penumbra_omnisearch for the topic or name to get candidate entities and sources.
3

Read it

penumbra_read on the best id to load the full entity or source.
4

Expand

penumbra_traverse from that entity to pull related entities along defined relationships.
5

Ground in text

penumbra_source_rag to retrieve the source passages that back up what you found.

​
Example agent prompts

Drop these into an agent that has the Penumbra MCP connected.
Orient in a project
First, set context: call penumbra_context_get to confirm the active project.
Then call penumbra_introspect and summarize the entity types, their adherence
modes, and the relationships between them. Tell me what this project is about.
Find and read
Use penumbra_omnisearch to find anything about "onboarding flow" across
entities and sources. Pick the most relevant result and penumbra_read it by id.
Quote the fields that matter.
Walk the graph
Find the entity for "Acme Corp" with penumbra_omnisearch, read it, then use
penumbra_traverse to list everything related to it. Group the results by
relationship type.
Retrieve over sources
Use penumbra_source_rag to retrieve passages about "data retention policy".
Answer my question using only those passages and cite the source for each claim.

​
Working across planes

Reads default to the semantic plane — the canonical graph. Two other planes matter when you read:
  • memory — recall defaults here. Memory writes and reads land on this plane.
  • archival — older or retired material.
A meta plane exists for hidden internal data and isn’t something you read directly. The memory system shape ships preloaded. Its memory type carries content (required), kind (preference, decision, fact, lesson, observation, signal), domain, scope (agent, commons, project), date_observed, source_context, and expiry, with ABOUT and SUPERSEDED_BY edges. The research shape ships with types inquiry, source, evidence, finding, open_question, and research_note. Use penumbra_list_shapes to see what’s loaded in your project and penumbra_introspect to see the live type definitions.

​
Next