ToolHive v1beta1 graduation changes how MCP servers scale

At a glance

What this is: ToolHive v0.23.0 graduates MCP server CRDs to v1beta1 and pushes shared identity, telemetry, and tool controls into reusable resources.

Why it matters: This matters because MCP deployments now need the same lifecycle discipline as other NHI estates: scoped access, reusable policy objects, and stable migration paths for operators and IAM teams.

By the numbers:

• Only 18% of MCP server deployments implement any form of access scoping for tool permissions.
• 53% of MCP servers expose credentials through hard-coded values in configuration files.

👉 Read Stacklok's ToolHive v1beta1 graduation post for MCP server migration details

Context

MCP server security now sits inside the same governance problem set as other non-human identities: credential scoping, reusable access policy, and lifecycle control. In Kubernetes, the difference between a stable API and a shifting one is not just operational convenience, because it determines whether identity, telemetry, and authorization settings can be managed as durable controls or only as per-manifest exceptions.

ToolHive’s move from v1alpha1 to v1beta1 is therefore more than a schema update. It marks a transition from inline configuration toward referenced, reusable CRDs for OIDC, telemetry, tool filters, external auth, remote server entries, and virtual server composition. For operators, that changes how MCP access is governed at scale, and it is a typical maturity step for platforms that have moved beyond early experimentation.

The broader issue is that MCP infrastructure is becoming a control plane for tool use, not just a transport layer for model calls. That places it squarely in the same governance conversation as other NHI estates, where configuration sprawl, weak scoping, and lifecycle drift are the recurring failure modes.

Key questions

Q: How should teams govern MCP servers once they are exposed through Kubernetes CRDs?

A: Treat MCP servers like any other governed identity surface. Use reusable CRDs for shared OIDC, telemetry, and tool permissions, assign ownership to each server or catalog entry, and review who can add backends or widen discovery. The goal is to keep identity, observability, and authorization controls stable as the fleet grows.

Q: What breaks when MCP access controls stay embedded in each server manifest?

A: Configuration drift breaks first. Inline controls are easy to copy incorrectly, hard to audit centrally, and difficult to retire when the schema changes. Over time, the same permission logic diverges across manifests, which creates inconsistent tool exposure and makes least privilege impossible to prove at fleet level.

Q: When should security teams move MCP settings into shared referenced resources?

A: As soon as multiple servers reuse the same identity provider, telemetry stack, or tool allow list. At that point, per-manifest settings become duplication, not control. Shared referenced resources reduce drift, simplify changes, and make policy reviews much more reliable for operators and IAM teams.

Q: What should operators check before upgrading from v1alpha1 to v1beta1?

A: Confirm which objects still write the deprecated version, then reapply manifests at v1beta1 and watch stored versions until the old API disappears from the cluster. That prevents upgrade surprises and prepares the fleet for eventual removal of v1alpha1 without downtime.

Technical breakdown

Why CRD graduation matters for MCP server governance

In Kubernetes, a CRD moving from v1alpha1 to v1beta1 usually means the schema has stabilised enough to become a durable contract. For ToolHive, that matters because MCP server identity, telemetry, and authorization are no longer treated as per-object inline blocks that can diverge silently. Instead, they become referenced resources that can be reused across MCPServer, MCPRemoteProxy, VirtualMCPServer, and related objects. That shift reduces manifest duplication and makes policy objects easier to reason about across a fleet.

Practical implication: treat the graduation as a signal to standardise shared identity and telemetry references across the cluster, not as a cosmetic version bump.

Referenced CRDs change how tool permissions are governed

Tool filtering, external auth, and OIDC settings behave differently when they are referenced instead of embedded. A referenced model lets operators centralise the identity provider, collector, and tool gating logic, which is essential when multiple MCP servers need the same approval boundaries. It also makes deprecation enforceable, because the old inline path can be warned on, then removed, without leaving every manifest to drift independently. In NHI terms, this is a move from object-local configuration to reusable entitlement primitives.

Practical implication: inventory where inline OIDC, telemetry, and tool settings still exist, then rework them into shared CRDs before the old fields disappear.

Virtual MCP servers and remote entries create a catalog first architecture

ToolHive’s MCPServerEntry and VirtualMCPServer show the platform maturing from single-server hosting into catalog and composition. Remote servers can be recorded without a proxy pod, while virtual servers present a single front door for multiple backends. That is a meaningful architecture change because it separates where a server lives from how it is governed. Once you do that, discovery, policy enforcement, and backend routing can operate on a catalog of tools rather than a one-off endpoint list.

Practical implication: model remote and local MCP backends as governed inventory, then apply access and discovery policy at the catalog layer rather than per server.

NHI Mgmt Group analysis

MCP control planes are now part of NHI governance, not just platform plumbing. Once MCP servers become shared entry points to tools and data, they inherit the same governance expectations as service accounts and API keys. The shift to reusable CRDs in ToolHive reflects a broader requirement: identity configuration must be stable, scoping must be explicit, and lifecycle changes must be managed centrally. That is the baseline control model practitioners should assume for MCP estates.

