Skip to content

v0.30.1

Choose a tag to compare

View all tags
@toolhive-release-app toolhive-release-app released this 23 Jun 23:38
v0.30.1
966ca7c
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

📝 Generated release notes for v0.30.1

🚀 Toolhive v0.30.1 is live!

A security-and-resilience focused release: local MCP servers now isolate their network by default, shared MCPAuthzConfig references are enforced end-to-end across every workload kind, OAuth-backed workloads self-recover from transient refresh failures, and OIDC gains per-provider subject-claim selection — alongside the continuing vMCP interface refactor.

⚠️ Breaking & Behavior Changes

  • Network isolation is now ON by default for local MCP servers — thv run and REST-API-created workloads now isolate the container network from the host unless you opt out; servers that reach the host, do proxy-unaware/non-HTTP outbound, or run offline may need action (migration guide) (#5583)
  • A non-Cedar authzConfigRef on a VirtualMCPServer now fails reconciliation — the reference is finally enforced at runtime, but because vMCP authz is Cedar-only, a ref to a non-cedarv1 MCPAuthzConfig (previously a silent no-op) now sets AuthzConfigRefValidated=False and stops updating the workload (migration guide) (#5580)

Migration guide: Network isolation default flip

Who is affected: thv run users and REST API (thv serve) consumers whose servers talk to the host (e.g. host.docker.internal), do non-HTTP or proxy-unaware outbound (notably some Node/npx servers), run under a restrictive permission profile, or run in constrained/offline environments. Already-running servers are unaffected until restarted. Kubernetes/operator behavior is unchanged — the operator does not consume this flag or field.

Before (v0.30.0)

thv run my-server                       # network isolation OFF (old default)
thv run --isolate-network my-server     # explicit opt-in

After (v0.30.1)

thv run my-server                          # network isolation ON (new default)
thv run --isolate-network=false my-server  # opt out — restores old behavior
thv run --allow-docker-gateway my-server   # keep isolation, allow host gateway (host.docker.internal)

For the REST API, the network_isolation field changed from bool to an optional *bool — an omitted field now means enabled:

// Before: omitting the field meant isolation OFF
{ "name": "my-server", "image": "..." }

// After: omitting the field means isolation ON; send false explicitly to opt out
{ "name": "my-server", "image": "...", "network_isolation": false }

Migration steps

  1. For any local server that must reach the host or relies on proxy-unaware outbound, add --isolate-network=false (full opt-out) or --allow-docker-gateway (keep isolation, allow the host gateway).
  2. REST API consumers: regenerate clients from the updated swagger; send "network_isolation": false explicitly for workloads that must not be isolated.
  3. Update/PUT requests built from scratch must include network_isolation explicitly — omitting it will enable isolation on a workload that previously had it off (round-trip GET→modify→PUT clients are unaffected, since GET always returns an explicit value).

PR: #5583

Migration guide: VirtualMCPServer non-Cedar authzConfigRef

Who is affected: Operator users with an existing VirtualMCPServer whose spec.incomingAuth.authzConfigRef points at an MCPAuthzConfig of a type other than cedarv1 (e.g. a CEL config). Previously such a reference was a documented no-op and reconciled cleanly while silently enforcing no authorization. It now fails reconciliation. References to a cedarv1 config, inline spec.incomingAuth.authzConfig, or no ref at all are unaffected. The CRD schema is unchanged (only the authzConfigRef field description was updated).

Before

apiVersion: toolhive.stacklok.dev/v1beta1
kind: VirtualMCPServer
metadata:
  name: my-vmcp
spec:
  incomingAuth:
    authzConfigRef:
      name: my-cel-authz   # non-cedarv1 MCPAuthzConfig → previously inert, now rejected

After

apiVersion: toolhive.stacklok.dev/v1beta1
kind: MCPAuthzConfig
metadata:
  name: my-cedar-authz
spec:
  type: cedarv1
  # ... cedar policies ...
---
apiVersion: toolhive.stacklok.dev/v1beta1
kind: VirtualMCPServer
metadata:
  name: my-vmcp
spec:
  incomingAuth:
    authzConfigRef:
      name: my-cedar-authz   # cedarv1 → resolved and enforced

Migration steps

  1. List affected resources: kubectl get virtualmcpserver -A -o json | jq -r '.items[] | select(.spec.incomingAuth.authzConfigRef != null) | "\(.metadata.namespace)/\(.metadata.name) -> \(.spec.incomingAuth.authzConfigRef.name)"'.
  2. For each referenced MCPAuthzConfig, check spec.type. If it is cedarv1, no action is needed.
  3. If it is anything else, your authorization was never actually enforced. Convert the policy to a cedarv1 MCPAuthzConfig and point the ref at it, or move it inline under spec.incomingAuth.authzConfig (Cedar). These two are mutually exclusive.
  4. To run with no incoming authorization, remove authzConfigRef entirely (the controller clears the hash and condition).
  5. After upgrade, confirm AuthzConfigRefValidated=True and Ready=True. Note: an already-running pod keeps its last-applied policy (fail-stale, not fail-open).

PR: #5580 — Part of #4778

🆕 New Features

  • Shared MCPAuthzConfig references (spec.authzConfigRef) are now resolved and enforced at runtime across MCPServer and MCPRemoteProxy (backend-agnostic: cedarv1 and httpv1) and VirtualMCPServer (Cedar-only), instead of being reference-tracked no-ops (#5563, #5564, #5580, foundation #5559)
  • OIDC upstreams accept an optional subjectClaim (Go config and subjectClaim on the CRD) to select which validated ID-token claim is the subject — fixing IdPs where sub isn't stable, such as Entra/Azure AD's rotating sub (use oid) (#5589)
  • The operator can configure a global default Redis/Valkey session store once via operator.defaultRedis (or global.redis in an umbrella chart); workloads without an explicit spec.sessionStorage fall back to it, and per-CR storage always wins (#5595)
  • The operator now emits Kubernetes Event objects from the MCPOIDCConfig, MCPExternalAuthConfig, and MCPAuthzConfig controllers, so kubectl describe shows why a config was rejected or which workloads block its deletion (#5514)
  • New WithDialControl option on the vMCP NewHTTPBackendClient lets embedders install a per-connection dialer hook for SSRF / DNS-rebinding defense without abandoning the built-in auth registry and RoundTripper chain (#5551)
  • New public NewKubernetesBackendRegistry constructor gives embedders one-call, live Kubernetes-driven backend discovery without importing the vMCP watch substrate (#5542)
  • New PlatformUserID field on auth.PrincipalInfo and an exported NewEmbeddedAuthServerWithStorage constructor lay the OSS groundwork for per-user-keyed upstream token storage (no runtime change for standalone OSS) (#5575)

🐛 Bug Fixes

  • OAuth-backed workloads now self-recover from transient token-refresh failures (e.g. a VPN drop or network-context change) via a new auth_retrying status with tunable cadence and ceiling, instead of going permanently dead (#5350)
  • The LLM gateway token refresh window is now synced with Claude Code's helper TTL, eliminating the occasional 401 blip at the hourly token boundary (#5557)
  • The runner readiness probe now accepts 401/403 from the local proxy when OIDC auth is configured, so auth-protected workloads become ready immediately instead of hanging for the full 5-minute timeout (#5554)
  • Operator-managed pods now satisfy the restricted Pod Security Standard on all platforms — seccompProfile: RuntimeDefault and capabilities.drop: [ALL] are set in the base security context, not just on OpenShift (#5555)
  • thv stop and thv rm now free an orphaned proxy port and stop the proxy even when the workload's status file is missing, instead of silently leaving a port-holding process (#5394)
  • Allowlisted passthrough headers (e.g. X-Api-Key) are once again forwarded to backends on the vMCP Serve path, fixing a regression from the legacy path (#5561)
  • The MCPOIDCConfig controller is now the sole owner of its ReferencingWorkloads status, removing a merge-patch-vs-PUT clobber hazard and an append-only staleness bug (#5544)
  • OBO SecretEnvVars are now wired into MCPServer and MCPRemoteProxy (previously only VirtualMCPServer), so OBO middleware can read its credential at startup in builds with a registered handler (inert in stock builds) (#5540)

🧹 Misc

  • Removed the experimental, unauthenticated embedded MCP control-plane server — the thv mcp serve command and thv serve --experimental-mcp* flags are gone; use the authenticated REST/OpenAPI API instead (thv mcp call / thv mcp list debug commands are retained) (#5591)
  • Routed vmcp server construction through the domain core (core.New + Serve) as the single live path; no CLI/operator change, but out-of-tree Go embedders of pkg/vmcp/server must now supply Config.Aggregator and use Config.Authz rather than Config.AuthzMiddleware (#5556)
  • Wired the tool optimizer onto the Serve path so --enable-optimizer keeps advertising find_tool/call_tool once server.New routes through Serve (#5543)
  • Migrated operator test fixtures to the shared v1beta1test builder and added reconciler/scheme test helpers across MCPServer, MCPRemoteProxy, EmbeddingServer, and VirtualMCPServer (#5565, #5566, #5576, #5578, #5579, #5577, #5584)
  • Added MCPServer and MCPToolConfig integration tests (#5593)
  • Isolated TestWorkloadFromContainerInfo state writes and fixed a data race in TestMCPAuthzConfigReconciler_watchHandlers (#5549, #5558)
  • Minted the Homebrew tap token from a GitHub App and replaced the retest action with an inline gh api script (#5552, #5548)
  • Removed broken image links from SECURITY.md and fixed a contributing-guide link (#5547, #5587)

📦 Dependencies

Module Version
github.com/stacklok/toolhive-core v0.0.25
go.mongodb.org/mongo-driver v1.17.9
github.com/google/go-containerregistry v0.21.7
github.com/shirou/gopsutil/v4 v4.26.5
github.com/redis/go-redis/v9 v9.20.1
github.com/stacklok/toolhive-catalog v0.20260623.0
golangci/golangci-lint-action v9.2.1
anthropics/claude-code-action 2fee155
security scanning & signing actions v4.1.2
release & publishing actions (updated)

👋 Welcome to our newest contributor: @kriptoburak 🎉

Full commit log

What's Changed

New Contributors

Full Changelog: v0.30.0...v0.30.1

🔗 Full changelog: v0.30.0...v0.30.1

Contributors

tgrunnagle, jhrozek, and 9 other contributors
Assets 30
Loading