Skip to content

v0.67.0

Choose a tag to compare

@toolhive-release-app toolhive-release-app released this 20 Nov 13:49
· 4 commits to main since this release
884ee1f

🚀 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 one resource. Associations without resources are rejected, and SPIFFE token-exchange requests that send audience= or no target now get invalid_target. Add resources to every spiffeClientAuth entry and send a single matching resource (migration guide)
  • thv run uvx://… now defaults to the stdio transport. A uvx:// package that serves HTTP or SSE, run without --transport, --target-port or --stateless, now starts as stdio and can't be reached through the proxy. Add --transport streamable-http (or --transport sse) (migration guide)
  • The act.sub of a SPIFFE token exchange is now the workload's SPIFFE ID. Cedar policies that match claim_act.sub against the SPIFFE client ID no longer match. Match claim_client_id instead (migration guide)
  • MCPRemoteProxy gets 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 replace authserver.SPIFFEGrantTypeTokenExchange with oauthproto.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.

  • resources is now required and must have at least one entry. A CEL admission rule enforces this, along with RunConfig validation and ValidateInboundGrants. The auth server refuses to start without it.
  • audiences is deprecated and ignored. A non-empty value is reported by the DeprecatedInboundGrantConfiguration condition and by one startup WARN per association.
  • SPIFFE token exchange must send exactly one resource that exactly matches an entry in the association's resources and in the server's allowed audiences. The server refuses a missing, empty or repeated resource, or any audience parameter, with invalid_target.
  • CRD validation ratcheting (Kubernetes 1.30+) still admits updates that leave the list unchanged. The Valid condition on MCPExternalAuthConfig, or the AuthServerConfigValidated condition on VirtualMCPServer, reports the missing resources, 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 policy WARN per association. Nothing is authorized differently.

Before

spiffeClientAuth:
  - # ...other association fields unchanged
    audiences:
      - https://mcp.example.com

After

spiffeClientAuth:
  - # ...other association fields unchanged
    resources:
      - https://mcp.example.com   # must also be in the server's allowed audiences

Migration steps

  1. Add a non-empty resources list to every spiffeClientAuth entry. Each entry must be one of the server's allowed audiences.
  2. Remove audiences from these entries. It is ignored now and only triggers the deprecation condition and WARN.
  3. Update SPIFFE workloads to send exactly one resource=<uri> and no audience parameter on token-exchange requests.
  4. Check the Valid / AuthServerConfigValidated conditions after you upgrade.

PR: #7160, part of #6204

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:

  1. An explicit --transport
  2. Registry metadata
  3. stdio for uvx:// inputs, unless --target-port or --stateless is set
  4. streamable-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-http

After

thv run --transport streamable-http uvx://my-http-mcp-server -- --transport streamable-http

Migration steps

  1. Find thv run uvx://… invocations for servers that speak HTTP or SSE.
  2. Add --transport streamable-http or --transport sse, or set --target-port.
  3. Stdio-based uvx:// servers need no change.

PR: #7133 — Fixes #6634

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.sub is now the workload's verified SPIFFE ID instead of the client ID. client_id is unchanged.
  • A sibling workload under a wildcard (/*) association can no longer exchange another workload's token. It gets invalid_grant with 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.sub is the client ID) gets invalid_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

  1. Search your Cedar policies for claim_act.sub comparisons against SPIFFE client IDs.
  2. Change them to claim_client_id, or match the workload's SPIFFE ID if you want per-workload rules.
  3. Update authorization_details hooks that read Request.Actor, which now carries the SPIFFE ID.

PR: #7176, part of #6204

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 unbounded

After

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 set

Migration steps

  1. Before you upgrade the operator, check memory usage of your existing MCPRemoteProxy pods.
  2. For any proxy close to or above 256Mi, set spec.resources.limits.memory (and CPU if needed) explicitly.
  3. Upgrade the operator, and expect one rolling restart of affected proxies.

PR: #7137 — Fixes #3131

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.SPIFFEGrantTypeTokenExchange

After

import "github.com/stacklok/toolhive/pkg/auth/tokenexchange" // middleware + factory
// pkg/oauthproto/tokenexchange still holds the RFC 8693 client, ExchangeConfig and NormalizeTokenType

grant := oauthproto.GrantTypeTokenExchange

Migration steps

  1. Change imports of the token-exchange HTTP middleware and runner factory to pkg/auth/tokenexchange. There is no compatibility wrapper.
  2. Keep pkg/oauthproto/tokenexchange for code that only uses the exchange client, ExchangeConfig or NormalizeTokenType.
  3. Replace authserver.SPIFFEGrantTypeTokenExchange with oauthproto.GrantTypeTokenExchange. The value is the same.

PRs: #7197, #7173

🔄 Deprecations

  • spiffeClientAuth[].audiences is deprecated in favour of resources. It is now ignored, and a non-empty value is reported by the DeprecatedInboundGrantConfiguration condition 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_credentials grant 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)
  • MCPExternalAuthConfig and VirtualMCPServer SPIFFE associations gain a grantTypes field that selects client_credentials, token exchange or both. It defaults to token exchange. Install the new CRDs and the new operator before you enable client_credentials (#7175)
  • Operators can set clientName in 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 validate and their API endpoints now return a structured findings array 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_description with a machine-readable reason code, such as invalid_assertion, subject_unknown, resource_denied or issuer_unavailable. An unreachable issuer JWKS now returns a retryable 503 temporarily_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 resource claim 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 no allowed_audiences now refuses every ID-JAG that carries a resource claim (#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-Agent header instead of always being reported as unknown (#7185)

🧹 Misc

  • Added a SPIRE-backed end-to-end harness, with client_credentials suites for MCPServer and VirtualMCPServer that 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 act claim 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-go to 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

Full Changelog: v0.66.0...v0.67.0

🔗 Full changelog: v0.66.0...v0.67.0