This page assumes the runtime MCP is already connected. To connect it, see /agents/connect.
Where the active project comes from
The MCP resolves the active project from your session context. You can read it, set it, and switch it at any time:| Tool | What it does |
|---|---|
penumbra_context_get | Read the current active project and context. |
penumbra_context_set | Set the active project / context for the session. |
penumbra_list_projects | List the projects your token can reach. |
penumbra_project_manifest | Inspect one project before you commit to it. |
penumbra_introspect, penumbra_omnisearch, penumbra_traverse, penumbra_read, penumbra_source_rag, penumbra_capture, and the workspace lifecycle) all operate against it.
Pick a project
See what you can reach
List the projects your token has access to.The result is scoped to your token. An org-scoped token sees the org’s projects; a project-scoped token sees only the project it was issued for.
Inspect a candidate
Before committing, pull the manifest for a project to confirm it’s the one you want.Use this to check the project’s identity and surface before you start reading or writing against it.
Set it active
Make the project active for the session.From here, every working tool resolves against this project.
Get oriented in the active project
Once the project is active, learn its shape before you search or write:penumbra_introspect— inspect the active project’s shape, types, and properties.penumbra_list_shapes— list the shapes defined in the project.penumbra_list_sources— list the sources attached to the project.
strict or loose), and a traversal grammar governs how penumbra_traverse walks relationships. Introspect first so your searches and captures line up with the project’s real types.
Tokens are org- or project-scoped
Your OAuth token determines what you can reach:- An org-scoped token can list and switch among the org’s projects.
- A project-scoped token is bound to a single project.
penumbra_list_projects returns fewer projects than you expect, or penumbra_context_set won’t move you to a project you know exists, your token is narrower than that project. You need a token with the right scope rather than a different tool call.
Access tiers and gated tools
Access is tiered. Beyond token scope, some tools are admin-only and can be gated behind an access-tier prompt. When you call a gated tool without the required tier, the MCP returns an access prompt instead of running the tool. This commonly shows up on governed operations — for example, the staging-workspace lifecycle that commits writes to the live graph (penumbra_workspace_open, penumbra_workspace_modify, penumbra_workspace_submit, and the rest of the workspace tools). Reads and search typically run on a lower tier; governed writes may not.
What to do when a tool is gated
Confirm it's a tier issue, not a scope issue
Run
penumbra_context_get. If you’re on the right project but a specific tool returns an access prompt, it’s a tier gate. If you can’t even reach the project, it’s a token-scope issue (see above).Fall back to what your tier allows
If a governed write tool is gated, you can usually still read and search. Use
penumbra_omnisearch, penumbra_read, penumbra_traverse, and penumbra_source_rag to do the read-only part of the work and prepare what you’d stage.Quick reference
| You want to… | Use |
|---|---|
| See which project is active | penumbra_context_get |
| Switch the active project | penumbra_context_set |
| List reachable projects | penumbra_list_projects |
| Inspect a project before switching | penumbra_project_manifest |
| Learn the active project’s types | penumbra_introspect |
| List shapes / sources | penumbra_list_shapes, penumbra_list_sources |
Next
- Run your first read and search: Explore and retrieve
- Stage a governed write through the workspace membrane: Capture and governed writes