Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/upstream-projects.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ projects:

- id: toolhive
repo: stacklok/toolhive
version: v0.47.0
version: v0.47.1
# toolhive is a monorepo covering the CLI, the Kubernetes
# operator, and the vMCP gateway. It also introduces cross-
# cutting features that land in concepts/, integrations/,
Expand Down
10 changes: 6 additions & 4 deletions docs/toolhive/concepts/cedar-policies.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -476,17 +476,19 @@ outside a Cedar-enabled transparent proxy.

## List operations and filtering

List operations (`tools/list`, `prompts/list`, `resources/list`) bypass
request-level authorization entirely. ToolHive forwards the list request to the
MCP server, then automatically filters the response based on what the caller is
authorized to access:
List operations (`tools/list`, `prompts/list`, `resources/list`, and
`resources/templates/list`) bypass request-level authorization entirely.
ToolHive forwards the list request to the MCP server, then automatically filters
the response based on what the caller is authorized to access:

- `tools/list` shows only tools the user can call (based on `call_tool`
policies)
- `prompts/list` shows only prompts the user can get (based on `get_prompt`
policies)
- `resources/list` shows only resources the user can read (based on
`read_resource` policies)
- `resources/templates/list` shows only resource templates whose URI template
the user can read (based on `read_resource` policies)

You don't need to write explicit policies for list operations. Instead, focus on
the underlying access policies, and the lists will be filtered automatically.
Expand Down
40 changes: 23 additions & 17 deletions docs/toolhive/reference/authz-policy-reference.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -46,11 +46,12 @@ These actions are evaluated against your Cedar policies:

### List operations

List methods (`tools/list`, `prompts/list`, `resources/list`) bypass
request-level authorization entirely. ToolHive allows the list request through
and filters the response to include only items the caller is authorized to
access using the individual-access actions above. See
[List operation filtering](#list-operation-filtering) for details.
List methods (`tools/list`, `prompts/list`, `resources/list`, and
`resources/templates/list`) bypass request-level authorization entirely.
ToolHive allows the list request through and filters the response to include
only items the caller is authorized to access using the individual-access
actions above. See [List operation filtering](#list-operation-filtering) for
details.

### Always-allowed MCP methods

Expand Down Expand Up @@ -451,25 +452,30 @@ permit(

## List operation filtering

List operations (`tools/list`, `prompts/list`, `resources/list`) bypass
request-level authorization entirely. ToolHive forwards the list request to the
MCP server, then filters the response to include only items the caller is
authorized to access.
List operations (`tools/list`, `prompts/list`, `resources/list`, and
`resources/templates/list`) bypass request-level authorization entirely.
ToolHive forwards the list request to the MCP server, then filters the response
to include only items the caller is authorized to access.

For each item in the list response, ToolHive runs a policy check using the
corresponding individual-access action:

| List method | Per-item check uses |
| ---------------- | -------------------------------------------------------------------- |
| `tools/list` | `Action::"call_tool"` against each `Tool::"<name>"` |
| `prompts/list` | `Action::"get_prompt"` against each `Prompt::"<name>"` |
| `resources/list` | `Action::"read_resource"` against each `Resource::"<sanitized_uri>"` |
| List method | Per-item check uses |
| -------------------------- | ------------------------------------------------------------------------------------------------ |
| `tools/list` | `Action::"call_tool"` against each `Tool::"<name>"` |
| `prompts/list` | `Action::"get_prompt"` against each `Prompt::"<name>"` |
| `resources/list` | `Action::"read_resource"` against each `Resource::"<sanitized_uri>"` |
| `resources/templates/list` | `Action::"read_resource"` against each `Resource::"<sanitized_uri>"` built from the URI template |

This means you don't need separate list policies. Your `call_tool`,
`get_prompt`, and `read_resource` policies automatically control what appears in
list responses. For resources, the per-item check uses the
[sanitized](#resource-uri-sanitization) entity ID, while the original URI
remains available via the `resource.uri` attribute.
list responses. For resources and resource templates, the per-item check uses
the [sanitized](#resource-uri-sanitization) entity ID, while the original URI
(or URI template) remains available via the `resource.uri` attribute.

Filtered resource template responses are served with
`Cache-Control: private, no-store` so a shared HTTP cache cannot replay one
caller's filtered view to a different caller.

:::note

Expand Down
5 changes: 1 addition & 4 deletions docs/toolhive/reference/crds/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,7 @@ description:

import DocCard from '@theme/DocCard';

The ToolHive operator manages MCP workloads using Kubernetes custom resources.
Each page below documents one resource - its fields, defaults, validation
rules, and a minimal example manifest - and links to the other resources it
references.
The ToolHive operator manages MCP workloads using Kubernetes custom resources. Each page below documents one resource - its fields, defaults, validation rules, and a minimal example manifest - and links to the other resources it references.

## Core workloads

Expand Down
Loading