Skip to content

Update stacklok/toolhive to v0.32.0#993

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

Update stacklok/toolhive to v0.32.0#993
renovate[bot] wants to merge 7 commits into
mainfrom
renovate/stacklok-toolhive-0.x

Conversation

@renovate

@renovate renovate Bot commented Jun 30, 2026 •
edited by github-actions Bot
Loading

Copy link
Copy Markdown
Contributor

This PR contains the following updates:

Package Update Change
stacklok/toolhive minor v0.31.0 → v0.32.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 (stacklok/toolhive)

v0.32.0

Compare Source

🚀 Toolhive v0.32.0 is live!

This release advances vMCP cross-application authentication — adding the XAA (Cross-Application Access) outgoing-auth strategy, the OBO strategy seam, and upstream ID-token propagation — alongside meaningful security hardening (Origin/DNS-rebind protection and a credential-passthrough fix) and a batch of operator and proxy robustness fixes.

⚠️ Breaking Changes

  • Origin validation & SSE CORS hardening — ToolHive now validates the HTTP Origin header (MCP 2025-11-25 DNS-rebind protection) and removed the insecure Access-Control-Allow-Origin: * from the legacy SSE transport. Default local (loopback) usage is unaffected; only browser clients on a non-http://localhost origin need action via the new --allowed-origins flag (migration guide) (#​4908).
  • vMCP Go embedders: server.New signature changed — pkg/vmcp/server.New dropped its discovery.Manager parameter (7 → 6 args) and the pkg/vmcp/discovery package was removed. CLI, operator, and API behavior are unchanged; only out-of-tree code importing the vMCP library must update its call (migration guide) (#​5627).
Migration guide: Origin validation & SSE CORS hardening

Who is affected: Only browser-based MCP clients that make cross-origin requests to ToolHive's SSE transport from an origin that is not http://localhost:<port> / http://127.0.0.1:<port> (for example, a web app served over HTTPS or from a custom hostname). Non-browser clients (IDEs, CLIs, MCP SDK clients) do not send an Origin header and are unaffected. Loopback binds (the default 127.0.0.1) auto-derive a matching local allowlist, so default local usage continues to work. Non-loopback binds without --allowed-origins are not enforced — a warning is logged instead.

Before
# Relied on the implicit Access-Control-Allow-Origin: * wildcard
thv run --transport sse some/mcp-server
After
# Explicitly allow the browser origin that needs cross-origin access
thv run --transport sse --allowed-origins https://my-web-app.example.com some/mcp-server

# The same flag is available on thv proxy:
thv proxy --allowed-origins https://my-web-app.example.com ...
Migration steps
  1. Determine whether any client reaches ToolHive's SSE endpoint cross-origin from a browser. If not, no action is needed.
  2. For each such origin, pass --allowed-origins=<scheme>://<host>:<port> on thv run / thv proxy. The flag is repeatable for multiple origins; matching is exact on scheme + host + port.
  3. Consider migrating browser clients off the legacy SSE transport to the streamable-HTTP transport.

PR: #​4908

Migration guide: vMCP server.New signature change

Who is affected: Only out-of-tree Go code that imports github.com/stacklok/toolhive/pkg/vmcp/server and calls server.New directly (e.g. vMCP library embedders). All in-tree callers were updated in the same PR. There is no impact for CLI, operator, or API consumers.

Before
mgr := discovery.NewManager(agg)
srv, err := server.New(ctx, cfg, router, backendClient, mgr, backendRegistry, workflowDefs)
After
// discovery.Manager is removed; capability discovery is now the core's responsibility.
srv, err := server.New(ctx, cfg, router, backendClient, backendRegistry, workflowDefs)
Migration steps
  1. Remove the discovery.Manager argument from your server.New call (and delete the discovery.NewManager(...) construction).
  2. Ensure Config.Aggregator is set — the core now rejects a nil aggregator.
  3. If you set Config.AuthzMiddleware, also set Config.Authz; the combination without Authz now returns ErrInvalidConfig instead of silently allowing all requests.

PR: #​5627

🆕 New Features

  • New XAA (Cross-Application Access) outgoing auth strategy implementing the ID-JAG two-step token exchange (RFC 8693 → RFC 7523) for lazy per-backend cross-application access tokens (#​5684).
  • Surface upstream ID tokens through the auth middleware, consolidating upstream credential retrieval into a single bulk lookup that carries both access and ID tokens (#​5682).
  • Added the vMCP OBO (on-behalf-of) strategy seam — a new optional OBO field on BackendAuthStrategy plus strategy registration and override hook (#​5624).
  • The vMCP optimizer can now use an OpenAI-compatible embedding client via the optional embeddingProvider/embeddingModel config fields (defaults to TEI, so existing configs are unchanged) (#​5633).
  • Added insecureAllowHTTP to EmbeddedAuthServerConfig so VirtualMCPServer deployers can explicitly allow an http:// issuer for in-cluster hosts, with admission-time validation instead of a proxyrunner crash (#​5671).
  • The operator Helm chart now prints a post-install NOTES.txt with verification commands, a minimal MCPServer example, and documentation links (#​5656).

🐛 Bug Fixes

  • vMCP now returns HTTP 401 + WWW-Authenticate (RFC 6750) when an upstream provider token is expired and cannot be refreshed, letting clients re-authenticate instead of receiving an opaque error (#​5651).
  • Security: the upstreamswap custom header strategy no longer forwards the client's ToolHive JWT in Authorization to the backend; the upstream IdP token is still delivered in the configured custom header (#​5661).
  • MCPRemoteProxy now mounts and validates the referenced OIDC CA bundle ConfigMap, fixing silent TLS failures and surfacing a CABundleRefValidated status condition (#​5630).
  • Concurrent upstream-token refreshes are now deduplicated on a shared refresher, preventing spurious upstream logouts on IdPs with refresh-token rotation + reuse detection (#​5635).
  • The operator no longer perpetually reconciles MCPServers using Redis session storage with a password ref — deploymentNeedsUpdate now mirrors the Redis password env var (#​5639).
  • Container-internal target ports are no longer validated against host availability, so SSE/streamable-HTTP workloads keep their registry-defined target port (#​5638).
  • Remote proxies now set X-Forwarded-Proto to the upstream scheme, fixing infinite redirect loops when MCPRemoteProxy runs behind a TLS-terminating load balancer (#​5646).
  • Upstream-token refresh now fails closed when a rotated refresh token can't be persisted, deleting the stale row instead of stranding a poisoned token (#​5636).
  • A typed-nil *Identity stored in the request context is now treated as absent, restoring vMCP fallback identity injection and preventing nil-deref panics (#​5653).
  • VirtualMCPServer now always applies its PodTemplateSpec strategic merge patch, so fields like runtimeClassName, topologySpreadConstraints, and hostNetwork are no longer silently dropped (#​5641).
  • RestoreSession no longer fabricates a partial identity, and session restore now threads the authenticated request context, fixing cross-pod Redis failover with upstream-auth strategies (#​5650).
  • DetachedEnvVarValidator no longer rejects optional secret env vars left blank, fixing spurious "missing required secret" errors when installing registry servers via ToolHive Studio (#​5689).

🧹 Misc

  • Landed Phase 2 of the plugin lifecycle epic — new pkg/plugins / pluginsvc packages, validation, and storage migration (no user-facing surface yet) (#​5676).
  • Removed the now-unreachable legacy vMCP discovery seam and default router (#​5627).
  • Removed redundant stale-ref scans from config controller watches, relying on controller-runtime's old+new object enqueue (−648 lines) (#​5626).
  • Removed redundant annotation-based reconcile triggers in config controllers and added the missing MCPToolConfig watch (#​5629).
  • Added unit + E2E test coverage for --allow-docker-gateway deny/allow behavior (#​5644).
  • Added E2E test infrastructure for upstreamInject identity propagation after cross-pod Redis restore, plus several embedded-auth-server in-cluster fixes (#​5660).
  • Expanded CONTRIBUTING guidelines with good-first-issue and good-tenth-issue descriptions (#​5634).

📦 Dependencies

Module Version
github.com/stacklok/toolhive-catalog v0.20260629.0
anthropics/claude-code-action v1.0.159 (digest a92e7c7)
actions/create-github-app-token v3.2.0
alpine (Docker tag) v3.24.1
Core workflow actions (updated)
Setup and language actions (updated)

👋 Welcome to our newest contributors: @​syf2211 and @​claude[bot] 🎉

Full commit log

What's Changed

New Contributors

Full Changelog: stacklok/toolhive@v0.31.0...v0.32.0

🔗 Full changelog: stacklok/toolhive@v0.31.0...v0.32.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.32.0

At a glance
Upstream stacklok/toolhive v0.31.0 → v0.32.0
Hand-written changes 2 commit(s)
Reference assets refreshed (separate commit)
Gaps 0
Release contributors 9 auto-assigned (see sidebar)
Action required Spot-check skill-authored prose for accuracy

Summary of changes

  • Added "Restrict browser Origin headers" section in docs/toolhive/guides-cli/run-mcp-servers.mdx covering the new --allowed-origins flag, loopback auto-defaults, non-loopback warnings, and the SSE CORS wildcard removal.
  • Added "Use an OpenAI-compatible embedding service" section in docs/toolhive/guides-vmcp/optimizer.mdx documenting the new embeddingProvider / embeddingModel fields and the OPENAI_API_KEY env-var pattern, plus a default-backend disclaimer on the existing TEI EmbeddingServer section.
  • Updated Tier 3 description in docs/toolhive/guides-vmcp/local-cli.mdx to note the new OpenAI-compatible provider option.
  • Added "Cross-application access (XAA)" subsection in docs/toolhive/guides-vmcp/authentication.mdx describing the new XAA outgoing-auth strategy (ID-JAG two-step exchange), and an insecureAllowHTTP paragraph for the embedded auth server.
  • Added an OIDC CA bundle behavior note in docs/toolhive/guides-k8s/remote-mcp-proxy.mdx covering the new ConfigMap mount and CABundleRefValidated condition.
  • Updated Step 2 preamble in docs/toolhive/tutorials/mcp-optimizer.mdx to cross-link the OpenAI-compatible embedding alternative.

Run cost

Session Turns Cost (USD)
Generation 133 $12.1744
Editorial review 27 $2.7571
Total 160 $14.9315
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.

@renovate
Update stacklok/toolhive to v0.32.0
87b4253 
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 Jun 30, 2026
@vercel

vercel Bot commented Jun 30, 2026 •
edited
Loading

Copy link
Copy Markdown

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

Project Deployment Actions Updated (UTC)
docs-website Ready Ready Preview, Comment Jun 30, 2026 10:21pm

Request Review

@github-actions github-actions Bot marked this pull request as draft June 30, 2026 18:09
@claude

claude Bot commented Jun 30, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Claude finished @renovate[bot]'s task in 13m 55s —— View job

Updated docs for toolhive v0.32.0

Pushed commit e2f7489 covering the user-facing v0.32.0 changes.

Verified against upstream source at v0.32.0 and applied:

  • guides-cli/run-mcp-servers.mdx - New "Restrict browser Origin headers" section covering the --allowed-origins flag, loopback auto-defaults, non-loopback warning behavior, and the SSE CORS wildcard removal.
  • guides-vmcp/optimizer.mdx - New "Use an OpenAI-compatible embedding service" section documenting embeddingProvider, embeddingModel, and the OPENAI_API_KEY env-var pattern; preamble disclaimer on the existing TEI EmbeddingServer section so it no longer reads as "the only option".
  • guides-vmcp/local-cli.mdx - Tier 3 paragraph noting OpenAI-compatible provider support and that tei remains the default.
  • guides-vmcp/authentication.mdx - New "Cross-application access (XAA)" subsection (ID-JAG two-step exchange), and an insecureAllowHTTP paragraph for the embedded auth server (controller rejects with AuthServerConfigValidated=False).
  • guides-k8s/remote-mcp-proxy.mdx - Admonition noting caBundleRef is now mounted and validated with a CABundleRefValidated status condition.
  • tutorials/mcp-optimizer.mdx - Step 2 preamble cross-link to the OpenAI-compatible alternative.

SUMMARY.md is written at repo root for the workflow to splice into the PR body.

Skipped (not OSS-user-facing):

  • OBO strategy stub: returns ErrEnterpriseRequired in the OSS build; the CRD field is structurally present but unusable without an enterprise build.
  • X-Forwarded-Proto fix for remote proxies: transparent internal behavior, no config or doc change required.
  • vMCP server.New signature change: out-of-tree Go embedders only; existing docs make no claims about this Go API.
    · Branch

@github-actions
Document toolhive v0.32.0 user-facing changes
e2f7489 
Cover the new --allowed-origins flag, XAA outgoing-auth strategy,
OpenAI-compatible embedding provider, EmbeddedAuthServer
insecureAllowHTTP, and MCPRemoteProxy OIDC CA bundle behavior.
@claude

claude Bot commented Jun 30, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Claude finished @renovate[bot]'s task in 3m 48s —— View job

Editorial review for toolhive v0.32.0 docs

  • Identify changed docs files (excluding auto-generated)
  • Run docs-review skill across the changed pages
  • Apply actionable editorial fixes
  • Run npm run prettier:fix and npm run eslint:fix
  • Commit and push

Summary

Reviewed the six docs changed in e2f7489: guides-cli/run-mcp-servers.mdx, guides-k8s/remote-mcp-proxy.mdx, guides-vmcp/authentication.mdx, guides-vmcp/local-cli.mdx, guides-vmcp/optimizer.mdx, and tutorials/mcp-optimizer.mdx. Content holds up against the upstream PRs (--allowed-origins, XAA, OpenAI-compatible embeddings, insecureAllowHTTP, OIDC CA bundle mount). Structure, placement, and "Next steps" sections are all in order.

Fixes applied

Two spaced-hyphen separators in prose — the project style guide reserves spaced hyphens for list-style contexts (e.g. "Related information" entries) and asks for commas or rephrasing elsewhere:

  • guides-vmcp/optimizer.mdx (line 126): "OpenAI /embeddings API - OpenAI itself, Azure OpenAI" → "API, such as OpenAI itself, Azure OpenAI"
  • guides-vmcp/authentication.mdx (line 472, XAA insecureTargetTokenUrl warning): "test endpoints - never for production traffic" → "test endpoints, never for production traffic"

Both run through prettier/eslint clean.

Observations not acted on

  • HuggingFace vs Hugging Face: the brand is two words, but local-cli.mdx consistently uses "HuggingFace" (one word) in pre-existing content, and the new sentence in local-cli.mdx matches that. optimizer.mdx uses both forms. The inconsistency predates this PR and crosses files — leave for a separate cleanup pass.
  • New "OIDC CA bundle is mounted into the proxy pod" admonition in remote-mcp-proxy.mdx: sits directly after the existing "Production security" warning that says to "set caBundleRef if using custom CAs". The two are related but stand on their own; not worth restructuring just for adjacency.
  • "in-cluster" XAA warning still reads slightly clunky with two adjacent backticked tokens (\http://` `targetTokenUrl``), but that's a defensible tradeoff to keep both verbatim — no rewrite needed.

Pushed as commit b4768ba to renovate/stacklok-toolhive-0.x.
· Branch

@github-actions github-actions Bot marked this pull request as ready for review June 30, 2026 18:28
@danbarr

danbarr commented Jun 30, 2026

Copy link
Copy Markdown
Collaborator

@claude the new "OIDC CA bundle is mounted into the proxy pod" admonition feels like we're documenting a bugfix like it's a feature; isn't this expected behavior and thus unnecessary?

@claude

claude Bot commented Jun 30, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Claude finished @danbarr's task in 1m 17s —— View job

Removed the OIDC CA bundle admonition

  • Read the admonition and surrounding context in remote-mcp-proxy.mdx
  • Check upstream PR #5630 to classify feature vs. bugfix
  • Decide and apply the change
  • Commit and push

You're right, and I've removed it (commit 458425e).

The reasoning: upstream #5630 is a bugfix - before it, setting caBundleRef on the OIDC config silently did nothing and produced opaque TLS failures. The admonition described the now-correct behavior (the operator mounts the bundle and uses it for issuer discovery / JWKS fetch), which is exactly what a reader already expects caBundleRef to do. Documenting it inline reads like announcing a feature when it's really "the field now works as advertised."

The actionable guidance already lives one block up in the Production security warning:

  • Use certificate validation (set caBundleRef if using custom CAs)

So the only genuinely new surface was the CABundleRefValidated status condition - observability that didn't justify a standalone callout on a how-to page, especially stacked right after the security warning. Dropped the whole admonition rather than trimming it to a sentence.

I held off on prettier:fix since the edit is a clean removal of a self-contained admonition block (no surrounding reflow), so the file stays formatted - but the sandbox blocked the prettier run if you'd like CI to confirm.
· Branch

@github-actions @danbarr
Drop OIDC CA bundle admonition in remote proxy docs
458425e 
The admonition described expected behavior of caBundleRef (now fixed
upstream in a bugfix), reading like a new feature. The actionable
guidance to set caBundleRef already lives in the Production security
warning, so the callout was redundant.

Co-authored-by: Dan Barr <danbarr@users.noreply.github.com>
@danbarr @claude
Tighten Origin headers section in run-mcp-servers
1e3c7e1 
Merge redundant non-loopback explanations into one paragraph
and fix an ambiguous loopback-address parenthetical.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@danbarr danbarr marked this pull request as draft June 30, 2026 22:00
@danbarr danbarr marked this pull request as ready for review June 30, 2026 22:00
Copilot AI review requested due to automatic review settings June 30, 2026 22:00
danbarr
danbarr previously approved these changes Jun 30, 2026
View reviewed changes
Copilot AI reviewed Jun 30, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Updates this docs website’s ToolHive upstream pin to v0.32.0 and syncs the corresponding source-verified documentation edits plus regenerated reference assets (OpenAPI + CRD schemas + CLI reference).

Changes:

  • Document new security behavior and flags around browser Origin validation (--allowed-origins) in the CLI run/proxy flow.
  • Document new vMCP optimizer option to use an OpenAI-compatible /embeddings backend (embeddingProvider/embeddingModel) and update related tutorial/guide references.
  • Refresh synced reference assets for v0.32.0 (OpenAPI spec, CRD JSON schemas, CLI reference).

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

Show a summary per file
File Description
static/api-specs/toolhive-crds/virtualmcpservers.schema.json CRD schema updates for vMCP auth/optimizer fields (incl. OpenAI embedding provider + XAA-related runtime config).
static/api-specs/toolhive-crds/mcpexternalauthconfigs.schema.json CRD schema refresh for external auth config resources (embedded auth server additions).
static/api-specs/toolhive-api.yaml OpenAPI spec refresh (adds allowed_origins, insecure_allow_http).
docs/toolhive/tutorials/mcp-optimizer.mdx Tutorial updated to point readers to the OpenAI-compatible embedding alternative.
docs/toolhive/reference/cli/thv_run.md Auto-synced CLI reference includes --allowed-origins.
docs/toolhive/reference/cli/thv_proxy.md Auto-synced CLI reference includes --allowed-origins.
docs/toolhive/guides-vmcp/optimizer.mdx Adds OpenAI-compatible embedding service configuration guidance.
docs/toolhive/guides-vmcp/local-cli.mdx Tier 3 description updated to mention the OpenAI-compatible provider option.
docs/toolhive/guides-vmcp/authentication.mdx Adds XAA section and documents insecureAllowHTTP behavior for embedded auth server.
docs/toolhive/guides-cli/run-mcp-servers.mdx Adds “Restrict browser Origin headers” section documenting new behavior and --allowed-origins.
.github/upstream-projects.yaml Bumps ToolHive upstream version pin to v0.32.0.

Comment thread docs/toolhive/guides-vmcp/authentication.mdx Outdated
Comment thread static/api-specs/toolhive-api.yaml
Comment thread docs/toolhive/guides-vmcp/optimizer.mdx
tgrunnagle
tgrunnagle previously approved these changes Jun 30, 2026
View reviewed changes

@tgrunnagle tgrunnagle left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

insecureAllowHTTP and xaa bits LGTM

@danbarr @claude
Drop unsupported XAA example, fix optimizer admonition
daa05d7 
XAA isn't wired into the Kubernetes operator: the converter
discards spec.config.outgoingAuth, and MCPExternalAuthConfig's
type enum doesn't include xaa, so the CRD example in
authentication.mdx can't work today. Remove it rather than
document a feature that silently falls back to unauthenticated.

Also scope the "EmbeddingServer is always required" admonition
in optimizer.mdx to the default tei provider; it doesn't apply
when embeddingService is set directly, e.g. via the
OpenAI-compatible provider added in this release.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@danbarr danbarr dismissed stale reviews from tgrunnagle and themself via daa05d7 June 30, 2026 22:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@danbarr danbarr danbarr left review comments
Copilot code review Copilot Copilot left review comments
@tgrunnagle tgrunnagle tgrunnagle left review comments
@ChrisJBurns ChrisJBurns Awaiting requested review from ChrisJBurns
@JAORMX JAORMX Awaiting requested review from JAORMX
@jerm-dro jerm-dro Awaiting requested review from jerm-dro
@jhrozek jhrozek Awaiting requested review from jhrozek

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

autogen-docs Pull requests generated by automated release workflows

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@danbarr @tgrunnagle