Update docs for ToolHive v0.15.0 (#663)

* Update docs for ToolHive v0.15.0 release

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

* Add group_claim_name option to Cedar upstream IDP docs

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

---------

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

Author: ChrisJBurns

docs/toolhive/concepts/cedar-policies.mdx

@@ -236,6 +236,100 @@ permit(principal, action == Action::"call_tool", resource == Tool::"weather");
 
 Then `tools/list` will only show the "weather" tool for that user.
 
+## Optimizer meta-tool enforcement
+
+When the [optimizer](../guides-vmcp/optimizer.mdx) is enabled alongside Cedar
+authorization, Cedar policies cover the optimizer's `find_tool` and `call_tool`
+meta-tools:
+
+- **`tools/list`**: The meta-tools (`find_tool`, `call_tool`) pass through Cedar
+  filtering. Real backend tools are filtered as before.
+- **`tools/call` with `call_tool`**: Cedar extracts the inner `tool_name`
+  argument and authorizes the actual backend tool before execution. Your
+  existing per-tool policies apply transparently.
+- **`tools/call` with `find_tool`**: The response is filtered through Cedar so
+  clients cannot discover unauthorized tools via search.
+
+You don't need to write separate policies for the meta-tools themselves. Your
+existing `call_tool` policies on backend tools are enforced automatically when
+the optimizer routes calls.
+
+:::warning[Review policies when enabling Cedar with the optimizer]
+
+If you enable Cedar on a deployment that already uses the optimizer, ensure your
+backend tool policies are comprehensive. Previously unchecked operations are now
+subject to default-deny authorization. Tools that were accessible without
+policies before may now be denied.
+
+:::
+
+## Upstream identity provider claims
+
+When using the
+[embedded authorization server](./auth-framework.mdx#embedded-authorization-server),
+Cedar policies can reference claims from the upstream identity provider token
+(for example, GitHub `login` or Okta `groups`). This enables group-based
+authorization using your organization's existing identity provider groups.
+
+### Group-based authorization
+
+The Cedar authorizer extracts group membership from upstream tokens using
+configurable claim names. By default, it looks for `groups`, `roles`, and
+`cognito:groups` claims. Groups are mapped to `THVGroup` parent entities, so you
+can write policies like:
+
+```text
+permit(
+  principal in THVGroup::"engineering",
+  action == Action::"call_tool",
+  resource
+);
+```
+
+This permits any user in the "engineering" group to call any tool.
+
+### Custom group claim names
+
+If your identity provider uses a non-standard claim name for groups (for
+example, Auth0 and Okta often use URI-style claims like
+`https://example.com/groups`), set the `group_claim_name` option in your Cedar
+configuration:
+
+```json
+{
+  "version": "1.0",
+  "type": "cedarv1",
+  "cedar": {
+    "policies": [
+      "permit(principal in THVGroup::\"engineering\", action, resource);"
+    ],
+    "entities_json": "[]",
+    "group_claim_name": "https://example.com/groups"
+  }
+}
+```
+
+When `group_claim_name` is set, it takes priority over the well-known defaults.
+When it is empty (the default), ToolHive checks `groups`, `roles`, and
+`cognito:groups` in order.
+
+### How it works
+
+1. The embedded authorization server authenticates the user with your upstream
+   identity provider and issues a ToolHive JWT.
+2. The Cedar authorizer reads claims from the upstream token (not just the
+   ToolHive-issued JWT).
+3. Group claims are extracted and used to build `THVGroup` parent entities for
+   the principal.
+4. Policies using `principal in THVGroup::"<group>"` evaluate correctly.
+
+:::note
+
+If the upstream token is opaque (not a JWT), the authorizer denies the request.
+There is no silent fallback to ToolHive-issued claims only.
+
+:::
+
 ## Policy evaluation and secure defaults
 
 Understanding how Cedar evaluates policies helps you write more effective and

docs/toolhive/guides-k8s/auth-k8s.mdx

@@ -33,7 +33,7 @@ You'll need:
 
 ## Choose your authentication approach
 
-There are four main ways to authenticate with MCP servers running in Kubernetes:
+There are several ways to authenticate with MCP servers running in Kubernetes:
 
 ### Approach 1: External identity provider authentication
 
@@ -44,18 +44,30 @@ providers like Google, GitHub, Microsoft Entra ID, Okta, or Auth0.
 
 <OidcPrerequisites />
 
-### Approach 2: Shared OIDC configuration with ConfigMap
+### Approach 2: Shared OIDC configuration with MCPOIDCConfig
 
 Use this when you want to share the same OIDC configuration across multiple
-MCPServers. This is ideal for managing multiple servers with the same external
-identity provider.
+MCPServers or VirtualMCPServers. The `MCPOIDCConfig` CRD provides a dedicated,
+validated resource for managing shared OIDC settings at the platform level.
 
 **Prerequisites for shared OIDC:**
 
 - External identity provider configured (same as Approach 1)
-- Understanding of Kubernetes ConfigMaps
 
-### Approach 3: Kubernetes service-to-service authentication
+### Approach 3: Shared OIDC configuration with ConfigMap (legacy)
+
+:::warning[Prefer MCPOIDCConfig]
+
+For new deployments, use Approach 2 (`MCPOIDCConfig`) instead of a ConfigMap.
+`MCPOIDCConfig` provides built-in validation, status tracking, and lifecycle
+management.
+
+:::
+
+This approach predates MCPOIDCConfig and remains supported. Use this when you
+want to share OIDC configuration via a ConfigMap.
+
+### Approach 4: Kubernetes service-to-service authentication
 
 Use this when you have client applications running in the same Kubernetes
 cluster that need to call MCP servers. This approach uses Kubernetes service
@@ -66,7 +78,7 @@ account tokens for authentication.
 - Client applications running in Kubernetes pods
 - Understanding of Kubernetes service accounts and RBAC
 
-### Approach 4: Embedded authorization server authentication
+### Approach 5: Embedded authorization server authentication
 
 Use this when you want ToolHive to handle the full OAuth flow, including
 redirecting users to an upstream identity provider for authentication. This
@@ -82,8 +94,131 @@ For conceptual background, see
 - A registered OAuth application/client with your upstream provider
 - Client ID and client secret from your upstream provider
 
+## Set up shared OIDC configuration with MCPOIDCConfig
+
+The `MCPOIDCConfig` CRD lets you define OIDC provider settings once and
+reference them from multiple MCPServer or VirtualMCPServer resources. Each
+server specifies its own `audience` (and optionally `scopes`) to maintain token
+isolation.
+
+**Step 1: Create an MCPOIDCConfig resource**
+
+<Tabs groupId="oidc-type">
+<TabItem value="inline" label="External IdP" default>
+
+```yaml title="shared-oidc-config.yaml"
+apiVersion: toolhive.stacklok.dev/v1alpha1
+kind: MCPOIDCConfig
+metadata:
+  name: production-oidc
+  namespace: toolhive-system
+spec:
+  type: inline
+  inline:
+    issuer: 'https://auth.example.com'
+    clientId: 'your-client-id'
+    clientSecretRef:
+      name: oidc-secret
+      key: client-secret
+    jwksUrl: 'https://auth.example.com/.well-known/jwks.json'
+```
+
+</TabItem>
+<TabItem value="k8s" label="Kubernetes service account">
+
+```yaml title="k8s-oidc-config.yaml"
+apiVersion: toolhive.stacklok.dev/v1alpha1
+kind: MCPOIDCConfig
+metadata:
+  name: k8s-sa-oidc
+  namespace: toolhive-system
+spec:
+  type: kubernetesServiceAccount
+  kubernetesServiceAccount:
+    serviceAccount: mcp-client
+    namespace: client-apps
+```
+
+</TabItem>
+</Tabs>
+
+Apply the resource:
+
+```bash
+kubectl apply -f <YOUR_OIDC_CONFIG_FILE>.yaml
+```
+
+**Step 2: Reference MCPOIDCConfig from an MCPServer**
+
+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
+kind: MCPServer
+metadata:
+  name: weather-server
+  namespace: toolhive-system
+spec:
+  image: ghcr.io/stackloklabs/weather-mcp/server
+  transport: streamable-http
+  proxyPort: 8080
+  permissionProfile:
+    type: builtin
+    name: network
+  # highlight-start
+  oidcConfigRef:
+    name: production-oidc
+    audience: weather-server
+    scopes:
+      - openid
+  # highlight-end
+```
+
+```bash
+kubectl apply -f mcp-server-shared-oidc.yaml
+```
+
+**Step 3: Verify**
+
+Check the MCPOIDCConfig status:
+
+```bash
+kubectl get mcpoidc -n toolhive-system
+```
+
+The `REFERENCES` column shows which workloads use this config. The `READY`
+column confirms validation passed.
+
+### Benefits of MCPOIDCConfig
+
+- **Centralized management**: update provider settings in one place for all
+  servers
+- **Built-in validation**: CEL rules catch misconfiguration at admission time
+- **Status tracking**: see which workloads reference the config and whether it
+  is valid
+- **Lifecycle management**: deletion is blocked while workloads reference the
+  config
+
+:::info[Inline oidcConfig deprecation]
+
+The inline `spec.oidcConfig` field on MCPServer is deprecated and will be
+removed in `v1beta1`. Use `oidcConfigRef` to reference a shared MCPOIDCConfig
+resource instead. You cannot set both fields on the same MCPServer.
+
+:::
+
 ## Set up external identity provider authentication
 
+:::note[Consider MCPOIDCConfig]
+
+For new deployments, consider using `oidcConfigRef` with a shared MCPOIDCConfig
+resource instead of inline `oidcConfig`. See
+[Set up shared OIDC configuration](#set-up-shared-oidc-configuration-with-mcpoidcconfig)
+above.
+
+:::
+
 **Step 1: Create an MCPServer with external OIDC**
 
 Create an `MCPServer` resource configured to accept tokens from your external
@@ -99,7 +234,7 @@ metadata:
 spec:
   image: ghcr.io/stackloklabs/weather-mcp/server
   transport: sse
-  port: 8080
+  proxyPort: 8080
   permissionProfile:
     type: builtin
     name: network
@@ -185,7 +320,7 @@ metadata:
 spec:
   image: ghcr.io/stackloklabs/weather-mcp/server
   transport: sse
-  port: 8080
+  proxyPort: 8080
   permissionProfile:
     type: builtin
     name: network
@@ -249,7 +384,7 @@ metadata:
 spec:
   image: ghcr.io/stackloklabs/weather-mcp/server
   transport: sse
-  port: 8080
+  proxyPort: 8080
   permissionProfile:
     type: builtin
     name: network
@@ -629,7 +764,11 @@ standard `name` field.
 ## Set up authorization
 
 All authentication approaches can use the same authorization configuration using
-Cedar policies.
+Cedar policies. When using the embedded authorization server (Approach 5), Cedar
+policies can also evaluate upstream identity provider claims such as group
+membership. See
+[Upstream identity provider claims](../concepts/cedar-policies.mdx#upstream-identity-provider-claims)
+for details.
 
 **Step 1: Create authorization configuration**
 
@@ -678,7 +817,7 @@ metadata:
 spec:
   image: ghcr.io/stackloklabs/weather-mcp/server
   transport: sse
-  port: 8080
+  proxyPort: 8080
   permissionProfile:
     type: builtin
     name: network

docs/toolhive/guides-k8s/customize-tools.mdx

@@ -16,8 +16,7 @@ descriptions. You reference the configuration from an MCPServer using the
 - toolsOverride: rename tools and/or change their descriptions.
 - Same-namespace only: an MCPServer can reference only MCPToolConfig objects in
   the same namespace.
-- Precedence: toolConfigRef takes precedence over the deprecated spec.tools
-  field on MCPServer.
+- The inline `spec.tools` field has been removed. Use `toolConfigRef` instead.
 
 ## Define a basic tool filter
 

docs/toolhive/guides-k8s/intro.mdx

@@ -25,6 +25,13 @@ which represents an MCP server running outside the cluster that is proxied by
 ToolHive, and `VirtualMCPServer`, which represents a virtual MCP server gateway
 that aggregates multiple backend MCP servers.
 
+All ToolHive CRDs are registered under the `toolhive` category, so you can list
+every ToolHive resource in your cluster with a single command:
+
+```bash
+kubectl get toolhive -n toolhive-system
+```
+
 When you create an `MCPServer` resource, the operator automatically:
 
 1. Creates a Deployment to run the MCP server
@@ -73,6 +80,16 @@ Most teams start with `MCPServer` for container-based servers, add
 `MCPRemoteProxy` for external SaaS tools, and graduate to `VirtualMCPServer`
 when managing five or more servers or needing centralized authentication.
 
+The operator also provides shared configuration CRDs that you reference from
+workload resources:
+
+| Resource                                                                                         | Purpose                                                                                      |
+| ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
+| [**MCPOIDCConfig**](./auth-k8s.mdx#set-up-shared-oidc-configuration-with-mcpoidcconfig)          | Shared OIDC authentication settings, referenced via `oidcConfigRef`                          |
+| [**MCPTelemetryConfig**](./telemetry-and-metrics.mdx#shared-telemetry-configuration-recommended) | Shared telemetry/observability settings, referenced via `telemetryConfigRef`                 |
+| [**MCPToolConfig**](./customize-tools.mdx)                                                       | Tool filtering and renaming, referenced via `toolConfigRef`                                  |
+| [**MCPExternalAuthConfig**](./auth-k8s.mdx#set-up-embedded-authorization-server-authentication)  | Token exchange or embedded auth server configuration, referenced via `externalAuthConfigRef` |
+
 ## Installation
 
 [Deploy the ToolHive operator](./deploy-operator.mdx) in your Kubernetes