Tool sprawl becomes authorization sprawl when MCP configuration stays inline. Inline OIDC, telemetry, and tool filters work until the environment grows beyond a handful of servers, then every change becomes a manual exception. Reusable CRDs reduce that drift by making identity and observability controls referenceable across the fleet. The implication is straightforward: if the same control is repeated in twenty manifests, it is already a governance problem.

Remote MCP servers need catalog governance before they need more infrastructure. ToolHive’s MCPServerEntry model acknowledges that many servers are discovered, not hosted, by the operator. That is the right abstraction for practitioners because governance should follow the server relationship, not just the deployment location. The practical lesson is to treat remote MCP endpoints as managed NHI inventory with explicit ownership, auth, and trust boundaries.

Virtual aggregation changes the blast radius of poor tool governance. When one front door exposes many backends, weak scoping or over-broad discovery no longer affects a single service. It affects every backend that can be reached through the composed interface. Practitioners should read that as a reminder that MCP composition is an identity decision as much as an architectural one.

From our research:

• 53% of MCP servers expose credentials through hard-coded values in configuration files, according to the State of MCP Server Security 2025.
• 24,008 unique secrets were exposed in MCP configuration files in 2025 alone, according to Astrix Security.
• That is why practitioners should pair CRD graduation with the lifecycle discipline outlined in Ultimate Guide to NHIs , The NHI Market.

What this signals

Reusable CRDs are now the governance boundary for MCP estates. The operational question is no longer whether you can stand up an MCP server in Kubernetes, but whether you can govern its identity, telemetry, and tool permissions without rewriting them everywhere. With 53% of MCP servers exposing credentials through hard-coded values in configuration files, the case for centralised lifecycle control is already visible.

Catalog-first architectures will reshape how teams think about tool access. Once remote and local servers are treated as entries in a governed inventory, discovery and authorisation can be reviewed as a single programme instead of scattered cluster exceptions. That is the same structural move IAM teams made when they shifted from ad hoc accounts to managed identities.

The next control gap to watch is not only secret exposure, but whether virtual aggregation widens the tool blast radius faster than policy can keep up. Practitioners should evaluate composed MCP endpoints with the same scrutiny they apply to other shared access layers, including the standards discussed in NIST SP 800-53 Rev 5 Security and Privacy Controls.

For practitioners

• Standardise shared MCP identity controls Move OIDC, telemetry, tool filters, and external auth into referenced CRDs so the same control set is reused across the cluster instead of copied into each manifest.
• Inventory and replace inline configuration Find every remaining inline oidcConfig, telemetry, and tools block, then migrate each one to a reusable resource before deprecation warnings become removal events.
• Govern remote servers as catalog entries Use MCPServerEntry for hosted or external MCP endpoints so access, ownership, and trust can be tracked without inventing unnecessary proxy infrastructure.
• Review virtual server aggregation boundaries Check which backends are exposed through each VirtualMCPServer and confirm that tool discovery and authorization stay aligned with the intended audience.
• Plan the stored-version migration now Watch status.storedVersions, reapply manifests at v1beta1, and prepare a no-op rewrite workflow so v1alpha1 objects do not block the next upgrade.

Key takeaways

• ToolHive’s v1beta1 graduation is really a governance change, because it turns MCP identity, telemetry, and tool controls into reusable cluster resources.
• Hard-coded credentials and duplicated inline settings remain the weak point in MCP estates, so schema stability only matters if teams use it to remove manifest sprawl.
• Operators should treat remote entries, virtual composition, and stored-version migration as part of one NHI control programme rather than separate platform chores.

Key terms

• MCPServerEntry: A governable record for a remote MCP server that the operator does not host directly. It lets teams catalogue external or hosted endpoints, attach auth and trust metadata, and manage access as inventory rather than as a proxy workload.
• VirtualMCPServer: A single MCP front door that can aggregate multiple backends into one governed endpoint. It changes control design by separating backend location from discovery and authorisation, which lets teams enforce policy across a composed tool surface instead of per connection.
• Referenced CRD: A Kubernetes custom resource that stores shared configuration once and is then pointed to by multiple workloads. In identity and access terms, referenced CRDs reduce duplication, make policy reusable, and limit drift when many servers rely on the same control settings.
• Stored version migration: The process of rewriting persisted Kubernetes objects so they are stored under the current API version rather than a deprecated one. It matters because old stored versions can block CRD cleanup and turn a simple upgrade into an operational dependency.

What's in the full article

Stacklok's full blog post covers the operational detail this post intentionally leaves for the source:

• The exact v1alpha1 to v1beta1 migration sequence, including stored-version handling and deprecation warnings.
• The full CRD surface for MCPOIDCConfig, MCPTelemetryConfig, MCPToolConfig, MCPExternalAuthConfig, and VirtualMCPServer.
• Implementation detail on session restore, backend routing, composite tool definitions, and policy evaluation.
• Registry deployment options and the spec-aligned browse endpoints that were not expanded here.

👉 Stacklok's full post covers the CRD migration path, virtual server composition, and registry changes in operational depth.

Deepen your knowledge

NHI governance, agentic AI identity, and machine identity security are core topics in our NHI Foundation Level course, the industry's only accredited NHI security programme. If you are building or maturing an IAM programme, it is worth exploring.