Skip to content

Update stacklok/toolhive to v0.67.0 - #1365

Open
renovate[bot] wants to merge 3 commits into
mainfrom
renovate/stacklok-toolhive-0.x
Open

renovate[bot] wants to merge 3 commits into
mainfrom
renovate/stacklok-toolhive-0.x

Conversation

@renovate

@renovate renovate Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

This PR contains the following updates:

Package Update Change
stacklok/toolhive minor v0.66.0 → v0.67.0

After this PR opens, .github/workflows/upstream-release-docs.yml adds source-verified content edits for the new release. For stacklok/toolhive, the same workflow also syncs reference assets (CLI help, Swagger) and regenerates the CRD MDX pages.


Release Notes

stacklok/toolhive

v0.67.0

Compare Source

🚀 Toolhive v0.67.0 is live!

This release expands SPIFFE workload identity with a new client_credentials grant and operator support for choosing grant types per association. It tightens token-exchange and ID-JAG redemption with clearer refusal reasons, adds structured findings and link and script checks to skill validation, and sets default resource limits for MCPRemoteProxy.

⚠️ Breaking Changes

  • SPIFFE associations now require resources, and token exchange needs exactly one resource. Associations without resources are rejected, and SPIFFE token-exchange requests that send audience= or no target now get invalid_target. Add resources to every spiffeClientAuth entry and send a single matching resource (migration guide)
  • thv run uvx://… now defaults to the stdio transport. A uvx:// package that serves HTTP or SSE, run without --transport, --target-port or --stateless, now starts as stdio and can't be reached through the proxy. Add --transport streamable-http (or --transport sse) (migration guide)
  • The act.sub of a SPIFFE token exchange is now the workload's SPIFFE ID. Cedar policies that match claim_act.sub against the SPIFFE client ID no longer match. Match claim_client_id instead (migration guide)
  • MCPRemoteProxy gets default CPU and memory requests and limits. Existing proxies that leave any resource field unset restart once after the operator upgrade and get a 256Mi memory limit. Set explicit limits on heavy proxies before you upgrade (migration guide)
  • Go API: the token-exchange middleware moved and a constant was removed. Import the middleware from pkg/auth/tokenexchange, and replace authserver.SPIFFEGrantTypeTokenExchange with oauthproto.GrantTypeTokenExchange (migration guide)
Migration guide: SPIFFE associations require resources

Who is affected: anyone with SPIFFE associations (spiffeClientAuth) on an MCPExternalAuthConfig (spec.embeddedAuthServer.inboundGrants), a VirtualMCPServer (spec.authServerConfig.inboundGrants), or a hand-written RunConfig. This also affects SPIFFE workloads that call token exchange. SPIFFE associations were introduced in v0.65.0.

  • resources is now required and must have at least one entry. A CEL admission rule enforces this, along with RunConfig validation and ValidateInboundGrants. The auth server refuses to start without it.
  • audiences is deprecated and ignored. A non-empty value is reported by the DeprecatedInboundGrantConfiguration condition and by one startup WARN per association.
  • SPIFFE token exchange must send exactly one resource that exactly matches an entry in the association's resources and in the server's allowed audiences. The server refuses a missing, empty or repeated resource, or any audience parameter, with invalid_target.
  • CRD validation ratcheting (Kubernetes 1.30+) still admits updates that leave the list unchanged. The Valid condition on MCPExternalAuthConfig, or the AuthServerConfigValidated condition on VirtualMCPServer, reports the missing resources, and dependent servers fail to reconcile until you add it.
  • On Redis-backed servers, the first start after upgrading logs one configured client replaced with a different policy WARN per association. Nothing is authorized differently.
Before
spiffeClientAuth:
  - # ...other association fields unchanged
    audiences:
      - https://mcp.example.com
After
spiffeClientAuth:
  - # ...other association fields unchanged
    resources:
      - https://mcp.example.com   # must also be in the server's allowed audiences
Migration steps
  1. Add a non-empty resources list to every spiffeClientAuth entry. Each entry must be one of the server's allowed audiences.
  2. Remove audiences from these entries. It is ignored now and only triggers the deprecation condition and WARN.
  3. Update SPIFFE workloads to send exactly one resource=<uri> and no audience parameter on token-exchange requests.
  4. Check the Valid / AuthServerConfigValidated conditions after you upgrade.

PR: #​7160, part of #​6204

Migration guide: uvx:// defaults to stdio

Who is affected: CLI users who run thv run uvx://<package> with no --transport and no registry metadata, for a package that serves streamable-http or SSE. For example, a package switched to HTTP through its own arguments after --. Python stdio servers, which previously restarted in a loop, now work without any flags.

