Document v1beta1 CRD graduation and redirectUri default for v0.23.1

Bump apiVersion to toolhive.stacklok.dev/v1beta1 across 39 docs (all
manifest examples except the "before" blocks in migrate-to-v1beta1),
add a v0.23.0 section to the migration guide covering the storage
version promotion and zero-downtime upgrade path, and document the new
{resourceUrl}/oauth/callback default applied when redirectUri is empty
on upstream OIDC/OAuth2 providers.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: github-actions[bot]

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

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
@@ -788,6 +788,53 @@ refresh-token state), add `prompt: 'consent'` alongside `access_type: 'offline'`
 - Google then shows the consent screen on every login and re-issues a refresh
   token each time.
 
+### Default callback URL for upstream providers
+
+Starting in v0.23.0, the `redirectUri` field on an upstream provider's
+`oidcConfig` or `oauth2Config` is optional. When you omit it, the operator
+defaults it to `{resourceUrl}/oauth/callback`, where `resourceUrl` is the value
+from the MCPServer's `oidcConfigRef.resourceUrl` (the same URL the embedded
+authorization server advertises as its protected resource).
+
+```yaml title="Upstream provider with defaulted redirect URI"
+# Assumes the MCPServer references this config with:
+#   oidcConfigRef:
+#     resourceUrl: https://mcp.example.com/mcp
+#
+# With no redirectUri set, the operator uses
+# https://mcp.example.com/mcp/oauth/callback
+upstreamProviders:
+  - name: google
+    type: oidc
+    oidcConfig:
+      issuerUrl: 'https://accounts.google.com'
+      clientId: '<YOUR_GOOGLE_CLIENT_ID>'
+      clientSecretRef:
+        name: upstream-idp-secret
+        key: client-secret
+```
+
+Set `redirectUri` explicitly if your upstream provider is registered with a
+different callback path, or if your MCPServer does not set `resourceUrl` (in
+which case no default is applied):
+
+```yaml title="Upstream provider with explicit redirect URI"
+upstreamProviders:
+  - name: google
+    type: oidc
+    oidcConfig:
+      issuerUrl: 'https://accounts.google.com'
+      clientId: '<YOUR_GOOGLE_CLIENT_ID>'
+      # highlight-next-line
+      redirectUri: 'https://mcp.example.com/custom/callback'
+      clientSecretRef:
+        name: upstream-idp-secret
+        key: client-secret
+```
+
+Whichever value ends up in effect - defaulted or explicit - must exactly match
+the redirect URI registered with the upstream identity provider.
+
 ## Set up authorization
 
 All authentication approaches can use the same authorization configuration using
@@ -836,7 +883,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 +894,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

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:

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

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>

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