[toolhive-release-app]

Release v0.55.0

Version Bump

minor release

Files Updated

• VERSION
• deploy/charts/operator-crds/Chart.yaml (path: version)
• deploy/charts/operator-crds/Chart.yaml (path: appVersion)
• deploy/charts/operator/Chart.yaml (path: version)
• deploy/charts/operator/Chart.yaml (path: appVersion)
• deploy/charts/operator/values.yaml (path: operator.image)
• deploy/charts/operator/values.yaml (path: operator.toolhiveRunnerImage)
• deploy/charts/operator/values.yaml (path: operator.vmcpImage)
• Helm chart docs (via helm-docs)

Next Steps

1. Review this PR
2. Merge to main
3. Release automation will handle the rest

Checklist

• Version bump is correct
• All CI checks pass

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 79.73%. Comparing base (4905ab8) to head (ab8cca5).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #6855   +/-   ##
=======================================
  Coverage   79.73%   79.73%           
=======================================
  Files         819      819           
  Lines       83667    83667           
=======================================
+ Hits        66709    66716    +7     
+ Misses      16953    16946    -7     
  Partials        5        5           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[github-actions]

📝 Generated release notes for v0.55.0

Auto-generated by the release-notes skill. Review and, if good, apply with:

gh release edit v0.55.0 --notes-file <paste-below>.md

Click to expand release notes

🚀 Toolhive v0.55.0 is live!

This release hardens vMCP and the streamable proxy against malicious backends and oversized requests. It also makes the embedded auth server's upstream DCR and token refresh more resilient, adds per-user upstream filtering to the VirtualMCPServer CRD, and extends the CLI with Pi support and Claude Desktop connectors.

🆕 New Features