The transport is now chosen in this order:

  1. An explicit --transport
  2. Registry metadata
  3. stdio for uvx:// inputs, unless --target-port or --stateless is set
  4. streamable-http

npx://, go:// and plain images are unchanged, and so is the thv serve API path. thv run logs the implicit stdio choice at startup.

Before
# ran as streamable-http implicitly
thv run uvx://my-http-mcp-server -- --transport streamable-http
After
thv run --transport streamable-http uvx://my-http-mcp-server -- --transport streamable-http
Migration steps
  1. Find thv run uvx://… invocations for servers that speak HTTP or SSE.
  2. Add --transport streamable-http or --transport sse, or set --target-port.
  3. Stdio-based uvx:// servers need no change.

PR: #​7133 — Fixes #​6634

Migration guide: SPIFFE act.sub names the workload

Who is affected: deployments where SPIFFE workloads use token exchange without an actor_token, especially Cedar policies or authorization_details hooks that identify the client through act.sub.

  • In a SPIFFE workload's exchange, the outermost act.sub is now the workload's verified SPIFFE ID instead of the client ID. client_id is unchanged.
  • A sibling workload under a wildcard (/*) association can no longer exchange another workload's token. It gets invalid_grant with the hint "The subject token was issued to a different workload of this client."
  • After you upgrade, re-exchanging a token issued before the upgrade (whose act.sub is the client ID) gets invalid_grant. These tokens are short-lived, and the workload recovers by exchanging the original token again.
Before
permit(principal, action, resource)
when { principal.claim_act.sub == "my-spiffe-client" };
After
permit(principal, action, resource)
when { principal.claim_client_id == "my-spiffe-client" };
Migration steps
  1. Search your Cedar policies for claim_act.sub comparisons against SPIFFE client IDs.
  2. Change them to claim_client_id, or match the workload's SPIFFE ID if you want per-workload rules.
  3. Update authorization_details hooks that read Request.Actor, which now carries the SPIFFE ID.

PR: #​7176, part of #​6204

Migration guide: MCPRemoteProxy default resources

Who is affected: every MCPRemoteProxy that leaves any resource field unset.

Unset fields now default to these values:

CPU Memory
Requests 50m 64Mi
Limits 200m 256Mi

Explicit values in spec.resources or podTemplateSpec still win, field by field. A proxy that sets only limits behaves exactly as before. Affected proxies restart once after the operator upgrade. A proxy whose working set is above 256Mi, such as a busy proxy with an embedded auth server, will be OOMKilled.

Before
apiVersion: toolhive.stacklok.dev/v1beta1
kind: MCPRemoteProxy
spec:
  # no resources: container ran unbounded
After
apiVersion: toolhive.stacklok.dev/v1beta1
kind: MCPRemoteProxy
spec:
  resources:
    requests:
      cpu: 100m
      memory: 256Mi
    limits:
      cpu: 500m
      memory: 1Gi   # size to the proxy's observed working set
Migration steps
  1. Before you upgrade the operator, check memory usage of your existing MCPRemoteProxy pods.
  2. For any proxy close to or above 256Mi, set spec.resources.limits.memory (and CPU if needed) explicitly.
  3. Upgrade the operator, and expect one rolling restart of affected proxies.

PR: #​7137 — Fixes #​3131

Migration guide: Go API changes

Who is affected: Go programs that embed ToolHive packages. CLI flags, operator manifests, serialized runner configuration and request handling are unchanged.

Before
import "github.com/stacklok/toolhive/pkg/oauthproto/tokenexchange" // middleware + factory

grant := authserver.SPIFFEGrantTypeTokenExchange
After
import "github.com/stacklok/toolhive/pkg/auth/tokenexchange" // middleware + factory
// pkg/oauthproto/tokenexchange still holds the RFC 8693 client, ExchangeConfig and NormalizeTokenType

grant := oauthproto.GrantTypeTokenExchange
Migration steps
  1. Change imports of the token-exchange HTTP middleware and runner factory to pkg/auth/tokenexchange. There is no compatibility wrapper.
  2. Keep pkg/oauthproto/tokenexchange for code that only uses the exchange client, ExchangeConfig or NormalizeTokenType.
  3. Replace authserver.SPIFFEGrantTypeTokenExchange with oauthproto.GrantTypeTokenExchange. The value is the same.

PRs: #​7197, #​7173

🔄 Deprecations

  • spiffeClientAuth[].audiences is deprecated in favour of resources. It is now ignored, and a non-empty value is reported by the DeprecatedInboundGrantConfiguration condition and a startup WARN. It stays in the schema for compatibility with v0.65.0 objects (#​7160)

🆕 New Features

  • SPIFFE-authenticated workloads can now get access tokens with a client_credentials grant bound to their SPIFFE ID. The token lifetime is capped at the SVID's remaining validity. The grant and the SPIFFE auth methods are advertised in discovery, and token exchange is no longer force-enabled when no association lists it (#​7173)
  • MCPExternalAuthConfig and VirtualMCPServer SPIFFE associations gain a grantTypes field that selects client_credentials, token exchange or both. It defaults to token exchange. Install the new CRDs and the new operator before you enable client_credentials (#​7175)
  • Operators can set clientName in the DCR upstream configuration to control the name shown on the upstream IdP's authorization screen. It defaults to "ToolHive MCP Client" (#​7095)
  • thv skill validate, thv ai-plugin validate and their API endpoints now return a structured findings array with severity, rule ID, file and line, and plugin validation now reports bundled-skill warnings (#​7165)
  • Skill validation now checks SKILL.md links and reports broken (ref-unresolved) or escaping (ref-escapes-root) references as warnings (#​7166)
  • Skill validation warns (script-direct-exec) when a skill tells the agent to run a bundled script directly. Installed skill files aren't executable, so the script would fail (#​7167)
  • JWT-bearer and ID-JAG redemption refusals now start error_description with a machine-readable reason code, such as invalid_assertion, subject_unknown, resource_denied or issuer_unavailable. An unreachable issuer JWKS now returns a retryable 503 temporarily_unavailable (#​7193)
  • vMCP library embedders can opt in to enforcing incoming token scopes per tool through core.Config.ScopeAuthorization. This is the first of three parts, and CLI and operator deployments are unchanged (#​7170)
  • The authorization server now refuses tokens that carry the new delegated-access marker claim in token exchange, grant opening and ID-JAG issuance. Nothing issues the marker yet, so this is hardening ahead of that feature (#​7180)

🐛 Bug Fixes

  • ID-JAG redemption now refuses assertions whose resource claim names a resource the server doesn't govern, or doesn't list the requested resource, as draft-06 §4.4.1 requires. A server with no allowed_audiences now refuses every ID-JAG that carries a resource claim (#​7198)
  • The private-IP guard now blocks zone-qualified IPv6 addresses (for example [::1%25lo0]) and hosts that don't parse as IP literals. Previously these could reach loopback or private addresses (#​7155)
  • Auth servers with no SPIFFE associations no longer install the SPIFFE client resolver, so SPIFFE-typed assertions fall through to the default client authentication (#​7177)
  • Proxies and vMCP no longer send a zero-call usage report on shutdown, which stops crash-looping pods from inflating proxy counts (#​7184)
  • Tool calls on sessionless servers, or on sessions the proxy has forgotten, are now attributed to a known client named in the User-Agent header instead of always being reported as unknown (#​7185)

🧹 Misc

  • Added a SPIRE-backed end-to-end harness, with client_credentials suites for MCPServer and VirtualMCPServer that run against a real SPIRE server (#​7194)
  • Added an in-process two-server test of the delegated-agent session and schedule flows (#​7171)
  • Added a test that the act claim survives ID-JAG redemption into the issued access token (#​7156)
  • The auth server TLS listener now logs at debug level whether each connection presented a client certificate, to help debug SPIFFE X.509 failures (#​7179)
  • Fixed a flaky plugin client test by isolating it from http.DefaultTransport (#​7178)
  • Fixed a race in the row-identity refresh test (#​7203)
  • Re-pinned actions/setup-go to v7.1.0 across CI workflows to fix the static-analysis gate (#​7169)

👋 Welcome to our newest contributors: @​shu-chen-dot-ca and @​imaxmelnyk 🎉

Full commit log

What's Changed

New Contributors

Full Changelog: stacklok/toolhive@v0.66.0...v0.67.0

🔗 Full changelog: stacklok/toolhive@v0.66.0...v0.67.0


Configuration

📅 Schedule: (in timezone America/New_York)

  • Branch creation
    • At any time (no schedule defined)
  • Automerge
    • At any time (no schedule defined)

🚦 Automerge: Disabled by config. Please merge this manually once you are satisfied.

♻ Rebasing: Never, or you tick the rebase/retry checkbox.

🔕 Ignore: Close this PR and you won't be reminded about this update again.


  • If you want to rebase/retry this PR, check this box

This PR was generated by Mend Renovate. View the repository job log.


Docs update for toolhive v0.67.0

Note

Silent run — skill produced no content commits. The docs are
likely already up-to-date (e.g. main ahead of pin, or a re-run
after a previous PR for this tag merged). Only the version bump
and refreshed reference assets are included.

At a glance

Upstream stacklok/toolhive v0.66.0 → v0.67.0
Hand-written changes 0 commit(s)
Reference assets refreshed (separate commit)
Gaps 0
Owner @samuv - identified from Release-Triggered-By trailer on the tagged commit
Release contributors 5 review requested (see sidebar) · 1 not requested (no docs impact)
Action required None — approve and merge if the silent-run signal is expected

Who does what

@samuv cut this release and owns this PR: review your own changes, chase the remaining approvals, and merge once they're in. You don't need to wait on a review from anyone listed as having no docs impact below.

Everyone with a review request: the target is a review and approval within 2 business days.

Summary of changes

  • Updated the SPIFFE workload section in docs/toolhive/guides-vmcp/delegate-agent-identity.mdx: the new grantTypes field, required resources (audiences is deprecated), single-resource requests, a new "Get a token with the client credentials grant" section, the workload's SPIFFE ID in act.sub (with a Changed in v0.67.0 note for Cedar policies), workload binding, and new troubleshooting rows
  • Updated the token-pattern table in docs/toolhive/guides-vmcp/embedded-auth-server-vmcp.mdx (SPIFFE acting party, new SPIFFE client credentials row) and the spiffeTrustDomains row in docs/toolhive/guides-k8s/embedded-auth-server-k8s.mdx
  • Added dcrConfig.clientName to docs/toolhive/guides-k8s/embedded-auth-server-k8s.mdx and the vMCP dcrConfig field table
  • Added a "Size the proxy container" section with the MCPRemoteProxy default resources and a Changed in v0.67.0 upgrade note to docs/toolhive/guides-k8s/remote-mcp-proxy.mdx
  • Updated docs/toolhive/guides-cli/run-mcp-servers.mdx with the uvx:// stdio transport default and a Changed in v0.67.0 note for HTTP/SSE packages
  • Updated skill validation in docs/toolhive/guides-cli/skills-management.mdx and ai-plugins.mdx: link, path-escape, and direct-script warnings, the findings JSON output, and reporting of bundled-skill warnings
  • Updated the JWT-bearer troubleshooting table in docs/toolhive/guides-vmcp/accept-workload-assertions.mdx with the invalid_assertion reason code and the 503 issuer_unavailable response, and updated the FAQ usage-metrics client attribution in docs/toolhive/faq.mdx

Deliberately not documented:

No docs impact identified

1 contributor(s) had no-docs-impact commits in this release. No review was requested, and the workflow did not auto-notify them.

Review routing

GitHub could not request the upstream contributor directly, so review went to the human merger of each relevant upstream PR:

Run cost

Session Turns Cost (USD)
Generation 112 $3.9584
Editorial review 16 $0.5038
Total 128 $4.4622
How this PR was built

Two Claude Opus sessions run per release: a generation pass
(upstream-release-docs skill, 6 phases) followed by a fresh-
context editorial pass (docs-review). Prettier/ESLint
auto-fixes are applied after.

Auto-synced paths — do not hand-edit these in review:

  • static/api-specs/
  • docs/toolhive/reference/cli/ (toolhive only)
  • docs/toolhive/reference/crds/

If a "Gaps needing human context" section is present above,
each entry includes a paste-ready Helper prompt for local
Claude
a reviewer can use to resolve the gap.

Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
@renovate renovate Bot added the autogen-docs Pull requests generated by automated release workflows label Nov 20, 2026
@vercel

vercel Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
docs-website Ready Ready Preview Nov 20, 2026 9:11pm UTC

Request Review

@github-actions

Copy link
Copy Markdown
Contributor

Generating docs for toolhive v0.67.0… (run)

@github-actions

Copy link
Copy Markdown
Contributor

Claude generation report

Session status: success · Workflow run

Nine docs pages are updated for v0.67.0, and formatting and lint pass. The production build is still running, so I can't yet say whether it builds cleanly or whether any links broke. None of the changes are committed yet.

I checked behavior against upstream source and architecture docs at the tag, using the GitHub API. Read and grep on the local clone were blocked in this session.

Changes:

  • SPIFFE workloads (delegate-agent-identity.mdx):
    • Added the new grantTypes field, and resources is now required (audiences is deprecated and ignored).
    • Every token request carries exactly one resource, and the exchange examples now use resource= instead of audience=.
    • New section on the client_credentials grant: the token's claims, how long it lasts (no longer than the SVID that requested it), and that there's no refresh token.
    • The act.sub claim now holds the workload's SPIFFE ID, and a token can only be exchanged by the workload it names. A "Changed in v0.67.0" note tells readers to switch Cedar policies to claim_client_id.
    • Seven new troubleshooting rows.
  • Related auth pages: the token-method table in embedded-auth-server-vmcp.mdx now says SPIFFE exchanges record the workload's SPIFFE ID and gains a client-credentials row. The spiffeTrustDomains row in embedded-auth-server-k8s.mdx now mentions the new grant.
  • DCR clientName: documented in the Kubernetes guide and the vMCP field table: default name, length limit, and that it only takes effect on a new registration.
  • MCPRemoteProxy defaults (remote-mcp-proxy.mdx): new section with the default CPU and memory values and the precedence rules, plus a "Changed in v0.67.0" note about the 256Mi memory limit.
  • uvx:// now defaults to stdio (run-mcp-servers.mdx): the transport rules, an example for HTTP packages, and a "Changed in v0.67.0" note.
  • Skill validation (skills-management.mdx, ai-plugins.mdx): the new warnings (ref-unresolved, ref-escapes-root, script-direct-exec), the findings JSON output with an example message taken from source, and bundled-skill warnings in plugin validation.
  • JWT-bearer errors (accept-workload-assertions.mdx): the invalid_assertion: reason prefix, plus rows for maxAssertionAge and the 503 issuer_unavailable response.
  • FAQ: usage metrics now identify the client from the User-Agent header (the raw value is never stored or sent), and calls that can't be attributed are reported as unknown.

Deliberately left out: vMCP scope enforcement (only Go library users can turn it on), the delegated-access marker (nothing issues it yet), ID-JAG redemption changes (the OSS docs don't cover that side), and the Go API package moves. Two upgrade-order caveats are left for reviewers rather than the guides: install the new CRDs and operator before enabling client_credentials, and re-exchanging a SPIFFE token issued before the upgrade fails. All of this is recorded in SUMMARY.md.

Review requests: REVIEWERS.json marks six contributors as docs-facing, each with the commits and a specific thing to check. Sanskarzz is marked not docs-facing because their change affects only Go library users. No GAPS.md was needed, since the PR bodies and upstream architecture docs explained every feature.

I'll come back with the build result when it finishes.

@github-actions

Copy link
Copy Markdown
Contributor

Claude editorial review report

Session status: success · Workflow run

I reviewed the nine docs pages written for the v0.67.0 release and fixed four small problems. Prettier and ESLint both ran cleanly, but I didn't run npm run build. I haven't committed or pushed anything.

The HEAD commit only refreshed the auto-generated reference files, which aren't mine to edit. The new docs content is still uncommitted in the working tree, so that's what I reviewed.

Fixes:

  • faq.mdx: The telemetry bullet said ToolHive identifies the client "from the client information it sends", where "it" could mean ToolHive. It now says the information comes from the client.
  • guides-cli/run-mcp-servers.mdx: The intro sentence on default transports listed fewer exceptions than the Python tab below it (that tab also lists --target-port and --stateless). I made it a plain statement of the defaults and left the exceptions to the Python tab.
  • guides-cli/skills-management.mdx: One bullet combined two unrelated validation warnings. I split it into separate bullets for allowed-tools-comma and skill-md-too-long.
  • guides-vmcp/delegate-agent-identity.mdx: The example config highlighted only the grantTypes: line. The highlight now covers the whole new block: the grant types and the resources field.

Checked and left as is:

  • Error table in accept-workload-assertions.mdx: The "subject is not configured" error is the only one without the invalid_assertion: prefix. Upstream code and tests show that's correct.
  • The three "Changed in v0.67.0" notes: These are in run-mcp-servers, remote-mcp-proxy, and delegate-agent-identity. Each covers a change that would otherwise behave differently without warning for existing setups, so the style guide allows them.
  • The other new content read clearly and stays within each page's scope. That includes the SPIFFE client credentials section, the proxy sizing section, the DCR clientName setting, and the plugin validation notes.

I couldn't search the local upstream clone because the sandbox only allows reading inside this repo, so I checked the error strings through gh search code instead.

@stacklok-octosts
stacklok-octosts Bot marked this pull request as ready for review November 20, 2026 21:10
@github-actions

Copy link
Copy Markdown
Contributor

Done · 128 turns · $4.46 · run · see PR body for details

This branch was successfully deployed

1 active deployment
Preview — 0986f6cc Deployed Nov 20, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

autogen-docs Pull requests generated by automated release workflows

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants