diff --git a/.github/upstream-projects.yaml b/.github/upstream-projects.yaml
index 20a32a69..4fcf9cf0 100644
--- a/.github/upstream-projects.yaml
+++ b/.github/upstream-projects.yaml
@@ -35,7 +35,7 @@ projects:
 
   - id: toolhive
     repo: stacklok/toolhive
-    version: v0.22.0
+    version: v0.23.1
     # toolhive is a monorepo covering the CLI, the Kubernetes
     # operator, and the vMCP gateway. It also introduces cross-
     # cutting features that land in concepts/, integrations/,
diff --git a/docs/toolhive/guides-cli/build-containers.mdx b/docs/toolhive/guides-cli/build-containers.mdx
index fae9a1a4..b3ad0f70 100644
--- a/docs/toolhive/guides-cli/build-containers.mdx
+++ b/docs/toolhive/guides-cli/build-containers.mdx
@@ -101,7 +101,7 @@ thv build --tag mcp-servers/git-server:stable uvx://mcp-server-git
 Use the built image in your Kubernetes manifests:
 
 ```yaml
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: git-server
@@ -263,7 +263,7 @@ you need to pre-build containers before deploying them.
 3. **Deploy to Kubernetes** using the pre-built image:
 
    ```yaml
-   apiVersion: toolhive.stacklok.dev/v1alpha1
+   apiVersion: toolhive.stacklok.dev/v1beta1
    kind: MCPServer
    metadata:
      name: git-server
@@ -499,3 +499,4 @@ If your custom package registry configuration isn't being applied:
    container build environment
 
 </details>
+
diff --git a/docs/toolhive/guides-k8s/auth-k8s.mdx b/docs/toolhive/guides-k8s/auth-k8s.mdx
index 09b19755..e31d4797 100644
--- a/docs/toolhive/guides-k8s/auth-k8s.mdx
+++ b/docs/toolhive/guides-k8s/auth-k8s.mdx
@@ -107,7 +107,7 @@ isolation.
 <TabItem value="inline" label="External IdP" default>
 
 ```yaml title="shared-oidc-config.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPOIDCConfig
 metadata:
   name: production-oidc
@@ -127,7 +127,7 @@ spec:
 <TabItem value="k8s" label="Kubernetes service account">
 
 ```yaml title="k8s-oidc-config.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPOIDCConfig
 metadata:
   name: k8s-sa-oidc
@@ -154,7 +154,7 @@ Use `oidcConfigRef` instead of inline `oidcConfig`. Each server must set a
 unique `audience` to prevent token replay across servers:
 
 ```yaml title="mcp-server-shared-oidc.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: weather-server
@@ -217,7 +217,7 @@ settings, and an `MCPServer` resource that references it. The ToolHive proxy
 handles authentication before forwarding requests to the MCP server.
 
 ```yaml title="mcp-server-external-auth.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPOIDCConfig
 metadata:
   name: external-oidc
@@ -229,7 +229,7 @@ spec:
     clientId: 'your-client-id'
     jwksUrl: 'https://your-oidc-issuer.com/path/to/jwks'
 ---
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: weather-server-external
@@ -310,7 +310,7 @@ Create an `MCPOIDCConfig` resource for Kubernetes service account authentication
 and an `MCPServer` that references it:
 
 ```yaml title="mcp-server-k8s-auth.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPOIDCConfig
 metadata:
   name: k8s-sa-oidc
@@ -321,7 +321,7 @@ spec:
     serviceAccount: 'mcp-client'
     namespace: 'client-apps'
 ---
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: weather-server-k8s
@@ -499,7 +499,7 @@ Create an `MCPExternalAuthConfig` resource with the `embeddedAuthServer` type.
 This example configures an OIDC upstream provider (the most common case):
 
 ```yaml title="embedded-auth-config.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPExternalAuthConfig
 metadata:
   name: embedded-auth-server
@@ -562,7 +562,7 @@ authorization server itself. The MCPOIDCConfig issuer must match the `issuer` in
 your `MCPExternalAuthConfig`.
 
 ```yaml title="mcp-server-embedded-auth.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPOIDCConfig
 metadata:
   name: embedded-auth-oidc
@@ -573,7 +573,7 @@ spec:
     # This must match the embedded authorization server issuer url
     issuer: 'https://mcp.example.com'
 ---
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: weather-server-embedded
@@ -690,7 +690,7 @@ for providers like GitHub that use OAuth 2.0 but don't implement the full OIDC
 specification.
 
 ```yaml title="embedded-auth-oauth2-config.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPExternalAuthConfig
 metadata:
   name: embedded-auth-oauth2
@@ -836,7 +836,7 @@ kubectl apply -f authz-configmap.yaml
 Add the authorization configuration to your `MCPServer` resources:
 
 ```yaml title="mcp-server-with-authz.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPOIDCConfig
 metadata:
   name: k8s-sa-authz-oidc
@@ -847,7 +847,7 @@ spec:
     serviceAccount: 'mcp-client'
     namespace: 'client-apps'
 ---
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: weather-server-with-authz
@@ -1057,3 +1057,4 @@ kubectl logs -n toolhive-system -l app.kubernetes.io/name=weather-server-k8s
   MCP server
 
 </details>
+
diff --git a/docs/toolhive/guides-k8s/connect-clients.mdx b/docs/toolhive/guides-k8s/connect-clients.mdx
index d30436e1..a3da463f 100644
--- a/docs/toolhive/guides-k8s/connect-clients.mdx
+++ b/docs/toolhive/guides-k8s/connect-clients.mdx
@@ -105,7 +105,7 @@ First, ensure you have an MCP server deployed. This example uses the `fetch`
 server:
 
 ```yaml title="fetch-server.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: fetch
@@ -235,7 +235,7 @@ First, in the MCPServer spec for each server, ensure the `resourceUrl` property
 is set to the full client-facing URL via `oidcConfigRef`:
 
 ```yaml title="fetch-server-oauth.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 # ...
 spec:
@@ -493,7 +493,7 @@ First, in the MCPServer spec for each server, ensure the `resourceUrl` property
 is set to the full client-facing URL via `oidcConfigRef`:
 
 ```yaml title="fetch-server-oauth.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 # ...
 spec:
@@ -1098,3 +1098,4 @@ Solutions:
 - Test connectivity using a debug pod in the app namespace
 
 </details>
+
diff --git a/docs/toolhive/guides-k8s/customize-tools.mdx b/docs/toolhive/guides-k8s/customize-tools.mdx
index 074b33d4..298dde2e 100644
--- a/docs/toolhive/guides-k8s/customize-tools.mdx
+++ b/docs/toolhive/guides-k8s/customize-tools.mdx
@@ -23,7 +23,7 @@ descriptions. You reference the configuration from an MCPServer using the
 This example exposes only three tools on a server:
 
 ```yaml title="toolconfig-basic.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPToolConfig
 metadata:
   name: basic-tool-filter
@@ -51,7 +51,7 @@ scopes (for example, separate GitHub orgs, repos, or environments). Renaming
 tools makes intent obvious and helps prevent mistakes.
 
 ```yaml title="toolconfig-with-overrides.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPToolConfig
 metadata:
   name: github-tools-config
@@ -112,7 +112,7 @@ resource.
 <TabItem value="mcpserver" label="MCPServer" default>
 
 ```yaml {10-11} title="mcpserver-with-toolconfig.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: github
@@ -130,7 +130,7 @@ spec:
 <TabItem value="mcpremoteproxy" label="MCPRemoteProxy">
 
 ```yaml {10-11} title="mcpremoteproxy-with-toolconfig.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRemoteProxy
 metadata:
   name: github
@@ -161,7 +161,7 @@ Run the GitHub MCP twice, once per organization, and rename tools so intent is
 clear to clients.
 
 ```yaml title="github-org-scoped-tools.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPToolConfig
 metadata:
   name: github-acme-tools
@@ -176,7 +176,7 @@ spec:
     get_pull_request:
       name: github_acme_get_pr
 ---
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPToolConfig
 metadata:
   name: github-foocorp-tools
@@ -191,7 +191,7 @@ spec:
     get_pull_request:
       name: github_foocorp_get_pr
 ---
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: github-acme
@@ -204,7 +204,7 @@ spec:
   toolConfigRef:
     name: github-acme-tools
 ---
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: github-foocorp
@@ -244,3 +244,4 @@ kubectl -n toolhive-system get mcpserver github -o yaml
 - See the [Kubernetes CRD reference](../reference/crds/mcptoolconfig.mdx) for
   the full MCPToolConfig and MCPServerSpec schemas.
 - Learn how to [run the MKP server in Kubernetes](../guides-mcp/k8s.mdx).
+
diff --git a/docs/toolhive/guides-k8s/logging.mdx b/docs/toolhive/guides-k8s/logging.mdx
index ca473c96..0452d085 100644
--- a/docs/toolhive/guides-k8s/logging.mdx
+++ b/docs/toolhive/guides-k8s/logging.mdx
@@ -84,7 +84,7 @@ your MCP server manifest:
 <TabItem value="mcpserver" label="MCPServer" default>
 
 ```yaml {11-12}
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: <SERVER_NAME>
@@ -102,7 +102,7 @@ spec:
 <TabItem value="mcpremoteproxy" label="MCPRemoteProxy">
 
 ```yaml {11-12}
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRemoteProxy
 metadata:
   name: <SERVER_NAME>
@@ -120,7 +120,7 @@ spec:
 <TabItem value="virtualmcpserver" label="VirtualMCPServer">
 
 ```yaml {11-14}
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: VirtualMCPServer
 metadata:
   name: <SERVER_NAME>
@@ -411,3 +411,4 @@ rules:
   complete monitoring picture
 - Check the [Kubernetes CRD reference](../reference/crds/index.mdx) for complete
   configuration options
+
diff --git a/docs/toolhive/guides-k8s/mcp-server-entry.mdx b/docs/toolhive/guides-k8s/mcp-server-entry.mdx
index 76375871..06b2cc93 100644
--- a/docs/toolhive/guides-k8s/mcp-server-entry.mdx
+++ b/docs/toolhive/guides-k8s/mcp-server-entry.mdx
@@ -79,7 +79,7 @@ MCPServerEntry resources must be part of an MCPGroup. Create the group first if
 it doesn't exist:
 
 ```yaml title="my-group.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPGroup
 metadata:
   name: my-group
@@ -91,7 +91,7 @@ spec:
 Then create a basic MCPServerEntry:
 
 ```yaml title="my-entry.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServerEntry
 metadata:
   name: my-remote-tool
@@ -142,7 +142,7 @@ exchange. The MCPExternalAuthConfig must exist in the same namespace as the
 MCPServerEntry.
 
 ```yaml title="auth-entry.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPExternalAuthConfig
 metadata:
   name: my-auth-config
@@ -157,7 +157,7 @@ spec:
       key: client-secret
     audience: https://mcp.example.com
 ---
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServerEntry
 metadata:
   name: internal-tool
@@ -191,7 +191,7 @@ kubectl create configmap internal-ca-bundle \
 Then reference it in the MCPServerEntry:
 
 ```yaml title="tls-entry.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServerEntry
 metadata:
   name: internal-tool
@@ -216,7 +216,7 @@ keys, or other purposes. Use the `headerForward` field to inject headers into
 requests forwarded to the remote server.
 
 ```yaml title="header-entry.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServerEntry
 metadata:
   name: my-remote-tool
@@ -246,7 +246,7 @@ it must already exist or be created separately:
 ```yaml title="complete-entry.yaml"
 ---
 # 1. Create the MCPGroup
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPGroup
 metadata:
   name: engineering-tools
@@ -256,7 +256,7 @@ spec:
 
 ---
 # 2. Create authentication config for token exchange
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPExternalAuthConfig
 metadata:
   name: remote-auth
@@ -273,7 +273,7 @@ spec:
 
 ---
 # 3. Create the MCPServerEntry
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServerEntry
 metadata:
   name: partner-tools
@@ -463,3 +463,4 @@ Common causes:
   server's actual transport protocol
 
 </details>
+
diff --git a/docs/toolhive/guides-k8s/migrate-to-v1beta1.mdx b/docs/toolhive/guides-k8s/migrate-to-v1beta1.mdx
index 04bcb632..d04354d0 100644
--- a/docs/toolhive/guides-k8s/migrate-to-v1beta1.mdx
+++ b/docs/toolhive/guides-k8s/migrate-to-v1beta1.mdx
@@ -2,16 +2,14 @@
 title: Migrate to v1beta1
 description:
   Breaking changes and migration steps for the CRD API stabilization track from
-  v0.15.0 through v0.21.0
+  v0.15.0 through v0.23.0
 ---
 
-The ToolHive Kubernetes Operator has undergone a series of CRD API changes in
-preparation for the `v1beta1` API version promotion. These changes span releases
-v0.15.0 through v0.21.0, each introducing breaking changes that require manifest
-and tooling updates.
-
-This guide covers every breaking change in order, so you can start from
-whichever version you are currently running and work forward.
+The ToolHive Kubernetes Operator stabilized its CRD API over multiple
+releases and graduated from `v1alpha1` to `v1beta1` in v0.23.0. This guide
+walks through every breaking schema change that landed during the stabilization
+track, so you can start from whichever version you are currently running and
+work forward to v0.23.0.
 
 :::warning[Upgrade one version at a time]
 
@@ -52,6 +50,7 @@ that point forward.
 | v0.21.0 | [`config.groupRef` fallback removed](#configgroupref-fallback-removed)                    | VirtualMCPServer                                                              | `spec.config.groupRef` removed; use `spec.groupRef`                                                                                 |
 | v0.21.0 | [`external_auth_config_ref` enum removed](#external_auth_config_ref-enum-removed)         | VirtualMCPServer                                                              | Snake_case enum value removed; use `externalAuthConfigRef`                                                                          |
 | v0.21.0 | [Inline vMCP `telemetry` removed](#inline-vmcp-telemetry-removed)                         | VirtualMCPServer                                                              | `spec.config.telemetry` removed; use `spec.telemetryConfigRef`                                                                      |
+| v0.23.0 | [CRD API graduated to v1beta1](#crd-api-graduated-from-v1alpha1-to-v1beta1)               | All ToolHive CRDs                                                             | `v1alpha1` served-and-deprecated; migrate manifests to `apiVersion: toolhive.stacklok.dev/v1beta1`                                  |
 
 ## General upgrade procedure
 
@@ -349,7 +348,7 @@ have been removed from the schema.
 
 ```yaml
 # Before (legacy typed fields)
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRegistry
 metadata:
   name: my-registry
@@ -378,7 +377,7 @@ spec:
     mode: anonymous
 
 # After (configYAML)
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRegistry
 metadata:
   name: my-registry
@@ -584,7 +583,7 @@ spec:
 Create a shared MCPOIDCConfig resource:
 
 ```yaml
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPOIDCConfig
 metadata:
   name: my-oidc-config
@@ -619,7 +618,7 @@ spec:
 Create a shared MCPTelemetryConfig resource:
 
 ```yaml
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPTelemetryConfig
 metadata:
   name: my-telemetry
@@ -701,8 +700,59 @@ outgoingAuth:
 The inline `spec.config.telemetry` field on VirtualMCPServer has been removed.
 Use `spec.telemetryConfigRef` to reference a shared MCPTelemetryConfig resource.
 
+## v0.23.0
+
+[Full release notes](https://github.com/stacklok/toolhive/releases/tag/v0.23.0)
+
+### CRD API graduated from v1alpha1 to v1beta1
+
+The operator graduates every ToolHive CRD from `v1alpha1` to `v1beta1`.
+`v1beta1` is now the storage version and the recommended API for all new and
+existing manifests.
+
+:::info[Non-breaking]
+
+`v1alpha1` is still served by the CRDs and uses a `None` conversion strategy
+(spec and status schemas are identical between versions), so existing
+`v1alpha1` resources continue to reconcile without changes. Applying a
+`v1alpha1` manifest emits a deprecation warning; plan to migrate manifests to
+`v1beta1` before the deprecation period ends.
+
+:::
+
+Update the `apiVersion` line in every ToolHive manifest:
+
+```yaml
+# Before
+apiVersion: toolhive.stacklok.dev/v1alpha1
+
+# After
+apiVersion: toolhive.stacklok.dev/v1beta1
+```
+
+Reapply each resource:
+
+```bash
+kubectl apply -f your-manifest.yaml
+```
+
+This applies to all ToolHive CRDs:
+
+- `MCPServer`, `MCPRemoteProxy`, `MCPServerEntry`, `MCPGroup`
+- `MCPRegistry`
+- `MCPOIDCConfig`, `MCPToolConfig`, `MCPTelemetryConfig`,
+  `MCPExternalAuthConfig`
+- `VirtualMCPServer`, `VirtualMCPCompositeToolDefinition`
+- `EmbeddingServer`
+
 ## Next steps
 
 - [Deploy the ToolHive operator](./deploy-operator.mdx)
 - [Run MCP servers in Kubernetes](./run-mcp-k8s.mdx)
 - [CRD specification reference](../reference/crds/index.mdx)
+
+
+
+
+
+
diff --git a/docs/toolhive/guides-k8s/rate-limiting.mdx b/docs/toolhive/guides-k8s/rate-limiting.mdx
index 66649ba4..a276002a 100644
--- a/docs/toolhive/guides-k8s/rate-limiting.mdx
+++ b/docs/toolhive/guides-k8s/rate-limiting.mdx
@@ -63,7 +63,7 @@ Shared limits apply a single token bucket across all users. Use them to cap
 total throughput to protect downstream services.
 
 ```yaml title="mcpserver-shared-ratelimit.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: weather-server
@@ -92,7 +92,7 @@ Per-user limits **require authentication** to be enabled. The proxy identifies
 users by the `sub` claim from their JWT token.
 
 ```yaml title="mcpserver-peruser-ratelimit.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPOIDCConfig
 metadata:
   name: ratelimit-oidc
@@ -102,7 +102,7 @@ spec:
   inline:
     issuer: https://my-idp.example.com
 ---
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: weather-server
@@ -132,7 +132,7 @@ limits. This lets you set a per-user ceiling while also capping total server
 throughput.
 
 ```yaml title="mcpserver-combined-ratelimit.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPOIDCConfig
 metadata:
   name: ratelimit-oidc
@@ -142,7 +142,7 @@ spec:
   inline:
     issuer: https://my-idp.example.com
 ---
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: weather-server
@@ -172,7 +172,7 @@ Individual tools can have tighter limits than the server default. Per-tool
 limits are enforced **in addition to** server-level limits.
 
 ```yaml title="mcpserver-pertool-ratelimit.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPOIDCConfig
 metadata:
   name: ratelimit-oidc
@@ -182,7 +182,7 @@ spec:
   inline:
     issuer: https://my-idp.example.com
 ---
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: weather-server
@@ -224,3 +224,4 @@ In this example:
 - [Token exchange](./token-exchange-k8s.mdx) to configure token exchange for
   upstream service authentication
 - [CRD reference](../reference/crds/index.mdx) for complete field definitions
+
diff --git a/docs/toolhive/guides-k8s/redis-session-storage.mdx b/docs/toolhive/guides-k8s/redis-session-storage.mdx
index aecf9b2a..2ba20d82 100644
--- a/docs/toolhive/guides-k8s/redis-session-storage.mdx
+++ b/docs/toolhive/guides-k8s/redis-session-storage.mdx
@@ -331,7 +331,7 @@ service discovery, which automatically resolves Sentinel endpoints from the
 headless Service deployed above:
 
 ```yaml title="embedded-auth-with-redis.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPExternalAuthConfig
 metadata:
   name: embedded-auth-server
@@ -740,7 +740,7 @@ kubectl wait --for=condition=available deployment/redis \
 Reference the Redis Service and Secret in your `MCPServer` spec:
 
 ```yaml title="mcp-server-with-redis.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: my-server
@@ -765,7 +765,7 @@ spec:
 The `sessionStorage` field is identical for `VirtualMCPServer`:
 
 ```yaml title="vmcp-with-redis.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: VirtualMCPServer
 metadata:
   name: my-vmcp
@@ -952,3 +952,4 @@ keyspace, including `thv:auth:*` tokens.
 - [Backend authentication](../concepts/backend-auth.mdx)
 - [Kubernetes CRD reference: SessionStorageConfig](../reference/crds/mcpserver.mdx)
 - [Kubernetes CRD reference: auth server storage](../reference/crds/virtualmcpserver.mdx)
+
diff --git a/docs/toolhive/guides-k8s/remote-mcp-proxy.mdx b/docs/toolhive/guides-k8s/remote-mcp-proxy.mdx
index 07ab8761..d3c0511a 100644
--- a/docs/toolhive/guides-k8s/remote-mcp-proxy.mdx
+++ b/docs/toolhive/guides-k8s/remote-mcp-proxy.mdx
@@ -105,7 +105,7 @@ This example creates a remote proxy for a fictional enterprise analytics MCP
 server with OIDC authentication:
 
 ```yaml title="analytics-proxy.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPOIDCConfig
 metadata:
   name: analytics-oidc
@@ -118,7 +118,7 @@ spec:
     # Optional: Client ID if using introspection
     clientId: analytics-proxy
 ---
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRemoteProxy
 metadata:
   name: analytics-proxy
@@ -210,7 +210,7 @@ Create an MCPOIDCConfig resource with inline OIDC settings and reference it from
 the MCPRemoteProxy. This works with most identity providers:
 
 ```yaml {1-12,21-25}
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPOIDCConfig
 metadata:
   name: company-oidc
@@ -224,7 +224,7 @@ spec:
       name: mcp-proxy-secret
       key: client-secret
 ---
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRemoteProxy
 metadata:
   name: my-proxy
@@ -246,7 +246,7 @@ For in-cluster clients, create an MCPOIDCConfig that validates Kubernetes
 service account tokens:
 
 ```yaml title="k8s-sa-oidc.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPOIDCConfig
 metadata:
   name: k8s-sa-oidc
@@ -257,7 +257,7 @@ spec:
     serviceAccount: mcp-client
     namespace: client-apps
 ---
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRemoteProxy
 metadata:
   name: analytics-proxy
@@ -360,7 +360,7 @@ available attributes depend on your identity provider's token configuration:
 Use `MCPToolConfig` to filter or rename tools from the remote server:
 
 ```yaml {2,31-32} title="analytics-tools.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPToolConfig
 metadata:
   name: analytics-tools-filter
@@ -382,7 +382,7 @@ spec:
       name: analytics_get_report
       description: Retrieve a generated analytics report
 ---
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRemoteProxy
 metadata:
   name: analytics-proxy
@@ -405,7 +405,7 @@ configure token exchange to convert company tokens into service-specific tokens:
 First, create an `MCPExternalAuthConfig`:
 
 ```yaml title="external-auth-config.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPExternalAuthConfig
 metadata:
   name: analytics-token-exchange
@@ -427,7 +427,7 @@ spec:
 Then reference it in your proxy:
 
 ```yaml {11-12}
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRemoteProxy
 metadata:
   name: analytics-proxy
@@ -492,7 +492,7 @@ stringData:
 Then reference the Secret in your MCPRemoteProxy:
 
 ```yaml title="analytics-proxy.yaml" {12-17}
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRemoteProxy
 metadata:
   name: analytics-proxy
@@ -546,7 +546,7 @@ spec:
 For testing and development, you can use the public MCP specification server:
 
 ```yaml title="mcp-spec-proxy.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPOIDCConfig
 metadata:
   name: test-oidc
@@ -556,7 +556,7 @@ spec:
   inline:
     issuer: https://auth.company.com/realms/test
 ---
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRemoteProxy
 metadata:
   name: mcp-spec-proxy
@@ -772,7 +772,7 @@ To include a remote proxy in an MCPGroup for future vMCP aggregation, add the
 `groupRef` field to your MCPRemoteProxy spec:
 
 ```yaml
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPOIDCConfig
 metadata:
   name: company-oidc
@@ -782,7 +782,7 @@ spec:
   inline:
     issuer: https://auth.company.com
 ---
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRemoteProxy
 metadata:
   name: context7-proxy
@@ -983,3 +983,4 @@ kubectl get events -n toolhive-system --sort-by='.lastTimestamp' | \
 ```
 
 </details>
+
diff --git a/docs/toolhive/guides-k8s/run-mcp-k8s.mdx b/docs/toolhive/guides-k8s/run-mcp-k8s.mdx
index a8a233dd..40109b94 100644
--- a/docs/toolhive/guides-k8s/run-mcp-k8s.mdx
+++ b/docs/toolhive/guides-k8s/run-mcp-k8s.mdx
@@ -129,7 +129,7 @@ cluster. This minimal example creates the
 information.
 
 ```yaml title="my-mcpserver.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: osv
@@ -228,7 +228,7 @@ format, so you can use any valid pod specification options.
 This example sets resource limits.
 
 ```yaml {14-15} title="my-mcpserver-custom-pod.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: fetch
@@ -289,7 +289,7 @@ kubectl -n production create secret generic github-token --from-literal=token=<Y
 Next, define the `MCPServer` resource to reference the secret:
 
 ```yaml {10-13} title="my-mcpserver-with-secrets.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: github
@@ -335,7 +335,7 @@ match what you specify in the `MCPServer` resource.
 Next, define the `MCPServer` resource to reference the secret:
 
 ```yaml {10-13} title="my-mcpserver-with-secrets-eso.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: github
@@ -395,7 +395,7 @@ the `/projects` path in the Filesystem MCP server. The PVC must already exist in
 the same namespace as the MCPServer.
 
 ```yaml {12-15,19-22} title="my-mcpserver-with-volume.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: filesystem
@@ -787,3 +787,4 @@ kubectl -n <NAMESPACE> get mcpserver <NAME> -o yaml
 ```
 
 </details>
+
diff --git a/docs/toolhive/guides-k8s/telemetry-and-metrics.mdx b/docs/toolhive/guides-k8s/telemetry-and-metrics.mdx
index 99f07056..dc8f4913 100644
--- a/docs/toolhive/guides-k8s/telemetry-and-metrics.mdx
+++ b/docs/toolhive/guides-k8s/telemetry-and-metrics.mdx
@@ -31,7 +31,7 @@ reference them from multiple MCPServer resources. Each server can override its
 **Step 1: Create an MCPTelemetryConfig resource**
 
 ```yaml title="shared-otel-config.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPTelemetryConfig
 metadata:
   name: shared-otel
@@ -60,7 +60,7 @@ Reference the config by name in `telemetryConfigRef`. Both `MCPServer` and
 `MCPRemoteProxy` support this field:
 
 ```yaml {10-12} title="mcpserver-with-shared-otel.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: gofetch
@@ -77,7 +77,7 @@ spec:
 For an `MCPRemoteProxy`, the reference works the same way:
 
 ```yaml {8-10} title="remote-proxy-with-shared-otel.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRemoteProxy
 metadata:
   name: analytics-proxy
@@ -142,7 +142,7 @@ If your OTLP endpoint requires authentication, add headers to the
 header name cannot appear in both fields.
 
 ```yaml title="otel-config-with-auth.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPTelemetryConfig
 metadata:
   name: otel-with-auth
@@ -170,7 +170,7 @@ the referenced ConfigMap into the pod and configures the OTLP exporters to trust
 the custom CA alongside the system CA pool.
 
 ```yaml title="telemetry-with-ca-bundle.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPTelemetryConfig
 metadata:
   name: shared-otel
@@ -271,7 +271,7 @@ Then point your `MCPTelemetryConfig` at the collector's OTLP HTTP receiver port
 (default `4318`):
 
 ```yaml
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPTelemetryConfig
 metadata:
   name: otel-collector
@@ -317,7 +317,7 @@ tracing system that natively supports OTLP. Point your telemetry configuration
 directly at Jaeger's OTLP HTTP port (default `4318`):
 
 ```yaml
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPTelemetryConfig
 metadata:
   name: jaeger-tracing
@@ -339,7 +339,7 @@ or use the [OpenTelemetry Collector](#opentelemetry-collector-recommended) to
 forward data to Honeycomb. This example sends data directly:
 
 ```yaml
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPTelemetryConfig
 metadata:
   name: honeycomb
@@ -387,7 +387,7 @@ To send data directly to
 [Grafana Cloud's OTLP endpoint](https://grafana.com/docs/grafana-cloud/send-data/otlp/send-data-otlp/#manual-opentelemetry-setup-for-advanced-users):
 
 ```yaml
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPTelemetryConfig
 metadata:
   name: grafana-cloud
@@ -445,3 +445,4 @@ Telemetry adds minimal overhead when properly configured:
 - [Kubernetes CRD reference](../reference/crds/mcpserver.mdx) - reference for
   the `MCPServer` Custom Resource Definition (CRD)
 - [Deploy the operator](./deploy-operator.mdx) - install the ToolHive operator
+
diff --git a/docs/toolhive/guides-k8s/token-exchange-k8s.mdx b/docs/toolhive/guides-k8s/token-exchange-k8s.mdx
index 198419ef..f7c05329 100644
--- a/docs/toolhive/guides-k8s/token-exchange-k8s.mdx
+++ b/docs/toolhive/guides-k8s/token-exchange-k8s.mdx
@@ -69,7 +69,7 @@ Create an `MCPExternalAuthConfig` resource that defines the token exchange
 parameters:
 
 ```yaml title="token-exchange-config.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPExternalAuthConfig
 metadata:
   name: backend-token-exchange
@@ -120,7 +120,7 @@ Create an `MCPOIDCConfig` resource and an `MCPServer` resource that references
 both the OIDC configuration and the token exchange configuration:
 
 ```yaml title="mcpserver-token-exchange.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPOIDCConfig
 metadata:
   name: token-exchange-oidc
@@ -131,7 +131,7 @@ spec:
     issuer: '<YOUR_OIDC_ISSUER>'
     jwksUrl: '<YOUR_JWKS_URL>'
 ---
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: my-mcp-server
@@ -203,7 +203,7 @@ stringData:
 ### MCPExternalAuthConfig
 
 ```yaml title="okta-token-exchange.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPExternalAuthConfig
 metadata:
   name: okta-backend-exchange
@@ -225,7 +225,7 @@ spec:
 ### MCPOIDCConfig and MCPServer
 
 ```yaml title="mcpserver-okta.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPOIDCConfig
 metadata:
   name: okta-oidc
@@ -236,7 +236,7 @@ spec:
     issuer: 'https://dev-123456.okta.com/oauth2/aus1234567890'
     jwksUrl: 'https://dev-123456.okta.com/oauth2/aus1234567890/v1/keys'
 ---
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: my-backend-server
@@ -288,3 +288,4 @@ Key points in this example:
 - [AWS STS integration](../integrations/aws-sts.mdx) - for AWS services,
   ToolHive has built-in STS support using `MCPExternalAuthConfig` with
   `type: awsSts`
+
diff --git a/docs/toolhive/guides-mcp/_template.mdx b/docs/toolhive/guides-mcp/_template.mdx
index 1bed3fb8..c9afa472 100644
--- a/docs/toolhive/guides-mcp/_template.mdx
+++ b/docs/toolhive/guides-mcp/_template.mdx
@@ -40,7 +40,7 @@ permission profile.
 Kubernetes manifest and instructions go here
 
 ```yaml title="SERVER_NAME.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 ```
 
@@ -55,3 +55,4 @@ Provide sample prompts that users can use to interact with the MCP server.
 
 - Include some recommended practices for using the MCP server safely and
   effectively
+
diff --git a/docs/toolhive/guides-mcp/context7.mdx b/docs/toolhive/guides-mcp/context7.mdx
index 07999f75..d56b745e 100644
--- a/docs/toolhive/guides-mcp/context7.mdx
+++ b/docs/toolhive/guides-mcp/context7.mdx
@@ -104,7 +104,7 @@ thv run --secret context7,target=CONTEXT7_API_KEY --isolate-network context7
 For basic usage without authentication:
 
 ```yaml title="context7.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: context7
@@ -175,3 +175,4 @@ Here are practical prompts you can use with the Context7 MCP server:
   [context7.com/dashboard](https://context7.com/dashboard) if you plan to make
   frequent requests or need higher rate limits.
 - Enable network isolation to restrict the server's outbound access.
+
diff --git a/docs/toolhive/guides-mcp/fetch.mdx b/docs/toolhive/guides-mcp/fetch.mdx
index 7af53932..d46f221d 100644
--- a/docs/toolhive/guides-mcp/fetch.mdx
+++ b/docs/toolhive/guides-mcp/fetch.mdx
@@ -71,7 +71,7 @@ thv run --isolate-network --permission-profile fetch-profile.json fetch
 Create a Kubernetes manifest to deploy the Fetch MCP server:
 
 ```yaml title="fetch.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: fetch
@@ -106,3 +106,4 @@ Here are some sample prompts you can use to interact with the Fetch MCP server:
   specific hosts and ports required for your use case.
 - Enable [telemetry](../guides-cli/telemetry-and-metrics.mdx) to monitor tool
   usage including URL access for security and auditing purposes.
+
diff --git a/docs/toolhive/guides-mcp/filesystem.mdx b/docs/toolhive/guides-mcp/filesystem.mdx
index 7d889f87..e011be60 100644
--- a/docs/toolhive/guides-mcp/filesystem.mdx
+++ b/docs/toolhive/guides-mcp/filesystem.mdx
@@ -112,7 +112,7 @@ Update the `podTemplateSpec` section to include your specific volume claim and
 mount path:
 
 ```yaml {14-17,20-23} title="filesystem.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: filesystem
@@ -170,3 +170,4 @@ server:
   by the AI agent to prevent accidental changes.
 - Enable network isolation to restrict the server's outbound network access,
   since the filesystem MCP server does not require any network connectivity.
+
diff --git a/docs/toolhive/guides-mcp/github.mdx b/docs/toolhive/guides-mcp/github.mdx
index 4577456e..8e9abbb7 100644
--- a/docs/toolhive/guides-mcp/github.mdx
+++ b/docs/toolhive/guides-mcp/github.mdx
@@ -132,7 +132,7 @@ kubectl -n toolhive-system create secret generic github-token --from-literal=tok
 Create a Kubernetes manifest to deploy the GitHub MCP server using your secret:
 
 ```yaml {10-14} title="github.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: github
@@ -207,3 +207,4 @@ Here are some sample prompts you can use to interact with the GitHub MCP server:
 - Enable network isolation to restrict the server's outbound network access.
 - Limit the active toolsets to reduce context overload and improve performance,
   or use dynamic tool discovery if supported by your client.
+
diff --git a/docs/toolhive/guides-mcp/grafana.mdx b/docs/toolhive/guides-mcp/grafana.mdx
index 00095562..a2386de0 100644
--- a/docs/toolhive/guides-mcp/grafana.mdx
+++ b/docs/toolhive/guides-mcp/grafana.mdx
@@ -141,7 +141,7 @@ Grafana instance URL and referencing the secret. This example uses a Grafana
 instance running in an `observability` namespace in the cluster:
 
 ```yaml title="grafana.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: grafana
@@ -229,3 +229,4 @@ server:
 - For production deployments, consider using the debug mode temporarily to
   troubleshoot connection or permission issues, but disable it once everything
   is working correctly.
+
diff --git a/docs/toolhive/guides-mcp/k8s.mdx b/docs/toolhive/guides-mcp/k8s.mdx
index 5f51de8f..b817238c 100644
--- a/docs/toolhive/guides-mcp/k8s.mdx
+++ b/docs/toolhive/guides-mcp/k8s.mdx
@@ -123,7 +123,7 @@ service account with `cluster-admin` permissions for simplicity. In production,
 create a custom ClusterRole with only the minimum permissions required.
 
 ```yaml title="mkp.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: mkp
@@ -221,3 +221,4 @@ server:
   specific namespaces rather than cluster-wide permissions.
 - **Enable audit logging**: Configure Kubernetes audit logging to track API
   calls made by the MCP server for security monitoring.
+
diff --git a/docs/toolhive/guides-mcp/notion-remote.mdx b/docs/toolhive/guides-mcp/notion-remote.mdx
index c41af34d..0f514e29 100644
--- a/docs/toolhive/guides-mcp/notion-remote.mdx
+++ b/docs/toolhive/guides-mcp/notion-remote.mdx
@@ -102,7 +102,7 @@ kubectl -n toolhive-system create secret generic notion-token --from-literal=tok
 Create a Kubernetes manifest to deploy the Notion MCP server using your secret:
 
 ```yaml title="notion.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: notion
@@ -207,3 +207,4 @@ Notion's API has rate limits. If you encounter rate limit errors:
 - Wait for the rate limit to reset (typically a few minutes)
 
 </details>
+
diff --git a/docs/toolhive/guides-mcp/osv.mdx b/docs/toolhive/guides-mcp/osv.mdx
index 8268711f..acbfff2d 100644
--- a/docs/toolhive/guides-mcp/osv.mdx
+++ b/docs/toolhive/guides-mcp/osv.mdx
@@ -66,7 +66,7 @@ thv run --isolate-network osv
 Create a Kubernetes manifest to deploy the OSV MCP server:
 
 ```yaml title="osv.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: osv
@@ -117,3 +117,4 @@ Here are some sample prompts you can use to interact with the OSV MCP server:
   identification across different ecosystems and registries.
 - **Monitor rate limits** when performing large-scale vulnerability scans to
   avoid overwhelming the OSV API service.
+
diff --git a/docs/toolhive/guides-mcp/playwright.mdx b/docs/toolhive/guides-mcp/playwright.mdx
index c2c592db..40d162ee 100644
--- a/docs/toolhive/guides-mcp/playwright.mdx
+++ b/docs/toolhive/guides-mcp/playwright.mdx
@@ -132,7 +132,7 @@ Create a basic Kubernetes manifest to deploy the Playwright MCP server using the
 Streamable HTTP transport:
 
 ```yaml title="playwright.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: playwright
@@ -168,7 +168,7 @@ For production deployments with network restrictions, add the
 `--allowed-origins` argument with a list of trusted domains:
 
 ```yaml {18-19} title="playwright-restricted.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: playwright
@@ -193,7 +193,7 @@ Mount a persistent volume to save browser output files like screenshots and
 traces:
 
 ```yaml {18-19,24-27,30-33} title="playwright-with-volume.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: playwright
@@ -269,3 +269,4 @@ server:
   screenshots, PDFs, and traces organized.
 - **Test responsively**: Use device emulation to test how web applications
   behave on different screen sizes and devices.
+
diff --git a/docs/toolhive/guides-registry/configuration.mdx b/docs/toolhive/guides-registry/configuration.mdx
index 771a5a96..ed1890bc 100644
--- a/docs/toolhive/guides-registry/configuration.mdx
+++ b/docs/toolhive/guides-registry/configuration.mdx
@@ -407,7 +407,7 @@ You can set authorization claims on individual Kubernetes workloads using the
 authenticated callers can see each entry.
 
 ```yaml title="mcp-server-with-claims.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: deploy-helper
@@ -443,7 +443,7 @@ Kubernetes workload discovery watches for annotations on
 [`VirtualMCPServer`](../guides-vmcp/configuration.mdx) resources.
 
 ```yaml {7-16}
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: my-mcp-server
@@ -693,3 +693,4 @@ precedence order.
 - [Set up authorization](./authorization.mdx) to control access with roles and
   claims
 - [Set up the database](./database.mdx) for production storage
+
diff --git a/docs/toolhive/guides-registry/deploy-operator.mdx b/docs/toolhive/guides-registry/deploy-operator.mdx
index a03d48c1..f0a0ecc9 100644
--- a/docs/toolhive/guides-registry/deploy-operator.mdx
+++ b/docs/toolhive/guides-registry/deploy-operator.mdx
@@ -70,7 +70,7 @@ This minimal example creates a registry that syncs from the ToolHive Git
 repository.
 
 ```yaml title="my-registry.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRegistry
 metadata:
   name: my-registry
@@ -137,7 +137,7 @@ You must explicitly declare all sources, including Kubernetes discovery sources.
 Clone and sync from Git repositories. Ideal for version-controlled registries.
 
 ```yaml title="registry-git.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRegistry
 metadata:
   name: git-registry
@@ -182,7 +182,7 @@ Read from a Kubernetes ConfigMap. Mount the ConfigMap as a volume and reference
 the file path in `configYAML`.
 
 ```yaml title="registry-configmap.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRegistry
 metadata:
   name: configmap-registry
@@ -217,7 +217,7 @@ Sync from an upstream MCP Registry API. Supports federation and aggregation
 scenarios.
 
 ```yaml title="registry-api.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRegistry
 metadata:
   name: api-registry
@@ -244,7 +244,7 @@ URL.
 Discover MCP servers from running Kubernetes resources in the cluster.
 
 ```yaml title="registry-k8s-discovery.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRegistry
 metadata:
   name: k8s-registry
@@ -265,7 +265,7 @@ spec:
 Fetch registry data from an HTTP/HTTPS URL.
 
 ```yaml title="registry-url.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRegistry
 metadata:
   name: url-registry
@@ -300,7 +300,7 @@ You can filter which servers are exposed through the API using name and tag
 patterns on individual sources.
 
 ```yaml title="registry-filtered.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRegistry
 metadata:
   name: filtered-registry
@@ -349,7 +349,7 @@ stringData:
     postgres.database.svc.cluster.local:5432:registry:db_app:app_password
     postgres.database.svc.cluster.local:5432:registry:db_migrator:migrator_password
 ---
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRegistry
 metadata:
   name: production-registry
@@ -431,7 +431,7 @@ OAuth mode validates JWT tokens from one or more identity providers. Configure
 providers in the `auth.oauth.providers` array within `configYAML`.
 
 ```yaml title="registry-oauth.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRegistry
 metadata:
   name: registry
@@ -493,7 +493,7 @@ For in-cluster deployments, you can configure OAuth to validate Kubernetes
 service account tokens:
 
 ```yaml title="registry-k8s-auth.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRegistry
 metadata:
   name: registry
@@ -535,7 +535,7 @@ You can configure multiple OAuth providers to accept tokens from different
 identity sources:
 
 ```yaml title="registry-multi-provider.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRegistry
 metadata:
   name: registry
@@ -572,7 +572,7 @@ The server validates tokens against each provider in order until one succeeds.
 For development and testing, you can disable authentication entirely:
 
 ```yaml title="registry-anonymous.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRegistry
 metadata:
   name: registry
@@ -611,7 +611,7 @@ You can customize the Registry server pod using the `podTemplateSpec` field.
 This gives you full control over the pod specification.
 
 ```yaml title="registry-custom-pod.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRegistry
 metadata:
   name: custom-registry
@@ -831,3 +831,4 @@ Common causes include:
 - **Filter too restrictive**: Filters may be excluding all servers
 
 </details>
+
diff --git a/docs/toolhive/guides-registry/quickstart.mdx b/docs/toolhive/guides-registry/quickstart.mdx
index 4e292e4e..e5b6b321 100644
--- a/docs/toolhive/guides-registry/quickstart.mdx
+++ b/docs/toolhive/guides-registry/quickstart.mdx
@@ -250,7 +250,7 @@ Create an `MCPRegistry` that mounts the ConfigMap, reads from the file, and
 exposes the data through a registry named `default`:
 
 ```yaml title="my-registry.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRegistry
 metadata:
   name: my-registry
@@ -434,3 +434,4 @@ Make sure the operator CRDs chart was installed before the operator chart. The
 operator needs the CRDs to exist before it starts.
 
 </details>
+
diff --git a/docs/toolhive/guides-vmcp/audit-logging.mdx b/docs/toolhive/guides-vmcp/audit-logging.mdx
index 083dc2c6..69d5115d 100644
--- a/docs/toolhive/guides-vmcp/audit-logging.mdx
+++ b/docs/toolhive/guides-vmcp/audit-logging.mdx
@@ -22,7 +22,7 @@ Configure audit logging in the VirtualMCPServer resource using the
 `spec.config.audit` field:
 
 ```yaml
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: VirtualMCPServer
 metadata:
   name: my-vmcp
@@ -279,7 +279,7 @@ Monitor).
 To persist audit logs to a file, configure a persistent volume:
 
 ```yaml
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: VirtualMCPServer
 metadata:
   name: my-vmcp
@@ -414,3 +414,4 @@ collection with Fluentd, Filebeat, Splunk, and other systems, see the
   performance with OpenTelemetry
 - [Kubernetes logging guide](../guides-k8s/logging.mdx) - configure logging for
   MCP servers in Kubernetes
+
diff --git a/docs/toolhive/guides-vmcp/authentication.mdx b/docs/toolhive/guides-vmcp/authentication.mdx
index 73dab1db..df95d4bd 100644
--- a/docs/toolhive/guides-vmcp/authentication.mdx
+++ b/docs/toolhive/guides-vmcp/authentication.mdx
@@ -81,7 +81,7 @@ credentials.
 Validate tokens from an external identity provider:
 
 ```yaml title="MCPOIDCConfig resource"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPOIDCConfig
 metadata:
   name: vmcp-oidc
@@ -106,7 +106,7 @@ When using an identity provider that issues opaque OAuth tokens, add a
 `clientSecretRef` to the MCPOIDCConfig resource to enable token introspection:
 
 ```yaml title="MCPOIDCConfig resource"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPOIDCConfig
 metadata:
   name: vmcp-oidc
@@ -148,7 +148,7 @@ stringData:
 Authenticate using Kubernetes service account tokens for in-cluster clients:
 
 ```yaml title="MCPOIDCConfig resource"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPOIDCConfig
 metadata:
   name: vmcp-k8s-oidc
@@ -210,7 +210,7 @@ Create an `MCPExternalAuthConfig` resource with the `upstreamInject` type. The
 authorization server:
 
 ```yaml title="MCPExternalAuthConfig resource"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPExternalAuthConfig
 metadata:
   name: inject-github
@@ -264,7 +264,7 @@ server acquires an Okta access token during login, you can exchange that token
 at a different Okta authorization server for a backend-scoped token:
 
 ```yaml title="MCPExternalAuthConfig resource"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPExternalAuthConfig
 metadata:
   name: exchange-okta
@@ -507,14 +507,14 @@ You need: `auth-signing-key`, `auth-hmac-key`, `github-client-secret`, and
 **Step 1:** Create an MCPGroup, OIDC config, and deploy the backend MCP server:
 
 ```yaml title="backends.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPGroup
 metadata:
   name: my-backends
   namespace: toolhive-system
 ---
 # highlight-start
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPOIDCConfig
 metadata:
   name: my-oidc-config
@@ -525,7 +525,7 @@ spec:
     issuer: https://auth.example.com
 # highlight-end
 ---
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: backend-github
@@ -542,7 +542,7 @@ spec:
 **Step 2:** Create the upstream token injection config:
 
 ```yaml title="auth-configs.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPExternalAuthConfig
 metadata:
   name: inject-github
@@ -556,7 +556,7 @@ spec:
 **Step 3:** Deploy the VirtualMCPServer:
 
 ```yaml title="virtualmcpserver.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: VirtualMCPServer
 metadata:
   name: my-vmcp
@@ -667,3 +667,4 @@ automatically include your GitHub access token.
 - [Token exchange in Kubernetes](../guides-k8s/token-exchange-k8s.mdx)
 - [Embedded auth server for MCPServer](../guides-k8s/auth-k8s.mdx#set-up-embedded-authorization-server-authentication)
 - [Redis Sentinel session storage](../guides-k8s/redis-session-storage.mdx)
+
diff --git a/docs/toolhive/guides-vmcp/backend-discovery.mdx b/docs/toolhive/guides-vmcp/backend-discovery.mdx
index ddd5ac98..1b891462 100644
--- a/docs/toolhive/guides-vmcp/backend-discovery.mdx
+++ b/docs/toolhive/guides-vmcp/backend-discovery.mdx
@@ -72,7 +72,7 @@ servers. This is the default mode.
 ### Discovered mode configuration
 
 ```yaml
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: VirtualMCPServer
 metadata:
   name: my-vmcp
@@ -138,7 +138,7 @@ updates), reducing the attack surface.
 ### Inline mode configuration
 
 ```yaml
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: VirtualMCPServer
 metadata:
   name: my-vmcp
@@ -389,7 +389,7 @@ with authentication:
 ```yaml
 ---
 # 1. Create the MCPGroup
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPGroup
 metadata:
   name: engineering-tools
@@ -399,7 +399,7 @@ spec:
 
 ---
 # 2. Create shared OIDC config for incoming client authentication
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPOIDCConfig
 metadata:
   name: engineering-oidc
@@ -411,7 +411,7 @@ spec:
 
 ---
 # 3. Create authentication config for GitHub backend
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPExternalAuthConfig
 metadata:
   name: github-token-config
@@ -428,7 +428,7 @@ spec:
 
 ---
 # 4. Create backend MCPServer
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: github-mcp
@@ -443,7 +443,7 @@ spec:
 
 ---
 # 5. Create VirtualMCPServer (discovered mode)
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: VirtualMCPServer
 metadata:
   name: engineering-vmcp
@@ -758,3 +758,4 @@ remove the auth reference.
 
 - [Configure vMCP servers](./configuration.mdx)
 - [VirtualMCPServer CRD specification](../reference/crds/virtualmcpserver.mdx)
+
diff --git a/docs/toolhive/guides-vmcp/composite-tools.mdx b/docs/toolhive/guides-vmcp/composite-tools.mdx
index faa2c6fe..3ab387ef 100644
--- a/docs/toolhive/guides-vmcp/composite-tools.mdx
+++ b/docs/toolhive/guides-vmcp/composite-tools.mdx
@@ -37,7 +37,7 @@ Composite tools are defined in the VirtualMCPServer resource under
 `spec.config.compositeTools`:
 
 ```yaml
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: VirtualMCPServer
 metadata:
   name: my-vmcp
@@ -660,7 +660,7 @@ A VirtualMCPServer with an inline composite tool using the
 [arxiv-mcp-server](https://github.com/blazickjp/arxiv-mcp-server):
 
 ```yaml
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: VirtualMCPServer
 metadata:
   name: research-vmcp
@@ -736,3 +736,4 @@ spec:
 ## Related information
 
 - [Configure vMCP servers](./configuration.mdx)
+
diff --git a/docs/toolhive/guides-vmcp/configuration.mdx b/docs/toolhive/guides-vmcp/configuration.mdx
index 9df26fdd..cfcaf56f 100644
--- a/docs/toolhive/guides-vmcp/configuration.mdx
+++ b/docs/toolhive/guides-vmcp/configuration.mdx
@@ -17,7 +17,7 @@ MCPRemoteProxy, and MCPServerEntry resources together.
 Create a basic MCPGroup:
 
 ```yaml
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPGroup
 metadata:
   name: my-group
@@ -39,7 +39,7 @@ vMCP supports three types of backends that can be added to an MCPGroup:
 MCPServer resources run container-based MCP servers in your cluster:
 
 ```yaml
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: fetch
@@ -57,7 +57,7 @@ MCPRemoteProxy resources proxy external remote MCP servers. They can be added to
 an MCPGroup for discovery by vMCP:
 
 ```yaml
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRemoteProxy
 metadata:
   name: context7-proxy
@@ -96,7 +96,7 @@ MCPServerEntry when you want to include a remote server in vMCP routing without
 the overhead of running a proxy.
 
 ```yaml
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServerEntry
 metadata:
   name: my-remote-tool
@@ -118,7 +118,7 @@ At minimum, a VirtualMCPServer requires a reference to an MCPGroup (via
 `groupRef`) and an authentication type:
 
 ```yaml
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: VirtualMCPServer
 metadata:
   name: my-vmcp
@@ -197,7 +197,7 @@ resource.
 Configure health monitoring in `spec.config.operational.failureHandling`:
 
 ```yaml
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: VirtualMCPServer
 metadata:
   name: my-vmcp
@@ -284,7 +284,7 @@ To enable health checks for remote workloads, set the
 `TOOLHIVE_REMOTE_HEALTHCHECKS` environment variable in the vMCP pod:
 
 ```yaml
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: VirtualMCPServer
 metadata:
   name: my-vmcp
@@ -324,3 +324,4 @@ Backend discovery guide.
 - [Composite tools](./composite-tools.mdx)
 - [Authentication](./authentication.mdx)
 - [Proxy remote MCP servers](../guides-k8s/remote-mcp-proxy.mdx)
+
diff --git a/docs/toolhive/guides-vmcp/failure-handling.mdx b/docs/toolhive/guides-vmcp/failure-handling.mdx
index b56ce653..35c172fa 100644
--- a/docs/toolhive/guides-vmcp/failure-handling.mdx
+++ b/docs/toolhive/guides-vmcp/failure-handling.mdx
@@ -67,7 +67,7 @@ stateDiagram-v2
 Configure circuit breaker in the VirtualMCPServer resource:
 
 ```yaml
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: VirtualMCPServer
 metadata:
   name: my-vmcp
@@ -131,7 +131,7 @@ failure protection during active traffic.
 Configure how vMCP behaves when some backends are unavailable:
 
 ```yaml
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: VirtualMCPServer
 metadata:
   name: my-vmcp
@@ -265,7 +265,7 @@ more details on the `/status` endpoint.
 Detect failures quickly and fail fast:
 
 ```yaml
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: VirtualMCPServer
 metadata:
   name: production-vmcp
@@ -300,7 +300,7 @@ spec:
 Continue with available backends:
 
 ```yaml
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: VirtualMCPServer
 metadata:
   name: dev-vmcp
@@ -425,3 +425,4 @@ operational:
   `/status` endpoint
 - [Configuration guide](./configuration.mdx)
 - [VirtualMCPServer CRD specification](../reference/crds/virtualmcpserver.mdx)
+
diff --git a/docs/toolhive/guides-vmcp/optimizer.mdx b/docs/toolhive/guides-vmcp/optimizer.mdx
index 8a14af59..1ae71a39 100644
--- a/docs/toolhive/guides-vmcp/optimizer.mdx
+++ b/docs/toolhive/guides-vmcp/optimizer.mdx
@@ -70,7 +70,7 @@ Create an EmbeddingServer with default settings. This deploys a text embeddings
 inference (TEI) server using the `BAAI/bge-small-en-v1.5` model:
 
 ```yaml title="embedding-server.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: EmbeddingServer
 metadata:
   name: my-embedding
@@ -98,7 +98,7 @@ sensible defaults. You only need to add an explicit `optimizer` block if you
 want to [tune the parameters](#tune-the-optimizer).
 
 ```yaml title="VirtualMCPServer resource"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: VirtualMCPServer
 metadata:
   name: my-vmcp
@@ -152,7 +152,7 @@ The default TEI image (`cpu-latest`) is x86_64-only. If you are running on ARM64
 nodes (for example, Apple Silicon), override the image in your EmbeddingServer:
 
 ```yaml title="embedding-server.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: EmbeddingServer
 metadata:
   name: my-embedding
@@ -228,7 +228,7 @@ The EmbeddingServer runs two replicas with resource limits and a persistent
 volume for model caching, so restarts don't re-download the model:
 
 ```yaml title="embedding-server-full.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: EmbeddingServer
 metadata:
   name: full-embedding
@@ -252,7 +252,7 @@ EmbeddingServer is co-located with low-latency access. Increase this value if
 the embedding service is remote or under high load:
 
 ```yaml title="vmcp-with-optimizer.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: VirtualMCPServer
 metadata:
   name: full-vmcp
@@ -295,3 +295,4 @@ spec:
 - [Virtual MCP Server overview](../concepts/vmcp.mdx) - conceptual overview of
   vMCP
 - [VirtualMCPServer CRD specification](../reference/crds/virtualmcpserver.mdx)
+
diff --git a/docs/toolhive/guides-vmcp/quickstart.mdx b/docs/toolhive/guides-vmcp/quickstart.mdx
index 0f2f298d..07c888c3 100644
--- a/docs/toolhive/guides-vmcp/quickstart.mdx
+++ b/docs/toolhive/guides-vmcp/quickstart.mdx
@@ -32,7 +32,7 @@ Before starting this tutorial, make sure you have:
 First, create an MCPGroup to organize your backend MCP servers:
 
 ```yaml title="mcpgroup.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPGroup
 metadata:
   name: demo-tools
@@ -59,7 +59,7 @@ Deploy two MCP servers that will be aggregated. Both reference the `demo-tools`
 group in the `groupRef` field:
 
 ```yaml title="mcpservers.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: fetch
@@ -81,7 +81,7 @@ spec:
       cpu: '50m'
       memory: '64Mi'
 ---
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: osv
@@ -123,7 +123,7 @@ You should see both servers with `Ready` status before continuing.
 Create a VirtualMCPServer that aggregates both backends:
 
 ```yaml title="virtualmcpserver.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: VirtualMCPServer
 metadata:
   name: demo-vmcp
@@ -288,3 +288,4 @@ kubectl describe virtualmcpserver demo-vmcp -n toolhive-system
 ```
 
 </details>
+
diff --git a/docs/toolhive/guides-vmcp/telemetry-and-metrics.mdx b/docs/toolhive/guides-vmcp/telemetry-and-metrics.mdx
index 32b2cdfd..23b30bae 100644
--- a/docs/toolhive/guides-vmcp/telemetry-and-metrics.mdx
+++ b/docs/toolhive/guides-vmcp/telemetry-and-metrics.mdx
@@ -28,7 +28,7 @@ resources, Kubernetes-native secret references for OTLP auth headers, CA bundle
 ConfigMap references, and per-server `serviceName` overrides.
 
 ```yaml title="telemetry-config.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPTelemetryConfig
 metadata:
   name: shared-otel
@@ -48,7 +48,7 @@ spec:
 ```
 
 ```yaml title="virtualmcpserver.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: VirtualMCPServer
 metadata:
   name: my-vmcp
@@ -120,7 +120,7 @@ service:
 Then create an MCPTelemetryConfig resource that points to the collector:
 
 ```yaml
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPTelemetryConfig
 metadata:
   name: jaeger-otel
@@ -211,3 +211,4 @@ Each span includes attributes for the target backend (`target.workload_id`,
   telemetry for MCPServer resources
 - [OpenTelemetry tutorial](../integrations/opentelemetry.mdx) - set up a local
   observability stack
+
diff --git a/docs/toolhive/guides-vmcp/tool-aggregation.mdx b/docs/toolhive/guides-vmcp/tool-aggregation.mdx
index c1c130ac..c134e6d3 100644
--- a/docs/toolhive/guides-vmcp/tool-aggregation.mdx
+++ b/docs/toolhive/guides-vmcp/tool-aggregation.mdx
@@ -217,7 +217,7 @@ conflict resolution:
 
 ```yaml
 # MCPGroup to organize backend servers
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPGroup
 metadata:
   name: demo-tools
@@ -226,7 +226,7 @@ spec:
   description: Demo group for tool aggregation
 ---
 # First backend: fetch server
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: fetch
@@ -240,7 +240,7 @@ spec:
     name: demo-tools
 ---
 # Second backend: osv server
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: osv
@@ -254,7 +254,7 @@ spec:
     name: demo-tools
 ---
 # VirtualMCPServer aggregating both backends
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: VirtualMCPServer
 metadata:
   name: demo-vmcp
@@ -287,3 +287,4 @@ With this configuration, tools from each backend are prefixed:
 
 - [VirtualMCPServer configuration reference](./configuration.mdx)
 - [Customize MCP server tools](../guides-k8s/customize-tools.mdx)
+
diff --git a/docs/toolhive/integrations/aws-sts.mdx b/docs/toolhive/integrations/aws-sts.mdx
index 84e4d206..f5dc8c02 100644
--- a/docs/toolhive/integrations/aws-sts.mdx
+++ b/docs/toolhive/integrations/aws-sts.mdx
@@ -277,7 +277,7 @@ Create an `MCPExternalAuthConfig` resource that defines how ToolHive exchanges
 OIDC tokens for AWS credentials.
 
 ```yaml {4,7} title="aws-sts-auth-config.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPExternalAuthConfig
 metadata:
   name: aws-mcp-sts-auth
@@ -361,7 +361,7 @@ and references the authentication configuration from the previous step.
 First, create an MCPOIDCConfig resource with your identity provider settings:
 
 ```yaml title="aws-mcp-oidc.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPOIDCConfig
 metadata:
   name: aws-mcp-oidc
@@ -375,7 +375,7 @@ spec:
 Then create the MCPRemoteProxy:
 
 ```yaml {7,10-11,14-19} title="aws-mcp-remote-proxy.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRemoteProxy
 metadata:
   name: aws-mcp-proxy
@@ -663,7 +663,7 @@ the steps in
 (steps 1 through 4). Then deploy the `MCPRemoteProxy` with both references:
 
 ```yaml title="aws-mcp-remote-proxy-combined.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRemoteProxy
 metadata:
   name: aws-mcp-proxy
@@ -826,3 +826,4 @@ kubectl logs -n toolhive-system \
 ```
 
 </details>
+
diff --git a/docs/toolhive/integrations/okta.mdx b/docs/toolhive/integrations/okta.mdx
index e1cc44e3..d78b2ba3 100644
--- a/docs/toolhive/integrations/okta.mdx
+++ b/docs/toolhive/integrations/okta.mdx
@@ -129,7 +129,7 @@ Create the MCPServer resource without authentication to verify the basic
 deployment works:
 
 ```yaml title="github-mcpserver.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: github
@@ -183,7 +183,7 @@ MCPServer to reference it. Replace the placeholder values with the configuration
 values you collected in [Step 1](#collect-your-configuration-values):
 
 ```yaml title="github-mcpserver-oidc.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPOIDCConfig
 metadata:
   name: okta-oidc
@@ -194,7 +194,7 @@ spec:
     issuer: 'YOUR_ISSUER_URL'
     jwksUrl: 'YOUR_JWKS_URL'
 ---
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: github
@@ -295,7 +295,7 @@ Add the `authzConfig` section to reference the ConfigMap you just created. The
 highlighted lines show the new addition:
 
 ```yaml title="github-mcpserver-authz.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: github
@@ -495,3 +495,4 @@ common mistake is to use just the Okta domain without the authorization server
 path.
 
 </details>
+
diff --git a/docs/toolhive/integrations/opentelemetry.mdx b/docs/toolhive/integrations/opentelemetry.mdx
index c04a2a5c..c54eab24 100644
--- a/docs/toolhive/integrations/opentelemetry.mdx
+++ b/docs/toolhive/integrations/opentelemetry.mdx
@@ -499,7 +499,7 @@ curl http://localhost:$PORT/metrics
 Create an MCPServer resource with comprehensive telemetry configuration:
 
 ```yaml {18-30} title="fetch-with-telemetry.yml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: fetch-telemetry
@@ -993,3 +993,4 @@ Common troubleshooting steps:
    collector endpoint
 
 </details>
+
diff --git a/docs/toolhive/integrations/vault.mdx b/docs/toolhive/integrations/vault.mdx
index 4bb7eaa7..9a627ad6 100644
--- a/docs/toolhive/integrations/vault.mdx
+++ b/docs/toolhive/integrations/vault.mdx
@@ -159,7 +159,7 @@ injection. The key is using the `podTemplateMetadataOverrides` field to add
 annotations to the proxy runner pods:
 
 ```yaml title="github-mcp-with-vault.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: github-vault
@@ -285,3 +285,4 @@ kubectl get pod $MCP_POD_NAME -n toolhive-system -o jsonpath='{range .spec.conta
   https://developer.hashicorp.com/vault/tutorials/operations/production-hardening
 [vault-injector]:
   https://developer.hashicorp.com/vault/docs/platform/k8s/injector
+
diff --git a/docs/toolhive/reference/crds/embeddingserver.mdx b/docs/toolhive/reference/crds/embeddingserver.mdx
index b47e7051..ef1139db 100644
--- a/docs/toolhive/reference/crds/embeddingserver.mdx
+++ b/docs/toolhive/reference/crds/embeddingserver.mdx
@@ -8,13 +8,13 @@ toc_max_heading_level: 4
 
 `EmbeddingServer` defines a containerized embedding model server managed by the ToolHive operator. The [VirtualMCPServer](./virtualmcpserver.mdx) optimizer references an `EmbeddingServer` to generate vector embeddings for tool discovery.
 
-**API:** `toolhive.stacklok.dev/v1alpha1`
+**API:** `toolhive.stacklok.dev/v1beta1`
  · **Scope:** Namespaced · **Short names:** `emb`, `embedding`
 
 ## Example
 
 ```yaml title="embeddingserver.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: EmbeddingServer
 metadata:
   name: my-embeddingserver
diff --git a/docs/toolhive/reference/crds/mcpexternalauthconfig.mdx b/docs/toolhive/reference/crds/mcpexternalauthconfig.mdx
index 21386526..6d277afc 100644
--- a/docs/toolhive/reference/crds/mcpexternalauthconfig.mdx
+++ b/docs/toolhive/reference/crds/mcpexternalauthconfig.mdx
@@ -8,13 +8,13 @@ toc_max_heading_level: 4
 
 `MCPExternalAuthConfig` configures how an MCP server or proxy authenticates to external services via token exchange or an embedded authorization server. It is referenced by [MCPServer](./mcpserver.mdx), [MCPRemoteProxy](./mcpremoteproxy.mdx), [MCPServerEntry](./mcpserverentry.mdx), and [VirtualMCPServer](./virtualmcpserver.mdx).
 
-**API:** `toolhive.stacklok.dev/v1alpha1`
+**API:** `toolhive.stacklok.dev/v1beta1`
  · **Scope:** Namespaced · **Short names:** `extauth`, `mcpextauth`
 
 ## Example
 
 ```yaml title="mcpexternalauthconfig.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPExternalAuthConfig
 metadata:
   name: my-mcpexternalauthconfig
diff --git a/docs/toolhive/reference/crds/mcpgroup.mdx b/docs/toolhive/reference/crds/mcpgroup.mdx
index 58858fdc..afaef5a0 100644
--- a/docs/toolhive/reference/crds/mcpgroup.mdx
+++ b/docs/toolhive/reference/crds/mcpgroup.mdx
@@ -8,13 +8,13 @@ toc_max_heading_level: 4
 
 `MCPGroup` is a grouping construct for backend workloads. Other resources reference an `MCPGroup` by name to join a shared pool - for example, a [VirtualMCPServer](./virtualmcpserver.mdx) aggregates the tools exposed by every member of its referenced group.
 
-**API:** `toolhive.stacklok.dev/v1alpha1`
+**API:** `toolhive.stacklok.dev/v1beta1`
  · **Scope:** Namespaced · **Short names:** `mcpg`, `mcpgroup`
 
 ## Example
 
 ```yaml title="mcpgroup.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPGroup
 metadata:
   name: my-mcpgroup
diff --git a/docs/toolhive/reference/crds/mcpoidcconfig.mdx b/docs/toolhive/reference/crds/mcpoidcconfig.mdx
index bd1b3abb..6378e1dc 100644
--- a/docs/toolhive/reference/crds/mcpoidcconfig.mdx
+++ b/docs/toolhive/reference/crds/mcpoidcconfig.mdx
@@ -8,13 +8,13 @@ toc_max_heading_level: 4
 
 `MCPOIDCConfig` defines OIDC authentication settings that can be shared across multiple MCP workloads. [MCPServer](./mcpserver.mdx), [MCPRemoteProxy](./mcpremoteproxy.mdx), and [VirtualMCPServer](./virtualmcpserver.mdx) reference an `MCPOIDCConfig` via `spec.oidcConfigRef` to validate incoming tokens.
 
-**API:** `toolhive.stacklok.dev/v1alpha1`
+**API:** `toolhive.stacklok.dev/v1beta1`
  · **Scope:** Namespaced · **Short names:** `mcpoidc`
 
 ## Example
 
 ```yaml title="mcpoidcconfig.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPOIDCConfig
 metadata:
   name: my-mcpoidcconfig
diff --git a/docs/toolhive/reference/crds/mcpregistry.mdx b/docs/toolhive/reference/crds/mcpregistry.mdx
index bce1f42a..65d494ed 100644
--- a/docs/toolhive/reference/crds/mcpregistry.mdx
+++ b/docs/toolhive/reference/crds/mcpregistry.mdx
@@ -8,13 +8,13 @@ toc_max_heading_level: 4
 
 `MCPRegistry` deploys a [ToolHive Registry Server](../../guides-registry/intro.mdx) in the cluster. The operator watches `MCPRegistry` resources and provisions the Registry Server, its PostgreSQL backing, and the configured sources (Git, ConfigMap, URL, or Kubernetes discovery) that populate its catalog of MCP server definitions.
 
-**API:** `toolhive.stacklok.dev/v1alpha1`
+**API:** `toolhive.stacklok.dev/v1beta1`
  · **Scope:** Namespaced · **Short names:** `mcpreg`, `registry`
 
 ## Example
 
 ```yaml title="mcpregistry.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRegistry
 metadata:
   name: my-mcpregistry
diff --git a/docs/toolhive/reference/crds/mcpremoteproxy.mdx b/docs/toolhive/reference/crds/mcpremoteproxy.mdx
index c163513d..65c82f03 100644
--- a/docs/toolhive/reference/crds/mcpremoteproxy.mdx
+++ b/docs/toolhive/reference/crds/mcpremoteproxy.mdx
@@ -8,13 +8,13 @@ toc_max_heading_level: 4
 
 `MCPRemoteProxy` fronts a remote MCP server (reachable over HTTPS) with the same authentication, telemetry, and tool-filtering features that the operator applies to containerized servers. Use this when you want to apply ToolHive policies to a third-party hosted MCP endpoint.
 
-**API:** `toolhive.stacklok.dev/v1alpha1`
+**API:** `toolhive.stacklok.dev/v1beta1`
  · **Scope:** Namespaced · **Short names:** `rp`, `mcprp`
 
 ## Example
 
 ```yaml title="mcpremoteproxy.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRemoteProxy
 metadata:
   name: my-mcpremoteproxy
diff --git a/docs/toolhive/reference/crds/mcpserver.mdx b/docs/toolhive/reference/crds/mcpserver.mdx
index 4489bfb7..9792fc40 100644
--- a/docs/toolhive/reference/crds/mcpserver.mdx
+++ b/docs/toolhive/reference/crds/mcpserver.mdx
@@ -8,13 +8,13 @@ toc_max_heading_level: 4
 
 `MCPServer` defines a containerized MCP server managed by the ToolHive Kubernetes operator. The operator watches `MCPServer` resources and reconciles them into a running, proxied MCP server with the configured transport, authentication, telemetry, and tool filtering.
 
-**API:** `toolhive.stacklok.dev/v1alpha1`
+**API:** `toolhive.stacklok.dev/v1beta1`
  · **Scope:** Namespaced · **Short names:** `mcpserver`, `mcpservers`
 
 ## Example
 
 ```yaml title="mcpserver.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: my-mcpserver
diff --git a/docs/toolhive/reference/crds/mcpserverentry.mdx b/docs/toolhive/reference/crds/mcpserverentry.mdx
index 60f07127..cb611bd8 100644
--- a/docs/toolhive/reference/crds/mcpserverentry.mdx
+++ b/docs/toolhive/reference/crds/mcpserverentry.mdx
@@ -8,13 +8,13 @@ toc_max_heading_level: 4
 
 `MCPServerEntry` declares a remote MCP server as a first-class member of an [MCPGroup](./mcpgroup.mdx) without running a full [MCPRemoteProxy](./mcpremoteproxy.mdx). Entries appear in registry listings and participate in group-scoped aggregations like a [VirtualMCPServer](./virtualmcpserver.mdx).
 
-**API:** `toolhive.stacklok.dev/v1alpha1`
+**API:** `toolhive.stacklok.dev/v1beta1`
  · **Scope:** Namespaced · **Short names:** `mcpentry`
 
 ## Example
 
 ```yaml title="mcpserverentry.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServerEntry
 metadata:
   name: my-mcpserverentry
diff --git a/docs/toolhive/reference/crds/mcptelemetryconfig.mdx b/docs/toolhive/reference/crds/mcptelemetryconfig.mdx
index 23479459..b81e7bec 100644
--- a/docs/toolhive/reference/crds/mcptelemetryconfig.mdx
+++ b/docs/toolhive/reference/crds/mcptelemetryconfig.mdx
@@ -8,13 +8,13 @@ toc_max_heading_level: 4
 
 `MCPTelemetryConfig` defines telemetry settings that can be shared across multiple MCP workloads. [MCPServer](./mcpserver.mdx), [MCPRemoteProxy](./mcpremoteproxy.mdx), and [VirtualMCPServer](./virtualmcpserver.mdx) reference a single `MCPTelemetryConfig` to emit traces and metrics to a common backend.
 
-**API:** `toolhive.stacklok.dev/v1alpha1`
+**API:** `toolhive.stacklok.dev/v1beta1`
  · **Scope:** Namespaced · **Short names:** `mcpotel`
 
 ## Example
 
 ```yaml title="mcptelemetryconfig.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPTelemetryConfig
 metadata:
   name: my-mcptelemetryconfig
diff --git a/docs/toolhive/reference/crds/mcptoolconfig.mdx b/docs/toolhive/reference/crds/mcptoolconfig.mdx
index e20fe728..fe0c696c 100644
--- a/docs/toolhive/reference/crds/mcptoolconfig.mdx
+++ b/docs/toolhive/reference/crds/mcptoolconfig.mdx
@@ -8,13 +8,13 @@ toc_max_heading_level: 4
 
 `MCPToolConfig` defines tool-filtering and renaming rules that can be shared across MCP workloads. [MCPServer](./mcpserver.mdx), [MCPRemoteProxy](./mcpremoteproxy.mdx), and [VirtualMCPServer](./virtualmcpserver.mdx) reference an `MCPToolConfig` via `spec.toolConfigRef` to customize the tool surface their clients see.
 
-**API:** `toolhive.stacklok.dev/v1alpha1`
+**API:** `toolhive.stacklok.dev/v1beta1`
  · **Scope:** Namespaced · **Short names:** `tc`, `toolconfig`
 
 ## Example
 
 ```yaml title="mcptoolconfig.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPToolConfig
 metadata:
   name: my-mcptoolconfig
diff --git a/docs/toolhive/reference/crds/virtualmcpcompositetooldefinition.mdx b/docs/toolhive/reference/crds/virtualmcpcompositetooldefinition.mdx
index fc942327..07ca47c7 100644
--- a/docs/toolhive/reference/crds/virtualmcpcompositetooldefinition.mdx
+++ b/docs/toolhive/reference/crds/virtualmcpcompositetooldefinition.mdx
@@ -8,13 +8,13 @@ toc_max_heading_level: 4
 
 `VirtualMCPCompositeToolDefinition` defines a reusable composite tool workflow - a sequence of backend tool calls exposed to clients as a single high-level tool. Referenced by a [VirtualMCPServer](./virtualmcpserver.mdx) via `spec.config.compositeToolRefs`.
 
-**API:** `toolhive.stacklok.dev/v1alpha1`
+**API:** `toolhive.stacklok.dev/v1beta1`
  · **Scope:** Namespaced · **Short names:** `vmcpctd`, `compositetool`
 
 ## Example
 
 ```yaml title="virtualmcpcompositetooldefinition.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: VirtualMCPCompositeToolDefinition
 metadata:
   name: my-virtualmcpcompositetooldefinition
diff --git a/docs/toolhive/reference/crds/virtualmcpserver.mdx b/docs/toolhive/reference/crds/virtualmcpserver.mdx
index 4d83ff49..b305ae6a 100644
--- a/docs/toolhive/reference/crds/virtualmcpserver.mdx
+++ b/docs/toolhive/reference/crds/virtualmcpserver.mdx
@@ -8,13 +8,13 @@ toc_max_heading_level: 4
 
 `VirtualMCPServer` (vMCP) aggregates the backend workloads belonging to an [MCPGroup](./mcpgroup.mdx) into a single endpoint. Clients see one MCP server; the operator handles tool aggregation, conflict resolution, auth, and optional composite tool workflows behind the scenes.
 
-**API:** `toolhive.stacklok.dev/v1alpha1`
+**API:** `toolhive.stacklok.dev/v1beta1`
  · **Scope:** Namespaced · **Short names:** `vmcp`, `virtualmcp`
 
 ## Example
 
 ```yaml title="virtualmcpserver.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: VirtualMCPServer
 metadata:
   name: my-virtualmcpserver
diff --git a/docs/toolhive/tutorials/mcp-optimizer.mdx b/docs/toolhive/tutorials/mcp-optimizer.mdx
index 337db246..2b47643f 100644
--- a/docs/toolhive/tutorials/mcp-optimizer.mdx
+++ b/docs/toolhive/tutorials/mcp-optimizer.mdx
@@ -95,7 +95,7 @@ Create an MCPGroup to organize the backend MCP servers that the optimizer will
 index and route to:
 
 ```yaml title="mcpgroup.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPGroup
 metadata:
   name: optimizer-demo
@@ -114,7 +114,7 @@ Next, deploy two MCP servers in the group. Both reference `optimizer-demo` in
 the `groupRef` field:
 
 ```yaml {11-12,31-32} title="mcpservers.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: fetch
@@ -134,7 +134,7 @@ spec:
       cpu: '50m'
       memory: '64Mi'
 ---
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: osv
@@ -189,7 +189,7 @@ Create an EmbeddingServer with default settings. This deploys the
 Apple Silicon with kind), uncomment the `image` line to use the ARM64 build:
 
 ```yaml title="embedding-server.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: EmbeddingServer
 metadata:
   name: optimizer-embedding
@@ -228,7 +228,7 @@ optimizer. Adding `embeddingServerRef` is the only change needed to enable the
 optimizer - sensible defaults are applied automatically:
 
 ```yaml title="virtualmcpserver.yaml"
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: VirtualMCPServer
 metadata:
   name: optimizer-vmcp
@@ -391,3 +391,4 @@ kind delete cluster --name toolhive
   approach without Kubernetes (legacy, being replaced by the vMCP path)
 - [Quickstart: Kubernetes Operator](../guides-k8s/quickstart.mdx) - prerequisite
   tutorial
+
diff --git a/static/api-specs/crds/embeddingservers.example.yaml b/static/api-specs/crds/embeddingservers.example.yaml
index 46b7e686..34b19103 100644
--- a/static/api-specs/crds/embeddingservers.example.yaml
+++ b/static/api-specs/crds/embeddingservers.example.yaml
@@ -1,4 +1,4 @@
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: EmbeddingServer
 metadata:
   name: my-embeddingserver
diff --git a/static/api-specs/crds/embeddingservers.schema.json b/static/api-specs/crds/embeddingservers.schema.json
index 8ddc9780..5b6d2253 100644
--- a/static/api-specs/crds/embeddingservers.schema.json
+++ b/static/api-specs/crds/embeddingservers.schema.json
@@ -4,7 +4,7 @@
   "description": "EmbeddingServer is the Schema for the embeddingservers API",
   "x-kubernetes-group": "toolhive.stacklok.dev",
   "x-kubernetes-kind": "EmbeddingServer",
-  "x-kubernetes-version": "v1alpha1",
+  "x-kubernetes-version": "v1beta1",
   "x-kubernetes-plural": "embeddingservers",
   "x-kubernetes-short-names": [
     "emb",
diff --git a/static/api-specs/crds/index.json b/static/api-specs/crds/index.json
index cd98ea98..df6b84a2 100644
--- a/static/api-specs/crds/index.json
+++ b/static/api-specs/crds/index.json
@@ -3,7 +3,7 @@
     "kind": "EmbeddingServer",
     "plural": "embeddingservers",
     "group": "toolhive.stacklok.dev",
-    "version": "v1alpha1",
+    "version": "v1beta1",
     "shortNames": [
       "emb",
       "embedding"
@@ -25,7 +25,7 @@
     "kind": "MCPExternalAuthConfig",
     "plural": "mcpexternalauthconfigs",
     "group": "toolhive.stacklok.dev",
-    "version": "v1alpha1",
+    "version": "v1beta1",
     "shortNames": [
       "extauth",
       "mcpextauth"
@@ -68,7 +68,7 @@
     "kind": "MCPGroup",
     "plural": "mcpgroups",
     "group": "toolhive.stacklok.dev",
-    "version": "v1alpha1",
+    "version": "v1beta1",
     "shortNames": [
       "mcpg",
       "mcpgroup"
@@ -109,7 +109,7 @@
     "kind": "MCPOIDCConfig",
     "plural": "mcpoidcconfigs",
     "group": "toolhive.stacklok.dev",
-    "version": "v1alpha1",
+    "version": "v1beta1",
     "shortNames": [
       "mcpoidc"
     ],
@@ -142,7 +142,7 @@
     "kind": "MCPRegistry",
     "plural": "mcpregistries",
     "group": "toolhive.stacklok.dev",
-    "version": "v1alpha1",
+    "version": "v1beta1",
     "shortNames": [
       "mcpreg",
       "registry"
@@ -157,7 +157,7 @@
     "kind": "MCPRemoteProxy",
     "plural": "mcpremoteproxies",
     "group": "toolhive.stacklok.dev",
-    "version": "v1alpha1",
+    "version": "v1beta1",
     "shortNames": [
       "rp",
       "mcprp"
@@ -204,7 +204,7 @@
     "kind": "MCPServerEntry",
     "plural": "mcpserverentries",
     "group": "toolhive.stacklok.dev",
-    "version": "v1alpha1",
+    "version": "v1beta1",
     "shortNames": [
       "mcpentry"
     ],
@@ -231,7 +231,7 @@
     "kind": "MCPServer",
     "plural": "mcpservers",
     "group": "toolhive.stacklok.dev",
-    "version": "v1alpha1",
+    "version": "v1beta1",
     "shortNames": [
       "mcpserver",
       "mcpservers"
@@ -278,7 +278,7 @@
     "kind": "MCPTelemetryConfig",
     "plural": "mcptelemetryconfigs",
     "group": "toolhive.stacklok.dev",
-    "version": "v1alpha1",
+    "version": "v1beta1",
     "shortNames": [
       "mcpotel"
     ],
@@ -311,7 +311,7 @@
     "kind": "MCPToolConfig",
     "plural": "mcptoolconfigs",
     "group": "toolhive.stacklok.dev",
-    "version": "v1alpha1",
+    "version": "v1beta1",
     "shortNames": [
       "tc",
       "toolconfig"
@@ -345,7 +345,7 @@
     "kind": "VirtualMCPCompositeToolDefinition",
     "plural": "virtualmcpcompositetooldefinitions",
     "group": "toolhive.stacklok.dev",
-    "version": "v1alpha1",
+    "version": "v1beta1",
     "shortNames": [
       "vmcpctd",
       "compositetool"
@@ -367,7 +367,7 @@
     "kind": "VirtualMCPServer",
     "plural": "virtualmcpservers",
     "group": "toolhive.stacklok.dev",
-    "version": "v1alpha1",
+    "version": "v1beta1",
     "shortNames": [
       "vmcp",
       "virtualmcp"
diff --git a/static/api-specs/crds/mcpexternalauthconfigs.example.yaml b/static/api-specs/crds/mcpexternalauthconfigs.example.yaml
index 77320fba..aef10ac3 100644
--- a/static/api-specs/crds/mcpexternalauthconfigs.example.yaml
+++ b/static/api-specs/crds/mcpexternalauthconfigs.example.yaml
@@ -1,4 +1,4 @@
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPExternalAuthConfig
 metadata:
   name: my-mcpexternalauthconfig
diff --git a/static/api-specs/crds/mcpexternalauthconfigs.schema.json b/static/api-specs/crds/mcpexternalauthconfigs.schema.json
index b929346d..31241e25 100644
--- a/static/api-specs/crds/mcpexternalauthconfigs.schema.json
+++ b/static/api-specs/crds/mcpexternalauthconfigs.schema.json
@@ -4,7 +4,7 @@
   "description": "MCPExternalAuthConfig is the Schema for the mcpexternalauthconfigs API.\nMCPExternalAuthConfig resources are namespace-scoped and can only be referenced by\nMCPServer resources within the same namespace. Cross-namespace references\nare not supported for security and isolation reasons.",
   "x-kubernetes-group": "toolhive.stacklok.dev",
   "x-kubernetes-kind": "MCPExternalAuthConfig",
-  "x-kubernetes-version": "v1alpha1",
+  "x-kubernetes-version": "v1beta1",
   "x-kubernetes-plural": "mcpexternalauthconfigs",
   "x-kubernetes-short-names": [
     "extauth",
diff --git a/static/api-specs/crds/mcpgroups.example.yaml b/static/api-specs/crds/mcpgroups.example.yaml
index f0ce93e3..1c6dd73a 100644
--- a/static/api-specs/crds/mcpgroups.example.yaml
+++ b/static/api-specs/crds/mcpgroups.example.yaml
@@ -1,4 +1,4 @@
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPGroup
 metadata:
   name: my-mcpgroup
diff --git a/static/api-specs/crds/mcpgroups.schema.json b/static/api-specs/crds/mcpgroups.schema.json
index f1f5a3c4..e827b3a1 100644
--- a/static/api-specs/crds/mcpgroups.schema.json
+++ b/static/api-specs/crds/mcpgroups.schema.json
@@ -4,7 +4,7 @@
   "description": "MCPGroup is the Schema for the mcpgroups API",
   "x-kubernetes-group": "toolhive.stacklok.dev",
   "x-kubernetes-kind": "MCPGroup",
-  "x-kubernetes-version": "v1alpha1",
+  "x-kubernetes-version": "v1beta1",
   "x-kubernetes-plural": "mcpgroups",
   "x-kubernetes-short-names": [
     "mcpg",
diff --git a/static/api-specs/crds/mcpoidcconfigs.example.yaml b/static/api-specs/crds/mcpoidcconfigs.example.yaml
index d59addeb..6e394fe1 100644
--- a/static/api-specs/crds/mcpoidcconfigs.example.yaml
+++ b/static/api-specs/crds/mcpoidcconfigs.example.yaml
@@ -1,4 +1,4 @@
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPOIDCConfig
 metadata:
   name: my-mcpoidcconfig
diff --git a/static/api-specs/crds/mcpoidcconfigs.schema.json b/static/api-specs/crds/mcpoidcconfigs.schema.json
index 669d97df..158e894b 100644
--- a/static/api-specs/crds/mcpoidcconfigs.schema.json
+++ b/static/api-specs/crds/mcpoidcconfigs.schema.json
@@ -4,7 +4,7 @@
   "description": "MCPOIDCConfig is the Schema for the mcpoidcconfigs API.\nMCPOIDCConfig resources are namespace-scoped and can only be referenced by\nMCPServer resources within the same namespace. Cross-namespace references\nare not supported for security and isolation reasons.",
   "x-kubernetes-group": "toolhive.stacklok.dev",
   "x-kubernetes-kind": "MCPOIDCConfig",
-  "x-kubernetes-version": "v1alpha1",
+  "x-kubernetes-version": "v1beta1",
   "x-kubernetes-plural": "mcpoidcconfigs",
   "x-kubernetes-short-names": [
     "mcpoidc"
diff --git a/static/api-specs/crds/mcpregistries.example.yaml b/static/api-specs/crds/mcpregistries.example.yaml
index 5e941635..4ae55608 100644
--- a/static/api-specs/crds/mcpregistries.example.yaml
+++ b/static/api-specs/crds/mcpregistries.example.yaml
@@ -1,4 +1,4 @@
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRegistry
 metadata:
   name: my-mcpregistry
diff --git a/static/api-specs/crds/mcpregistries.schema.json b/static/api-specs/crds/mcpregistries.schema.json
index ff151c13..89915cf4 100644
--- a/static/api-specs/crds/mcpregistries.schema.json
+++ b/static/api-specs/crds/mcpregistries.schema.json
@@ -4,7 +4,7 @@
   "description": "MCPRegistry is the Schema for the mcpregistries API",
   "x-kubernetes-group": "toolhive.stacklok.dev",
   "x-kubernetes-kind": "MCPRegistry",
-  "x-kubernetes-version": "v1alpha1",
+  "x-kubernetes-version": "v1beta1",
   "x-kubernetes-plural": "mcpregistries",
   "x-kubernetes-short-names": [
     "mcpreg",
diff --git a/static/api-specs/crds/mcpremoteproxies.example.yaml b/static/api-specs/crds/mcpremoteproxies.example.yaml
index f4ec6f8a..4e06a587 100644
--- a/static/api-specs/crds/mcpremoteproxies.example.yaml
+++ b/static/api-specs/crds/mcpremoteproxies.example.yaml
@@ -1,4 +1,4 @@
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPRemoteProxy
 metadata:
   name: my-mcpremoteproxy
diff --git a/static/api-specs/crds/mcpremoteproxies.schema.json b/static/api-specs/crds/mcpremoteproxies.schema.json
index 20424e68..a5587643 100644
--- a/static/api-specs/crds/mcpremoteproxies.schema.json
+++ b/static/api-specs/crds/mcpremoteproxies.schema.json
@@ -4,7 +4,7 @@
   "description": "MCPRemoteProxy is the Schema for the mcpremoteproxies API\nIt enables proxying remote MCP servers with authentication, authorization, audit logging, and tool filtering",
   "x-kubernetes-group": "toolhive.stacklok.dev",
   "x-kubernetes-kind": "MCPRemoteProxy",
-  "x-kubernetes-version": "v1alpha1",
+  "x-kubernetes-version": "v1beta1",
   "x-kubernetes-plural": "mcpremoteproxies",
   "x-kubernetes-short-names": [
     "rp",
diff --git a/static/api-specs/crds/mcpserverentries.example.yaml b/static/api-specs/crds/mcpserverentries.example.yaml
index 2a7384f3..cdc8eb58 100644
--- a/static/api-specs/crds/mcpserverentries.example.yaml
+++ b/static/api-specs/crds/mcpserverentries.example.yaml
@@ -1,4 +1,4 @@
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServerEntry
 metadata:
   name: my-mcpserverentry
diff --git a/static/api-specs/crds/mcpserverentries.schema.json b/static/api-specs/crds/mcpserverentries.schema.json
index 8acc33ba..ed37c587 100644
--- a/static/api-specs/crds/mcpserverentries.schema.json
+++ b/static/api-specs/crds/mcpserverentries.schema.json
@@ -4,7 +4,7 @@
   "description": "MCPServerEntry is the Schema for the mcpserverentries API.\nIt declares a remote MCP server endpoint for vMCP discovery and routing\nwithout deploying any infrastructure.",
   "x-kubernetes-group": "toolhive.stacklok.dev",
   "x-kubernetes-kind": "MCPServerEntry",
-  "x-kubernetes-version": "v1alpha1",
+  "x-kubernetes-version": "v1beta1",
   "x-kubernetes-plural": "mcpserverentries",
   "x-kubernetes-short-names": [
     "mcpentry"
diff --git a/static/api-specs/crds/mcpservers.example.yaml b/static/api-specs/crds/mcpservers.example.yaml
index b02c28a8..470f1903 100644
--- a/static/api-specs/crds/mcpservers.example.yaml
+++ b/static/api-specs/crds/mcpservers.example.yaml
@@ -1,4 +1,4 @@
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPServer
 metadata:
   name: my-mcpserver
diff --git a/static/api-specs/crds/mcpservers.schema.json b/static/api-specs/crds/mcpservers.schema.json
index 148bceb6..395fb731 100644
--- a/static/api-specs/crds/mcpservers.schema.json
+++ b/static/api-specs/crds/mcpservers.schema.json
@@ -4,7 +4,7 @@
   "description": "MCPServer is the Schema for the mcpservers API",
   "x-kubernetes-group": "toolhive.stacklok.dev",
   "x-kubernetes-kind": "MCPServer",
-  "x-kubernetes-version": "v1alpha1",
+  "x-kubernetes-version": "v1beta1",
   "x-kubernetes-plural": "mcpservers",
   "x-kubernetes-short-names": [
     "mcpserver",
diff --git a/static/api-specs/crds/mcptelemetryconfigs.example.yaml b/static/api-specs/crds/mcptelemetryconfigs.example.yaml
index e630b142..d1a26f4a 100644
--- a/static/api-specs/crds/mcptelemetryconfigs.example.yaml
+++ b/static/api-specs/crds/mcptelemetryconfigs.example.yaml
@@ -1,4 +1,4 @@
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPTelemetryConfig
 metadata:
   name: my-mcptelemetryconfig
diff --git a/static/api-specs/crds/mcptelemetryconfigs.schema.json b/static/api-specs/crds/mcptelemetryconfigs.schema.json
index 4aecc789..4f299679 100644
--- a/static/api-specs/crds/mcptelemetryconfigs.schema.json
+++ b/static/api-specs/crds/mcptelemetryconfigs.schema.json
@@ -4,7 +4,7 @@
   "description": "MCPTelemetryConfig is the Schema for the mcptelemetryconfigs API.\nMCPTelemetryConfig resources are namespace-scoped and can only be referenced by\nMCPServer resources within the same namespace. Cross-namespace references\nare not supported for security and isolation reasons.",
   "x-kubernetes-group": "toolhive.stacklok.dev",
   "x-kubernetes-kind": "MCPTelemetryConfig",
-  "x-kubernetes-version": "v1alpha1",
+  "x-kubernetes-version": "v1beta1",
   "x-kubernetes-plural": "mcptelemetryconfigs",
   "x-kubernetes-short-names": [
     "mcpotel"
diff --git a/static/api-specs/crds/mcptoolconfigs.example.yaml b/static/api-specs/crds/mcptoolconfigs.example.yaml
index 9b8de9ca..d911f3a6 100644
--- a/static/api-specs/crds/mcptoolconfigs.example.yaml
+++ b/static/api-specs/crds/mcptoolconfigs.example.yaml
@@ -1,4 +1,4 @@
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: MCPToolConfig
 metadata:
   name: my-mcptoolconfig
diff --git a/static/api-specs/crds/mcptoolconfigs.schema.json b/static/api-specs/crds/mcptoolconfigs.schema.json
index fbe41e6b..9efb42fc 100644
--- a/static/api-specs/crds/mcptoolconfigs.schema.json
+++ b/static/api-specs/crds/mcptoolconfigs.schema.json
@@ -4,7 +4,7 @@
   "description": "MCPToolConfig is the Schema for the mcptoolconfigs API.\nMCPToolConfig resources are namespace-scoped and can only be referenced by\nMCPServer resources within the same namespace. Cross-namespace references\nare not supported for security and isolation reasons.",
   "x-kubernetes-group": "toolhive.stacklok.dev",
   "x-kubernetes-kind": "MCPToolConfig",
-  "x-kubernetes-version": "v1alpha1",
+  "x-kubernetes-version": "v1beta1",
   "x-kubernetes-plural": "mcptoolconfigs",
   "x-kubernetes-short-names": [
     "tc",
diff --git a/static/api-specs/crds/virtualmcpcompositetooldefinitions.example.yaml b/static/api-specs/crds/virtualmcpcompositetooldefinitions.example.yaml
index e588ae95..cfae92d1 100644
--- a/static/api-specs/crds/virtualmcpcompositetooldefinitions.example.yaml
+++ b/static/api-specs/crds/virtualmcpcompositetooldefinitions.example.yaml
@@ -1,4 +1,4 @@
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: VirtualMCPCompositeToolDefinition
 metadata:
   name: my-virtualmcpcompositetooldefinition
diff --git a/static/api-specs/crds/virtualmcpcompositetooldefinitions.schema.json b/static/api-specs/crds/virtualmcpcompositetooldefinitions.schema.json
index c878929c..c2320024 100644
--- a/static/api-specs/crds/virtualmcpcompositetooldefinitions.schema.json
+++ b/static/api-specs/crds/virtualmcpcompositetooldefinitions.schema.json
@@ -4,7 +4,7 @@
   "description": "VirtualMCPCompositeToolDefinition is the Schema for the virtualmcpcompositetooldefinitions API\nVirtualMCPCompositeToolDefinition defines reusable composite workflows that can be referenced\nby multiple VirtualMCPServer instances",
   "x-kubernetes-group": "toolhive.stacklok.dev",
   "x-kubernetes-kind": "VirtualMCPCompositeToolDefinition",
-  "x-kubernetes-version": "v1alpha1",
+  "x-kubernetes-version": "v1beta1",
   "x-kubernetes-plural": "virtualmcpcompositetooldefinitions",
   "x-kubernetes-short-names": [
     "vmcpctd",
diff --git a/static/api-specs/crds/virtualmcpservers.example.yaml b/static/api-specs/crds/virtualmcpservers.example.yaml
index 664a53df..20167256 100644
--- a/static/api-specs/crds/virtualmcpservers.example.yaml
+++ b/static/api-specs/crds/virtualmcpservers.example.yaml
@@ -1,4 +1,4 @@
-apiVersion: toolhive.stacklok.dev/v1alpha1
+apiVersion: toolhive.stacklok.dev/v1beta1
 kind: VirtualMCPServer
 metadata:
   name: my-virtualmcpserver
diff --git a/static/api-specs/crds/virtualmcpservers.schema.json b/static/api-specs/crds/virtualmcpservers.schema.json
index 03f5db70..d380fbd3 100644
--- a/static/api-specs/crds/virtualmcpservers.schema.json
+++ b/static/api-specs/crds/virtualmcpservers.schema.json
@@ -4,7 +4,7 @@
   "description": "VirtualMCPServer is the Schema for the virtualmcpservers API\nVirtualMCPServer aggregates multiple backend MCPServers into a unified endpoint",
   "x-kubernetes-group": "toolhive.stacklok.dev",
   "x-kubernetes-kind": "VirtualMCPServer",
-  "x-kubernetes-version": "v1alpha1",
+  "x-kubernetes-version": "v1beta1",
   "x-kubernetes-plural": "virtualmcpservers",
   "x-kubernetes-short-names": [
     "vmcp",
diff --git a/static/api-specs/toolhive-api.yaml b/static/api-specs/toolhive-api.yaml
index 5fc9d245..e6c07a3e 100644
--- a/static/api-specs/toolhive-api.yaml
+++ b/static/api-specs/toolhive-api.yaml
@@ -31,7 +31,7 @@ components:
           description: Version is the schema version of the registry
           type: string
       type: object
-    github_com_stacklok_toolhive_cmd_thv-operator_api_v1alpha1.RateLimitBucket:
+    github_com_stacklok_toolhive_cmd_thv-operator_api_v1beta1.RateLimitBucket:
       description: |-
         PerUser token bucket configuration for this tool.
         +optional
@@ -47,15 +47,15 @@ components:
         refillPeriod:
           $ref: '#/components/schemas/v1.Duration'
       type: object
-    github_com_stacklok_toolhive_cmd_thv-operator_api_v1alpha1.RateLimitConfig:
+    github_com_stacklok_toolhive_cmd_thv-operator_api_v1beta1.RateLimitConfig:
       description: |-
         RateLimitConfig contains the CRD rate limiting configuration.
         When set, rate limiting middleware is added to the proxy middleware chain.
       properties:
         perUser:
-          $ref: '#/components/schemas/github_com_stacklok_toolhive_cmd_thv-operator_api_v1alpha1.RateLimitBucket'
+          $ref: '#/components/schemas/github_com_stacklok_toolhive_cmd_thv-operator_api_v1beta1.RateLimitBucket'
         shared:
-          $ref: '#/components/schemas/github_com_stacklok_toolhive_cmd_thv-operator_api_v1alpha1.RateLimitBucket'
+          $ref: '#/components/schemas/github_com_stacklok_toolhive_cmd_thv-operator_api_v1beta1.RateLimitBucket'
         tools:
           description: |-
             Tools defines per-tool rate limit overrides.
@@ -65,11 +65,11 @@ components:
             +listMapKey=name
             +optional
           items:
-            $ref: '#/components/schemas/github_com_stacklok_toolhive_cmd_thv-operator_api_v1alpha1.ToolRateLimitConfig'
+            $ref: '#/components/schemas/github_com_stacklok_toolhive_cmd_thv-operator_api_v1beta1.ToolRateLimitConfig'
           type: array
           uniqueItems: false
       type: object
-    github_com_stacklok_toolhive_cmd_thv-operator_api_v1alpha1.ToolRateLimitConfig:
+    github_com_stacklok_toolhive_cmd_thv-operator_api_v1beta1.ToolRateLimitConfig:
       properties:
         name:
           description: |-
@@ -78,9 +78,9 @@ components:
             +kubebuilder:validation:MinLength=1
           type: string
         perUser:
-          $ref: '#/components/schemas/github_com_stacklok_toolhive_cmd_thv-operator_api_v1alpha1.RateLimitBucket'
+          $ref: '#/components/schemas/github_com_stacklok_toolhive_cmd_thv-operator_api_v1beta1.RateLimitBucket'
         shared:
-          $ref: '#/components/schemas/github_com_stacklok_toolhive_cmd_thv-operator_api_v1alpha1.RateLimitBucket'
+          $ref: '#/components/schemas/github_com_stacklok_toolhive_cmd_thv-operator_api_v1beta1.RateLimitBucket'
       type: object
     github_com_stacklok_toolhive_pkg_audit.Config:
       description: |-
@@ -1213,7 +1213,7 @@ components:
           type: array
           uniqueItems: false
         rate_limit_config:
-          $ref: '#/components/schemas/github_com_stacklok_toolhive_cmd_thv-operator_api_v1alpha1.RateLimitConfig'
+          $ref: '#/components/schemas/github_com_stacklok_toolhive_cmd_thv-operator_api_v1beta1.RateLimitConfig'
         rate_limit_namespace:
           description: RateLimitNamespace is the Kubernetes namespace for Redis key
             derivation.