Connect the runtime MCP

The runtime Penumbra MCP lets an AI agent operate a live graph from inside its client. Connect it once and the penumbra_* tools appear in the session: the agent can inspect a project’s shape, search entities and sources, walk relationships, read by id, retrieve over source chunks, and stage structured writes. This is the agent-facing surface. It is governed by the same shapes and the same staging workspace the rest of the platform uses, so writes are reviewed before they commit.

Endpoint

The runtime MCP is a hosted SSE endpoint.

https://mcp.getpenumbra.ai/sse

Authenticate

The server uses OAuth. Your client opens a browser consent flow and Penumbra issues a token for the session, so you do not put a key in the config. The first time the agent calls a penumbra_* tool, the client walks you through the login.

Access is tiered. Tokens are scoped to an org or a project, and some tools are admin-only and can be gated. If a tool is outside your tier you will see an access-tier prompt rather than a result.

Add it to your client

Claude Code
Claude Desktop
Cursor

Add the server from the command line:

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

Run a Penumbra tool and the client walks you through the browser login.

Add the server to your MCP config:

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

Restart the app, then trigger a Penumbra tool to start the browser login.

Add the server to your MCP config:

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

Reload, then trigger a Penumbra tool to start the browser login.

Confirm the tools are there

Once connected, the penumbra_* tools appear in the client. You should see the following.

Tool	What it does
`penumbra_introspect`	Inspect the active project’s shape and types
`penumbra_omnisearch`	Search across entities and sources
`penumbra_traverse`	Walk relationships
`penumbra_read`	Read entities or sources by id
`penumbra_source_rag`	Retrieve over source chunks
`penumbra_capture`	Stage a structured entity
`penumbra_list_projects`	List projects you can reach
`penumbra_list_shapes`	List the shapes in a project
`penumbra_list_sources`	List a project’s sources
`penumbra_project_manifest`	Read a project’s manifest
`penumbra_context_get` / `penumbra_context_set`	Get or set the active project and context
`penumbra_workspace_*`	The staging-workspace lifecycle for governed writes
`penumbra_agent_feedback`	Send feedback from the agent

The workspace lifecycle is a set of tools, penumbra_workspace_open, read, modify, validate, submit, close, hydrate, and list, that governs writes. Captures and edits stage in a workspace before they commit.

How the agent sees your graph

The data model is the same one the rest of Penumbra uses:

Shape defines an ontology. Each shape has entity types, each type has properties and relationships to other types.
Types carry semantic anchors and an adherence mode, strict or loose, that governs how closely captured entities must match the type.
A traversal grammar governs which relationship walks are allowed, so penumbra_traverse follows the graph’s own rules.
Writes stage through a workspace (the membrane) before they commit. The agent opens a workspace, makes changes, validates, then submits.

A good first move after connecting is to call penumbra_context_get to see the active project, then penumbra_introspect to read its shape. From there the agent knows what it can search for and what it can capture.

Explore and retrieve

Inspect, search, traverse, read, and retrieve over a live project.

Capture and writes

Stage structured entities and run the workspace lifecycle.

​Endpoint

​Authenticate

​Add it to your client

​Confirm the tools are there

​How the agent sees your graph

​Next

Explore and retrieve

Capture and writes

Endpoint

Authenticate

Add it to your client

Confirm the tools are there

How the agent sees your graph

Next