Update stacklok/toolhive to v0.23.1 (#759)

* Update stacklok/toolhive to v0.23.1

Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

* Refresh reference assets for toolhive v0.23.1

* Add upstream-release-docs content for v0.23.1

Source-verified against stacklok/toolhive@v0.23.1.

- Bump apiVersion from v1alpha1 to v1beta1 across 40 guide,
  integration, and tutorial MDX files. migrate-to-v1beta1.mdx
  is excluded so historical "before" examples stay accurate.
- Add v0.23.0 section to migrate-to-v1beta1.mdx covering the
  CRD API graduation, zero-downtime upgrade behavior, and
  manifest migration steps.
- Add "Default callback URL for upstream providers" subsection
  to auth-k8s.mdx documenting the {resourceUrl}/oauth/callback
  default applied when redirectUri is omitted.

* Docs-review fixes on v0.23.1 release docs

- migrate-to-v1beta1.mdx: replace the kubectl --raw API
  discovery command with a jq query over CRD
  status.storedVersions, which actually identifies CRDs
  still holding v1alpha1-stored resources (the previous
  command only listed kinds served at v1alpha1, always
  all of them).
- auth-k8s.mdx: smooth out the awkward leading-ellipsis
  sentence in the "Default callback URL for upstream
  providers" section by merging it into the preceding
  sentence and dropping the parenthetical em-dash-like
  aside in favor of a natural "for example" clause.

Co-authored-by: Radoslav Dimitrov <undefined@users.noreply.github.com>

* Apply prettier and eslint fixups to skill output

---------

Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Radoslav Dimitrov <undefined@users.noreply.github.com>

Author: 3 people

.github/upstream-projects.yaml

@@ -35,7 +35,7 @@ projects:
 
   - id: toolhive
     repo: stacklok/toolhive
-    version: v0.22.0
+    version: v0.23.1
     docs_paths:
       - docs/toolhive/guides-cli
       - docs/toolhive/guides-k8s

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,51 @@ 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
+
+When you omit `redirectUri` from an upstream provider's `oidcConfig` or
+`oauth2Config`, the operator defaults it to `{resourceUrl}/oauth/callback`.
+`resourceUrl` is the `oidcConfigRef.resourceUrl` set on the MCPServer or
+VirtualMCPServer that references this MCPExternalAuthConfig. It's typically the
+external URL that MCP clients use to reach the server.
+
+You still need to register this callback URL with your upstream OAuth2 or OIDC
+provider before the flow can complete. Use the same URL on both sides: the value
+computed from `resourceUrl` here, and the authorized redirect URI in your
+provider's application settings.
+
+For example, given this `oidcConfigRef` on an MCPServer:
+
+```yaml
+spec:
+  oidcConfigRef:
+    name: embedded-auth-oidc
+    audience: 'https://mcp.example.com/mcp'
+    resourceUrl: 'https://mcp.example.com/mcp'
+```
+
+Omitting `redirectUri` on the upstream provider resolves the callback to
+`https://mcp.example.com/mcp/oauth/callback`:
+
+```yaml
+upstreamProviders:
+  - name: google
+    type: oidc
+    oidcConfig:
+      issuerUrl: 'https://accounts.google.com'
+      clientId: '<YOUR_GOOGLE_CLIENT_ID>'
+      clientSecretRef:
+        name: upstream-idp-secret
+        key: client-secret
+      # redirectUri omitted - defaults to:
+      # https://mcp.example.com/mcp/oauth/callback
+```
+
+Set `redirectUri` explicitly if you need a non-default callback path, for
+example to route the callback through a separate gateway hostname. If
+`resourceUrl` is also unset, no default is applied and the upstream provider
+must have `redirectUri` set explicitly.
+
 ## Set up authorization
 
 All authentication approaches can use the same authorization configuration using
@@ -836,7 +881,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 +892,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>