• VirtualMCPServer.spec.authServerUpstreamFilter narrows the embedded auth server's upstream OAuth chain per user, based on a group claim. The filter fails closed: users whose identity lacks the claim are rejected. Make sure the first upstream emits the claim in its ID token or userinfo response before you turn the filter on (#6740)
• New optional dcrConfig.rotationKey on embedded auth server upstream providers. Changing it makes ToolHive register a fresh client with the upstream on its next start, so you no longer have to delete the cached dcr: row from Redis by hand. Leaving it empty keeps existing cached registrations (#6825)
• New thv client connector add|list|rm --client claude-desktop commands manage remote MCP servers in Claude Desktop's third-party (LLM gateway) configuration. Re-running thv llm setup --client claude-desktop now keeps your connectors, and thv llm teardown warns when it removes them (#6840)
• thv llm setup --client pi routes Pi through the LLM gateway, configuring both OpenAI-compatible and Anthropic models with their reported context sizes. Pi is also picked up by auto-detection when you run thv llm setup without --client (#6818)
• Groundwork for SPIFFE X.509-SVID client authentication: a TLS listener config shape and SPIFFE bundle wiring in the auth server. This is not usable yet; setting tls_listener or SPIFFE trust domains is still rejected at startup (#6760)

🐛 Bug Fixes

• Security: the streamable HTTP proxy now gives every in-flight upstream request a random correlation key. Previously, two requests in the same session that reused a JSON-RPC id could get each other's responses, which could bypass the authz list filter. Clients still receive their original id (0ce28113)
• Security: vMCP no longer crashes when a backend lists a resource with an unparsable URI. It drops that one resource and logs a warning (590dc928)
• Security: vMCP drops backend resource templates that could exhaust memory during matching, logging a warning for each. A template is dropped if it is over 1024 bytes, has more than 8 variables, or has prefix modifiers totalling more than 256 characters (c6e5eebe)
• Security: vMCP skips template matching for resource URIs over 2048 bytes in resources/read, resources/subscribe and completion/complete. Such a URI now returns not-found unless it exactly matches a listed resource, and error messages no longer echo it back. When several backends advertise overlapping templates, an exact template-string match now takes priority over an expansion match (a62748b4)
• Security: when OAuth tokens or client credentials for a remote workload are persisted, resolved secrets and runtime-only middleware are no longer written to the workload's saved run state. Older state files are scrubbed the next time tokens are saved (130f53f2)
• The embedded auth server now detects at startup when the upstream has evicted a cached DCR client and registers a new one, instead of failing every authorization with invalid_client. This costs one extra token-endpoint request per upstream per start, which upstream identity providers may log as a failed code redemption (#6822)
• New opt-in omitScopeOnRefresh on OIDC/OAuth2 upstreams leaves scope out of refresh-token requests. This fixes refresh failures against providers such as Salesforce; the default behaviour is unchanged (#6832)
• Terminating a vMCP session (client DELETE) now frees its cache entry and backend connections right away instead of keeping them until LRU eviction. Previously, memory grew with the total number of sessions ever created, which could lead to OOM kills (#6807)
• The operator now grants pods/attach to MCPServer proxy-runner Roles only for stdio transport, or when transport is unset. Existing sse and streamable-http Roles lose the permission on the next reconcile (#6841)
• When PI_CODING_AGENT_DIR is set, Pi's MCP config, user-scope skills and install detection now live under that directory, matching where thv llm setup already writes models.json. Entries previously written to ~/.pi/agent are not migrated: re-run thv client register pi and reinstall user-scope skills (#6839)

🧹 Misc

• Clarified the guarantees for session eviction and cache cleanup in code comments (#6833)
• Added conventions stated in recent code reviews to the contributor rules and docs/logging.md (#6812)
• The release-notes workflow now returns its output via structured output, so a run fails at the Claude step itself if no notes come back (#6826)
• Fixed codespell hits in vMCP resource validation (#6853)

📦 Dependencies

Module	Version
golang.org/x/net (Go SDK module)	v0.61.0
golang.org/x/text (Go SDK module)	v0.43.0
github.com/Microsoft/go-winio	v0.6.4
github.com/go-chi/chi/v5	v5.5.0
github.com/go-jose/go-jose/v4	v4.1.6
github.com/sigstore/sigstore	v1.11.1
github.com/stacklok/toolhive-core	v0.0.55
github.com/stacklok/toolhive-core/redisconn	v0.0.4
golang.ngrok.com/ngrok/v2	v2.2.1
oras.land/oras-go/v2	v2.6.4
golang.org/x/exp/jsonrpc2	f0251eb
ghcr.io/modelcontextprotocol/inspector	2.11.0
ghcr.io/stacklok/thv-registry-api	v1.5.3
ghcr.io/zizmorcore/zizmor	1.31.1
python (image digest)	2da6760
anthropics/claude-code-action	v1.0.253
github/codeql-action	v4.39.0
golangci/golangci-lint	v2.15.0
helm	v4.3.1
zizmorcore/zizmor-action	v0.7.1

Full commit log

What's Changed

• Return release notes via structured output by @rdimitrov in Return release notes via structured output #6826
• Bump x/net and x/text in the Go SDK module by @rdimitrov in Bump x/net and x/text in the Go SDK module #6828
• Add dcrConfig.rotationKey to re-register upstream DCR clients by @aron-muon in Add dcrConfig.rotationKey to re-register upstream DCR clients #6825
• Allow omitting scope on upstream token refresh by @hellouz818 in Allow omitting scope on upstream token refresh #6832
• Close terminated vMCP sessions instead of waiting for eviction by @hellouz818 in Close terminated vMCP sessions instead of waiting for eviction #6807
• Clarify session eviction cleanup guarantees by @JAORMX in Clarify session eviction cleanup guarantees #6833
• Expose group-based upstream filter via vMCP CRD by @hellouz818 in Expose group-based upstream filter via vMCP CRD #6740
• Re-register DCR clients the upstream evicted by @peppescg in Re-register DCR clients the upstream evicted #6822
• Add TLS listener config and SPIFFE X.509 authority capability by @jhrozek in Add TLS listener config and SPIFFE X.509 authority capability #6760
• Codify conventions stated in recent code reviews by @alex-feel in Codify conventions stated in recent code reviews #6812
• Support Pi in LLM gateway setup by @jerm-dro in Support Pi in LLM gateway setup #6818
• Honor PI_CODING_AGENT_DIR for Pi MCP and skills by @jerm-dro in Honor PI_CODING_AGENT_DIR for Pi MCP and skills #6839
• Grant pods/attach only for stdio transport by @hellouz818 in Grant pods/attach only for stdio transport #6841
• Add thv client connector for Claude Desktop by @jerm-dro in Add thv client connector for Claude Desktop #6840
• Update github actions by @renovate[bot] in Update github actions #6849
• Update go modules by @renovate[bot] in Update go modules #6850
• Update golang.org/x/exp/jsonrpc2 digest to f0251eb by @renovate[bot] in Update golang.org/x/exp/jsonrpc2 digest to f0251eb #6848
• Update docker images by @renovate[bot] in Update docker images #6851
• Fix codespell hits in vMCP resource validation by @rdimitrov in Fix codespell hits in vMCP resource validation #6853
• Release v0.55.0 by @toolhive-release-app[bot] in Release v0.55.0 #6855

Full Changelog: v0.54.0...v0.55.0

🔗 Full changelog: v0.54.0...v0.55.0