Update stacklok/toolhive to v0.41.0 - #1065
Merged
Merged
Conversation
Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
renovate
Bot
added
the
autogen-docs
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
Claude finished @renovate[bot]'s task in 25m 11s —— View job Upstream Release Docs: toolhive v0.41.0 — done
Summary of hand-written changes
Build note: |
Cover the v0.41.0 changes that need prose: rate-limit JSON-RPC code change from -32029 to 429, MCP 2026-07-28 revision, operator storage version migrator default and namespace opt-out, opt-in image-discovery Deployment, --build-with on uvx builds, --strict-protocol-validation, Envoy egress backend, reproducible project skills workflow, embedded authorization server RFC 8693 token exchange with delegation audit, and Cedar multi-valued claim normalization. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Contributor
|
Claude finished @renovate[bot]'s task in 6m 41s —— View job Editorial review: toolhive v0.41.0 docs — done
Editorial changes applied
Verified against upstream at
|
- Move air-gapped image discovery out of deployment-modes section, into
the operator customization section where the other image and Helm
values live. The parent section is scoped to cluster vs. namespace
mode; static image discovery is orthogonal.
- Rephrase the delegated-token intro to address the reader directly
rather than starting with "An agent framework uses ..."
- Name the reserved JSON-RPC code range in the rate-limit change note.
- Reword the cedar multi_valued_claims bullet to drop the jargon
("scope-shaped values") and lead with an example.
- Promote the --build-with "uvx only" admonition to a warning; passing
it to npx/go fails.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
github-actions
Bot
requested review from
ChrisJBurns,
JAORMX,
jhrozek,
reyortiz3 and
samuv
July 28, 2026 20:02
The v0.41.0 doc updates described the embedded authorization server's token endpoint as accepting RFC 8693 token exchange requests. Verified against the v0.41.0 tag (toolhive d72230424), that isn't reachable by users: the grant dispatch, confidential-client check, and audience bounding are all implemented, but the only path that registers clients (DCR) creates public clients with an authorization_code/refresh_token allowlist, and the grant isn't advertised in discovery metadata. The only clients registered for the grant are in tests, injected via a test-only storage backdoor. Drop the claim rather than document a feature nobody can enable. Reframe the section around what does work: ToolHive reads the act claim from any JWT it validates, so delegation audit and Cedar policies apply to tokens minted by an external IdP performing its own exchange. Also fix two errors in the same section: - Delegation audit was described as happening at token issuance. The token-exchange handler emits no audit events; all three producers are on the consumption path, firing per MCP request, per SSE connection, and per vMCP workflow step. Each hop is independently auditable. - The 10-hop cap was described as refusing exchanges, which applied to the removed issuance path. On the consumption path, over-deep chains are truncated and flagged. Add the introspection caveat, which is a silent failure mode: with opaque token introspection configured, act never reaches the audit and authorization layers, because the fixed claim struct's catch-all field is tagged json:"-" and never populates. Note in the policy reference that claim_-prefixed attributes are available on both principal and context, which explains why that page reads context.claim_act.sub under "Principal attributes". Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The v0.41.0 doc updates added four lines explaining that the 2026-07-28
spec revision introduces a stateless variant dropping the initialize
handshake and carrying protocol metadata in _meta. That's more mechanical
detail than a primer needs, and the roadmap paragraph directly below
already covers the same theme at the right altitude ("scaling Streamable
HTTP statelessly behind load balancers").
Keep the new revision date in the list, drop the explanation.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The JSON-RPC error code for rate limiting is 429 as of ToolHive v0.41.0 (pkg/ratelimit/errors.go), not -32029. Note that vMCP enforces rate limits at a second point, its tool-dispatch layer, which never sets an HTTP 429: the rejection is folded into an HTTP 200 response, so the JSON-RPC error code is the only signal a client has. Readers who detect rate limiting from the HTTP status alone would otherwise miss it entirely, which is the only reason the inner code matters. The v0.41.0 doc updates framed this as an admonition about the code changing from -32029. Left that out: a how-to guide should describe current behavior, and the migration fact belongs in release notes. Worth adding there, since upstream flags it as a wire-visible change. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
jhrozek
previously approved these changes
Jul 29, 2026
Contributor
|
@claude could you remove the experimental features for skills ( |
Contributor
|
Claude finished @samuv's task in 2m 54s —— View job Done — experimental skills lock-file docs removedRemoved all documentation for the experimental skills lock file and its commands, per your request to hold off until they're ready. Tasks
What changed
240 lines removed across 5 files (pure deletions), pushed as Two notes
· branch |
Drop documentation for the experimental thv skill sync/upgrade commands and the toolhive.lock.yaml lock file until the feature is ready. Removes the guide and concept sections, their cross-links, and the auto-generated CLI reference pages. Co-authored-by: Samuele V <4377202+samuv@users.noreply.github.com>
ChrisJBurns
approved these changes
Jul 30, 2026
This was referenced Jul 30, 2026
JAORMX
approved these changes
Jul 30, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR contains the following updates:
v0.40.1→v0.41.0After this PR opens,
.github/workflows/upstream-release-docs.ymladds source-verified content edits for the new release. Forstacklok/toolhive, the same workflow also syncs reference assets (CLI help, Swagger) and regenerates the CRD MDX pages.Release Notes
stacklok/toolhive (stacklok/toolhive)
v0.41.0Compare Source
🚀 Toolhive v0.41.0 is live!
This release delivers first-class support for the new MCP 2026-07-28 ("Modern") specification revision across every ToolHive surface — the transport proxies, the transparent proxy, and Virtual MCP now recognize, serve, and bridge both the session-based 2025-11-25 revision and the new stateless revision, including mixed client×backend combinations. It also ships a reproducible project-skills workflow (
thv skill sync/upgradewith a lock file and Sigstore groundwork), an opt-in Envoy network-isolation backend, and RFC 8693 token exchange with full delegation-chain auditing.operator.rbac.scope=namespace) failhelm upgradeat render time unless they setoperator.features.storageVersionMigrator: false; cluster-scoped installs need no action (#5603)-32600instead of being executed; batches previously bypassed authorization, tool filtering, and audit, and MCP removed batching in 2025-06-18, so send individual requests (#5931)-32029to429— the MCP 2026-07-28 spec reserves-32020..-32099; clients branching onerror.code == -32029must match429(the HTTP 429 status,Retry-Afterheader, anddata.retryAfterSecondsare unchanged) (#6120)Migration guide: storage version migrator default
The chart now enables the StorageVersionMigrator controller by default (
operator.features.storageVersionMigrator: true), and a new chart validation rejects that combination withoperator.rbac.scope=namespace— the controller cannot sync its cluster-scoped CRD informer under namespace RBAC. Affected users seehelm install/helm upgradefail with:Cluster-scoped installs (the chart default) need no action: the operator pod restarts once with the migrator enabled and begins automatically trimming
status.storedVersionson ToolHive CRDs — the precondition for a future release to drop deprecated API versions. No new pods or RBAC objects are created. To opt out anyway, setoperator.features.storageVersionMigrator: false.Namespace-scoped installs must opt out explicitly:
Before
After
Migration steps
helm get values <release> -n <ns>— you are affected ifoperator.rbac.scopeisnamespaceandoperator.features.storageVersionMigratoris unset ortrue.operator.features.storageVersionMigrator: falseto your values (or pass--set operator.features.storageVersionMigrator=false).helm upgradeas usual.status.storedVersionsby other means (e.g. a one-off run of kube-storage-version-migrator) before any future release drops a deprecated CRD version. Seedocs/operator/storage-version-migration.md.PR: #5603
Migration guide: JSON-RPC batch rejection and rate-limit error code
Batch requests (#5931) — affects only clients sending JSON-RPC batches (removed from MCP in 2025-06-18); no conformant 2025-11-25 or 2026-07-28 client emits them.
Before
[{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{...}}, {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{...}}]After
Each request must be its own POST; a batch now returns:
{"jsonrpc":"2.0","id":null,"error":{"code":-32600,"message":"Invalid Request: batch requests are not supported"}}Rate-limit error code (#6120) — affects only clients branching on the JSON-RPC
error.codefor backoff.Before
{"jsonrpc":"2.0","error":{"code":-32029,"message":"rate limited","data":{"retryAfterSeconds":30}}}After
{"jsonrpc":"2.0","error":{"code":429,"message":"rate limited","data":{"retryAfterSeconds":30}}}Migration steps
error.code == 429— or, better, key off the HTTP 429 status ordata.retryAfterSeconds, which are stable across versions.Upgrade notes (not breaking, worth knowing)
HMACSecretRefssecret file carried leading/trailing whitespace bytes, previously-minted authorization codes and refresh tokens fail validation once after upgrade and clients re-authenticate; ensure the mounted secret is exactly the raw random bytes (no trailing newline).-32603),idomitted rather thannull, generic denial messages, and filtered tool calls answered with-32602over HTTP 200 instead of a bodyless 400 — monitoring or scripts keyed to the old malformed shapes need updating.🆕 New Features
MCP 2026-07-28 ("Modern") spec support
885e8b1)input_requiredseam lands as groundwork for MRTR (SEP-2322) (#6074)io.modelcontextprotocol/*keys are stripped from backend response_metaso backends cannot spoof protocol metadata (#6024)_meta(SEP-414), joining backend spans to the client→proxy→server trace (#5964)x-mcp-headerannotations (SEP-2243) are rejected as the spec requires (#6013)MCP-Protocol-Versionheader validation for the streamable proxy (#5957)Virtual MCP conformance and aggregation
list_changednotifications are consumed and propagated to clients for tools (#5965) and for resources and prompts (#5971)Reproducible project skills
toolhive.lock.yamllock file (#5892, #5893, #5894)thv skill syncrestores a project's pinned skill set on any machine and verifies on-disk content in CI (#5895)thv skill upgradere-resolves pinned skills to newer content without silent lock drift (#5896)Authentication and token exchange
actclaim and full delegation chain, so "agent X acting for Alice" is distinguishable from Alice (#6046, refined in #6096 and adopted as the toolhive-core canonical schema in #6107)actclaims are rejected at token exchange per RFC 8693 §4.1 (#6114)Network isolation
TOOLHIVE_NETWORK_PROXY=envoy) consolidates egress and ingress into one container (#5907, seam extracted in #5906)AllowPortpermissions translate into Envoy egress RBAC policy, matching Squid's port ACLs (#5927)Other
thv runandthv buildgain a repeatable--build-withflag to constrain build-time dependencies (e.g.--build-with 'mcp<2'foruvx://packages) (#6111, #6116)🐛 Bug Fixes
email(#6022)MCPOIDCConfig.caBundleRef, fixing OIDC discovery against self-signed issuers (#4923)event: message, unbreaking spec-lenient clients such as@ai-sdk/mcp(#5954)tag@digest) no longer fail at container create (#5978)thv listno longer poisons workload status when transient Docker errors occur (#6076), the ingress proxy port is no longer derived from a fixed upstream port (#6069), and concurrent isolated-workload startups no longer race on network creation and ingress DNS (#6071, #6083)thv runin warn mode (#6063)oneOf/anyOf/enumkeywords through vMCP ingestion (#5990)🧹 Misc
9ef27fa, #5970)📦 Dependencies
google.golang.org/grpcgithub.com/klauspost/compressgithub.com/stacklok/toolhive-catalogactions/checkoutd23441agithub/codeql-actione4fba86golang/govulncheck-action032d455anthropics/claude-code-actionbe7b93b👋 Welcome to our newest contributors: @amir-rezaei and @stantheman0128 🎉
Full commit log
What's Changed
New Contributors
Full Changelog: stacklok/toolhive@v0.40.1...v0.41.0
🔗 Full changelog: stacklok/toolhive@v0.40.1...v0.41.0
Configuration
📅 Schedule: (in timezone America/New_York)
🚦 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.
This PR was generated by Mend Renovate. View the repository job log.
Docs update for
toolhivev0.41.0At a glance
stacklok/toolhivev0.40.1→v0.41.0Summary of changes
error.codefrom-32029to429indocs/toolhive/guides-k8s/rate-limiting.mdxand added an admonition explaining the change.docs/toolhive/concepts/mcp-primer.mdx, briefly framing it as a stateless variant alongside 2025-11-25.docs/toolhive/guides-k8s/deploy-operator.mdx.docs/toolhive/guides-cli/build-containers.mdxcovering the new--build-withflag onuvx://builds.docs/toolhive/guides-cli/run-mcp-servers.mdxwith the same--build-withguidance and a new "Reject unknown MCP protocol versions" section covering--strict-protocol-validation.docs/toolhive/guides-cli/network-isolation.mdxdocumenting the opt-inTOOLHIVE_NETWORK_PROXY=envoybackend.docs/toolhive/guides-cli/skills-management.mdxcoveringthv skill sync,thv skill upgrade, thetoolhive.lock.yamlfile, theTOOLHIVE_SKILLS_LOCK_ENABLEDgate, and typed exit codes; cross-linked fromdocs/toolhive/concepts/skills.mdx.docs/toolhive/concepts/embedded-auth-server.mdx.docs/toolhive/reference/authz-policy-reference.mdxand a matching config bullet indocs/toolhive/concepts/cedar-policies.mdx.Run cost
How this PR was built
Two Claude Opus sessions run per release: a generation pass
(
upstream-release-docsskill, 6 phases) followed by a fresh-context editorial pass (
docs-review). Prettier/ESLintauto-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.