Repository navigation
v0.67.0
🚀 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 oneresource. Associations withoutresourcesare rejected, and SPIFFE token-exchange requests that sendaudience=or no target now getinvalid_target. Addresourcesto everyspiffeClientAuthentry and send a single matchingresource(migration guide) thv run uvx://…now defaults to the stdio transport. Auvx://package that serves HTTP or SSE, run without--transport,--target-portor--stateless, now starts as stdio and can't be reached through the proxy. Add--transport streamable-http(or--transport sse) (migration guide)- The
act.subof a SPIFFE token exchange is now the workload's SPIFFE ID. Cedar policies that matchclaim_act.subagainst the SPIFFE client ID no longer match. Matchclaim_client_idinstead (migration guide) MCPRemoteProxygets 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 replaceauthserver.SPIFFEGrantTypeTokenExchangewithoauthproto.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.
resourcesis now required and must have at least one entry. A CEL admission rule enforces this, along with RunConfig validation andValidateInboundGrants. The auth server refuses to start without it.audiencesis deprecated and ignored. A non-empty value is reported by theDeprecatedInboundGrantConfigurationcondition and by one startup WARN per association.- SPIFFE token exchange must send exactly one
resourcethat exactly matches an entry in the association'sresourcesand in the server's allowed audiences. The server refuses a missing, empty or repeatedresource, or anyaudienceparameter, withinvalid_target. - CRD validation ratcheting (Kubernetes 1.30+) still admits updates that leave the list unchanged. The
Validcondition onMCPExternalAuthConfig, or theAuthServerConfigValidatedcondition onVirtualMCPServer, reports the missingresources, 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 policyWARN per association. Nothing is authorized differently.
Before
spiffeClientAuth:
- # ...other association fields unchanged
audiences:
- https://mcp.example.comAfter
spiffeClientAuth:
- # ...other association fields unchanged
resources:
- https://mcp.example.com # must also be in the server's allowed audiencesMigration steps
- Add a non-empty
resourceslist to everyspiffeClientAuthentry. Each entry must be one of the server's allowed audiences. - Remove
audiencesfrom these entries. It is ignored now and only triggers the deprecation condition and WARN. - Update SPIFFE workloads to send exactly one
resource=<uri>and noaudienceparameter on token-exchange requests. - Check the
Valid/AuthServerConfigValidatedconditions after you upgrade.
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:
- An explicit
--transport - Registry metadata
stdioforuvx://inputs, unless--target-portor--statelessis setstreamable-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-httpAfter
thv run --transport streamable-http uvx://my-http-mcp-server -- --transport streamable-httpMigration steps
- Find
thv run uvx://…invocations for servers that speak HTTP or SSE. - Add
--transport streamable-httpor--transport sse, or set--target-port. - Stdio-based
uvx://servers need no change.
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.subis now the workload's verified SPIFFE ID instead of the client ID.client_idis unchanged. - A sibling workload under a wildcard (
/*) association can no longer exchange another workload's token. It getsinvalid_grantwith 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.subis the client ID) getsinvalid_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
- Search your Cedar policies for
claim_act.subcomparisons against SPIFFE client IDs. - Change them to
claim_client_id, or match the workload's SPIFFE ID if you want per-workload rules. - Update
authorization_detailshooks that readRequest.Actor, which now carries the SPIFFE ID.
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 unboundedAfter
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 setMigration steps
- Before you upgrade the operator, check memory usage of your existing
MCPRemoteProxypods. - For any proxy close to or above 256Mi, set
spec.resources.limits.memory(and CPU if needed) explicitly. - Upgrade the operator, and expect one rolling restart of affected proxies.
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.SPIFFEGrantTypeTokenExchangeAfter
import "github.com/stacklok/toolhive/pkg/auth/tokenexchange" // middleware + factory
// pkg/oauthproto/tokenexchange still holds the RFC 8693 client, ExchangeConfig and NormalizeTokenType
grant := oauthproto.GrantTypeTokenExchangeMigration steps
- Change imports of the token-exchange HTTP middleware and runner factory to
pkg/auth/tokenexchange. There is no compatibility wrapper. - Keep
pkg/oauthproto/tokenexchangefor code that only uses the exchange client,ExchangeConfigorNormalizeTokenType. - Replace
authserver.SPIFFEGrantTypeTokenExchangewithoauthproto.GrantTypeTokenExchange. The value is the same.
🔄 Deprecations
spiffeClientAuth[].audiencesis deprecated in favour ofresources. It is now ignored, and a non-empty value is reported by theDeprecatedInboundGrantConfigurationcondition 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_credentialsgrant 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) MCPExternalAuthConfigandVirtualMCPServerSPIFFE associations gain agrantTypesfield that selectsclient_credentials, token exchange or both. It defaults to token exchange. Install the new CRDs and the new operator before you enableclient_credentials(#7175)- Operators can set
clientNamein 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 validateand their API endpoints now return a structuredfindingsarray 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_descriptionwith a machine-readable reason code, such asinvalid_assertion,subject_unknown,resource_deniedorissuer_unavailable. An unreachable issuer JWKS now returns a retryable 503temporarily_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
resourceclaim 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 noallowed_audiencesnow refuses every ID-JAG that carries aresourceclaim (#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-Agentheader instead of always being reported asunknown(#7185)
🧹 Misc
- Added a SPIRE-backed end-to-end harness, with
client_credentialssuites forMCPServerandVirtualMCPServerthat 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
actclaim 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-goto 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
- Add default resource limits for MCPRemoteProxy by @ChrisJBurns in #7137
- Classify zoned addresses in the private-IP guard by @rdimitrov in #7155
- Test that act survives ID-JAG redemption by @jhrozek in #7156
- Bump actions/setup-go to v7.1.0 by @samuv in #7169
- Require one resource for SPIFFE token exchange by @jhrozek in #7160
- Add an in-process delegated-agent flow test by @jhrozek in #7171
- Enforce incoming scopes in the vMCP core by @Sanskarzz in #7170
- Default uvx:// runs to the stdio transport by @shu-chen-dot-ca in #7133
- Add client_credentials grant for SPIFFE workloads by @jhrozek in #7173
- Report structured findings from skill validation by @samuv in #7165
- Check SKILL.md links during skill validation by @samuv in #7166
- Bind SPIFFE token exchange to the acting workload by @jhrozek in #7176
- Warn on directly executed scripts in skills by @samuv in #7167
- Expose SPIFFE grant types in the operator CRD by @jhrozek in #7175
- Isolate plugin client tests from DefaultTransport by @jhrozek in #7178
- Skip SPIFFE wiring without associations by @jhrozek in #7177
- Log TLS client certificate presence at debug by @jhrozek in #7179
- Skip usage report on shutdown with no calls by @rdimitrov in #7184
- Attribute sessionless tool calls by User-Agent by @rdimitrov in #7185
- Refuse delegated-access tokens in exchanges by @jhrozek in #7180
- Add SPIRE e2e harness and SPIFFE client credentials suites by @jhrozek in #7194
- Add reason codes to redemption refusals by @jhrozek in #7193
- Move token-exchange middleware out of oauthproto by @jhrozek in #7197
- Refuse ID-JAGs whose resource claim disagrees by @jhrozek in #7198
- Stop the row-identity refresh test racing its follower by @jhrozek in #7203
- Allow configuring the DCR client name by @imaxmelnyk in #7095
- Release v0.67.0 by @toolhive-release-app[bot] in #7205
New Contributors
- @shu-chen-dot-ca made their first contribution in #7133
- @imaxmelnyk made their first contribution in #7095
Full Changelog: v0.66.0...v0.67.0
🔗 Full changelog: v0.66.0...v0.67.0