Build an interview agent

This build gives an AI agent a live graph to write into. You connect the runtime Penumbra MCP to Claude Code or Cursor, point the agent at a person or a topic, and it records what it learns as structured entities using the preloaded research shape. The result is not a transcript. It is a structured graph governed by the research shape, queryable the moment the interview ends. See shapes overview for what “governed” buys you.

This page covers the runtime MCP, which operates a live graph from inside your client. It is separate from the design-time Shapes Workbench. Prerequisite setup for connecting an agent to Penumbra lives in Connect an agent.

What the agent works with

The runtime MCP exposes a fixed set of tools. The interview agent reads with a few and writes with one.

Tool	Use
`penumbra_introspect`	Inspect the active project’s shape, types, and properties
`penumbra_list_projects`	List projects the token can reach
`penumbra_list_shapes`	List shapes available in the active project
`penumbra_list_sources`	List sources attached to the project
`penumbra_context_get` / `penumbra_context_set`	Get or set the active project and context
`penumbra_project_manifest`	Read the project’s manifest
`penumbra_omnisearch`	Search across entities and sources
`penumbra_traverse`	Walk relationships between entities
`penumbra_read`	Read entities or sources by id
`penumbra_source_rag`	Retrieve over source chunks
`penumbra_capture`	Stage a structured entity into the graph
`penumbra_agent_feedback`	Send feedback from the agent

For governed multi-entity writes there is a staging-workspace lifecycle: penumbra_workspace_open, penumbra_workspace_read, penumbra_workspace_modify, penumbra_workspace_validate, penumbra_workspace_submit, penumbra_workspace_close, penumbra_workspace_hydrate, and penumbra_workspace_list. A single interview turn can stay on penumbra_capture, which stages one entity at a time.

Mental model: a shape defines entity types, each type has properties and relationships, and every write stages through a workspace membrane before it commits. penumbra_capture is the one-entity door into that membrane.

The research shape

The research shape ships preloaded. The interview agent captures into its types as it works:

Type	What it holds
`inquiry`	The question or line of investigation driving the interview
`source`	A person, document, or origin a finding came from
`evidence`	A quote, data point, or observation that supports something
`finding`	A conclusion the agent reached
`open_question`	Something unresolved, to follow up on
`research_note`	A working note that does not fit the other types

Each type carries semantic anchors and an adherence mode (strict or loose) that governs how closely a captured entity must match the type. Run penumbra_introspect first so the agent sees the exact property names before it captures.

Connect the runtime MCP

The runtime MCP is a remote server at https://mcp.getpenumbra.ai/sse. It uses OAuth: your client opens a browser consent flow on first connect, and the resulting token authorizes the session.

Claude Code
Cursor / JSON

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

The first tool call triggers the browser consent flow. Approve it, and the penumbra_* tools appear in your session.

Add to your MCP config:

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

Reload the client. It opens the consent flow when the server first connects.

Access is tiered. Tokens are scoped to an org or a project, and some tools are admin-only and can be gated. If a call returns an access-tier prompt, your token does not reach that tool or that project. The read-and-capture loop below works on a standard project-scoped token.

Run the interview

Set the working project

Have the agent confirm where it is writing. List projects, then set the active one.

List my projects with penumbra_list_projects, then set the active project to
"Customer Discovery" with penumbra_context_set.

Introspect the research shape

Before capturing, the agent reads the shape so it uses the right types and property names.

Call penumbra_introspect and confirm the research shape is active. List its
types and the properties on inquiry, source, evidence, finding, and
open_question.

Interview or research, capturing as you go

Give the agent the subject and tell it to capture each unit of meaning into the right research type with penumbra_capture.

Interview me about how our team currently handles incident response. Ask one
question at a time. As we go, use penumbra_capture to record:
- the question driving each thread as an `inquiry`
- me as a `source`
- each concrete quote or fact I give you as `evidence`
- any conclusion you reach as a `finding`
- anything unresolved as an `open_question`

For topic research instead of a live interview, point the agent at existing material first: penumbra_omnisearch and penumbra_source_rag find what is already in the graph, penumbra_traverse and penumbra_read follow and expand it, then penumbra_capture records what it concludes.

Review what landed

Captured entities stage through the workspace membrane. Confirm them with a search.

Run penumbra_omnisearch for the findings and open questions you just captured
and show me what is in the graph.

What you end up with

A graph, not a document. The inquiry that started a thread links to the source that answered it, the evidence that backs it, and the finding it produced, with open_question entities flagging what is still loose. Because the research shape governs every entity, the next agent or query reads a typed structure instead of re-parsing prose. The same shape that governed the write governs the read.

Connect an agent

Prerequisite setup for wiring an AI agent to Penumbra.

Shapes overview

How shapes govern the types, properties, and relationships in your graph.

​What the agent works with

​The research shape

​Connect the runtime MCP

​Run the interview

​What you end up with

​Next

Connect an agent

Shapes overview

What the agent works with

The research shape

Connect the runtime MCP

Run the interview

What you end up with

Next