Fix CRD field issues in vMCP and K8s quickstart docs (#720)

- MCPServer.spec.groupRef must be an object {name: ...}, not a string
- Replace inline oidcConfig with oidcConfigRef and MCPOIDCConfig resource
- Move resourceUrl to oidcConfigRef (per-server, not per-provider)
- Update K8s quickstart mcpservers expected output (new READY/REPLICAS
  columns, /mcp URL path)
- Update health endpoint expected response from OK to JSON

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 2 people

docs/toolhive/guides-k8s/quickstart.mdx

@@ -171,8 +171,8 @@ kubectl get mcpservers -n toolhive-system
 You should see:
 
 ```text
-NAME    STATUS   URL                                                             AGE
-fetch   Ready    http://mcp-fetch-proxy.toolhive-system.svc.cluster.local:8080   30s
+NAME    STATUS   READY   REPLICAS   URL                                                                 AGE
+fetch   Ready    True    1          http://mcp-fetch-proxy.toolhive-system.svc.cluster.local:8080/mcp   30s
 ```
 
 If the status is "Pending", wait a few moments and check again. If it remains
@@ -196,10 +196,10 @@ kubectl port-forward service/mcp-fetch-proxy -n toolhive-system 8080:8080
 In another terminal, test the server:
 
 ```bash
-curl http://localhost:8080/health
+curl -s http://localhost:8080/health | jq .status
 ```
 
-You should see a response of `OK`.
+You should see a response of `"healthy"`.
 
 This confirms your MCP server is running and responding correctly.
 

docs/toolhive/guides-vmcp/authentication.mdx

@@ -427,26 +427,22 @@ at `authed_user.access_token`). Add a `tokenResponseMapping` block to the
 ### Incoming auth with the embedded auth server
 
 When using the embedded auth server, configure `incomingAuth` to validate the
-JWTs it issues. The `issuer` must match `authServerConfig.issuer`. Note that
+JWTs it issues. Create an `MCPOIDCConfig` resource whose `issuer` matches
+`authServerConfig.issuer`, then reference it with `oidcConfigRef`. Note that
 `jwksAllowPrivateIP: true` is no longer needed when using the embedded auth
 server because JWKS retrieval is done in-process.
 
 ```yaml title="VirtualMCPServer resource"
 spec:
   incomingAuth:
     type: oidc
-    resourceUrl: https://mcp.example.com/mcp
-    oidcConfig:
-      type: inline
-      inline:
-        issuer: https://auth.example.com
-        audience: https://mcp.example.com/mcp
+    # highlight-start
+    oidcConfigRef:
+      name: my-oidc-config
+      audience: https://mcp.example.com/mcp
+    # highlight-end
 ```
 
-The `resourceUrl` is the externally reachable URL of the MCP endpoint. MCP
-clients use this for [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728)
-protected resource metadata discovery to find the authorization server.
-
 ### Session storage
 
 By default, upstream tokens are stored in memory and lost on pod restart. For
@@ -468,7 +464,7 @@ provider credentials following the steps in
 You need: `auth-signing-key`, `auth-hmac-key`, `github-client-secret`, and
 `google-client-secret`.
 
-**Step 1:** Create an MCPGroup and deploy the backend MCP server:
+**Step 1:** Create an MCPGroup, OIDC config, and deploy the backend MCP server:
 
 ```yaml title="backends.yaml"
 apiVersion: toolhive.stacklok.dev/v1alpha1
@@ -477,6 +473,18 @@ metadata:
   name: my-backends
   namespace: toolhive-system
 ---
+# highlight-start
+apiVersion: toolhive.stacklok.dev/v1alpha1
+kind: MCPOIDCConfig
+metadata:
+  name: my-oidc-config
+  namespace: toolhive-system
+spec:
+  type: inline
+  inline:
+    issuer: https://auth.example.com
+# highlight-end
+---
 apiVersion: toolhive.stacklok.dev/v1alpha1
 kind: MCPServer
 metadata:
@@ -485,7 +493,10 @@ metadata:
 spec:
   image: ghcr.io/github/github-mcp-server
   transport: streamable-http
-  groupRef: my-backends
+  # highlight-start
+  groupRef:
+    name: my-backends
+  # highlight-end
 ```
 
 **Step 2:** Create the upstream token injection config:
@@ -567,12 +578,11 @@ spec:
   # highlight-end
   incomingAuth:
     type: oidc
-    resourceUrl: https://mcp.example.com/mcp
-    oidcConfig:
-      type: inline
-      inline:
-        issuer: https://auth.example.com
-        audience: https://mcp.example.com/mcp
+    # highlight-start
+    oidcConfigRef:
+      name: my-oidc-config
+      audience: https://mcp.example.com/mcp
+    # highlight-end
   outgoingAuth:
     source: inline
     backends:

docs/toolhive/guides-vmcp/quickstart.mdx

@@ -58,7 +58,7 @@ kubectl get mcpgroups -n toolhive-system
 Deploy two MCP servers that will be aggregated. Both reference the `demo-tools`
 group in the `groupRef` field:
 
-```yaml {11,30} title="mcpservers.yaml"
+```yaml title="mcpservers.yaml"
 apiVersion: toolhive.stacklok.dev/v1alpha1
 kind: MCPServer
 metadata:
@@ -69,7 +69,10 @@ spec:
   transport: streamable-http
   proxyPort: 8080
   mcpPort: 8080
-  groupRef: demo-tools
+  # highlight-start
+  groupRef:
+    name: demo-tools
+  # highlight-end
   resources:
     limits:
       cpu: '100m'
@@ -88,7 +91,10 @@ spec:
   transport: streamable-http
   proxyPort: 8080
   mcpPort: 8080
-  groupRef: demo-tools
+  # highlight-start
+  groupRef:
+    name: demo-tools
+  # highlight-end
   resources:
     limits:
       cpu: '100m'

docs/toolhive/guides-vmcp/tool-aggregation.mdx

@@ -236,7 +236,8 @@ spec:
   transport: streamable-http
   proxyPort: 8080
   mcpPort: 8080
-  groupRef: demo-tools
+  groupRef:
+    name: demo-tools
 ---
 # Second backend: osv server
 apiVersion: toolhive.stacklok.dev/v1alpha1
@@ -249,7 +250,8 @@ spec:
   transport: streamable-http
   proxyPort: 8080
   mcpPort: 8080
-  groupRef: demo-tools
+  groupRef:
+    name: demo-tools
 ---
 # VirtualMCPServer aggregating both backends
 apiVersion: toolhive.stacklok.dev/v1alpha1