Update docs for ToolHive v0.17.0

Breaking changes:
- Update CRD phase values from Running to Ready for MCPServer,
  EmbeddingServer, and MCPRegistry across quickstarts, guides,
  and integration pages
- Migrate MCPRegistry examples from v1 flat registries[] format
  to v2 sources[]/registries[] with configYAML recommended path
- Remove PVC source type (no longer supported)
- Remove Syncing phase from MCPRegistry status documentation
- Remove auto-injection note for Kubernetes discovery sources

New features:
- Add MCPServerEntry (zero-infrastructure catalog entries) docs
  to K8s intro and vMCP configuration pages
- Add caBundleRef for OTLP endpoints to telemetry guide
- Add authServerRef for separating embedded auth from external
  token exchange to auth guide
- Update standalone registry server config to v2 format

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

Author: ChrisJBurns

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

@@ -652,6 +652,36 @@ spec:
 kubectl apply -f mcp-server-embedded-auth.yaml
 ```
 
+:::tip[Combining embedded auth with outgoing token exchange]
+
+If you need both an embedded auth server for incoming client authentication
+**and** an outgoing token exchange (such as AWS STS) on the same MCPServer, use
+the dedicated `authServerRef` field instead of `externalAuthConfigRef` for the
+embedded auth server. This separates the two configurations so they don't
+compete for the same field:
+
+```yaml
+spec:
+  # Dedicated field for the embedded auth server
+  authServerRef:
+    kind: MCPExternalAuthConfig
+    name: embedded-auth-server
+  # Outgoing token exchange (e.g., AWS STS)
+  externalAuthConfigRef:
+    name: aws-sts-config
+    kind: MCPExternalAuthConfig
+  oidcConfig:
+    type: inline
+    inline:
+      issuer: 'https://mcp.example.com'
+```
+
+Both `authServerRef` and `externalAuthConfigRef` cannot point to an
+`embeddedAuthServer` type simultaneously. The same `authServerRef` field is
+available on MCPRemoteProxy resources.
+
+:::
+
 :::note
 
 The `oidcConfig` issuer must match the `issuer` in your `MCPExternalAuthConfig`.

docs/toolhive/guides-k8s/intro.mdx

@@ -70,25 +70,28 @@ or Gateway. To learn how to expose your MCP servers and connect clients, see
 The operator introduces three resource types for MCP workloads. Choose based on
 where your MCP server runs and how many servers you need to manage:
 
-| Resource             | Use when                                                                                                          |
-| -------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| **MCPServer**        | Running an MCP server as a container inside your cluster                                                          |
-| **MCPRemoteProxy**   | Connecting to an MCP server hosted outside your cluster (SaaS tools, external APIs, remote endpoints)             |
-| **VirtualMCPServer** | Aggregating multiple MCPServer and/or MCPRemoteProxy resources behind a single endpoint for a team or application |
+| Resource             | Use when                                                                                                 |
+| -------------------- | -------------------------------------------------------------------------------------------------------- |
+| **MCPServer**        | Running an MCP server as a container inside your cluster                                                 |
+| **MCPRemoteProxy**   | Connecting to an MCP server hosted outside your cluster (SaaS tools, external APIs, remote endpoints)    |
+| **MCPServerEntry**   | Declaring a remote MCP server as a lightweight catalog entry without deploying proxy pods                |
+| **VirtualMCPServer** | Aggregating multiple MCPServer, MCPRemoteProxy, and/or MCPServerEntry resources behind a single endpoint |
 
 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.
+when managing five or more servers or needing centralized authentication. Use
+`MCPServerEntry` instead of `MCPRemoteProxy` when you want to include a remote
+server in vMCP discovery without the overhead of running a proxy pod.
 
 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` |
+| 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` or `authServerRef` |
 
 ## Installation
 

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   Running   http://mcp-fetch-proxy.toolhive-system.svc.cluster.local:8080   30s
+NAME    STATUS   URL                                                             AGE
+fetch   Ready    http://mcp-fetch-proxy.toolhive-system.svc.cluster.local:8080   30s
 ```
 
 If the status is "Pending", wait a few moments and check again. If it remains

docs/toolhive/guides-k8s/telemetry-and-metrics.mdx

@@ -146,6 +146,40 @@ spec:
       enabled: true
 ```
 
+#### Custom CA certificates for OTLP endpoints
+
+If your OTLP collector uses TLS with certificates signed by an internal or
+private CA, add a `caBundleRef` to your MCPTelemetryConfig. The operator mounts
+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
+kind: MCPTelemetryConfig
+metadata:
+  name: shared-otel
+  namespace: toolhive-system
+spec:
+  openTelemetry:
+    enabled: true
+    endpoint: otel-collector.internal:4318
+    caBundleRef:
+      configMapRef:
+        name: otel-ca-bundle
+        key: ca.crt
+    tracing:
+      enabled: true
+    metrics:
+      enabled: true
+```
+
+:::note
+
+`caBundleRef` cannot be used when `insecure` is set to `true` — they are
+mutually exclusive.
+
+:::
+
 ### Inline telemetry configuration
 
 :::warning[Deprecated]

docs/toolhive/guides-registry/configuration.mdx

@@ -9,12 +9,13 @@ pointing to a YAML configuration file.
 
 ## Configuration file structure
 
-```yaml title="config.yaml"
-# Registry name/identifier (optional, defaults to "default")
-registryName: my-registry
+The configuration file uses a v2 format that separates **data sources** (where
+registry data comes from) from **registry views** (logical registries that
+aggregate one or more sources).
 
-# Registries configuration (required, can have multiple registries)
-registries:
+```yaml title="config.yaml"
+# Data sources (required, at least one)
+sources:
   - name: toolhive
     # Data format: upstream or toolhive (see below)
     format: upstream
@@ -25,12 +26,12 @@ registries:
       branch: main
       path: pkg/catalog/toolhive/data/registry-upstream.json
 
-    # Per-registry automatic sync policy (required for synced registries)
+    # Per-source automatic sync policy (required for synced sources)
     syncPolicy:
       # Sync interval (e.g., "30m", "1h", "24h")
       interval: '30m'
 
-    # Optional: Per-registry server filtering
+    # Optional: Per-source server filtering
     filter:
       names:
         include: ['official/*']
@@ -39,6 +40,12 @@ registries:
         include: ['production']
         exclude: ['experimental']
 
+# Registry views (required, at least one)
+# Each view references sources by name
+registries:
+  - name: default
+    sources: ['toolhive']
+
 # Authentication configuration (required)
 # See authentication.mdx for detailed configuration options
 auth:
@@ -80,10 +87,11 @@ The `format` field specifies the JSON schema format for the registry data:
   [ToolHive-native format](../reference/registry-schema-toolhive.mdx), used by
   the built-in ToolHive registry.
 
-## Registries
+## Sources
 
-The server supports five registry types, each with its own configuration
-options. You can configure multiple registries in a single server instance.
+The server supports multiple source types, each with its own configuration
+options. You can configure multiple sources in a single server instance and
+aggregate them into registry views.
 
 ### Git repository source
 
@@ -99,7 +107,7 @@ on every container restart, adding startup latency and increasing network usage.
 :::
 
 ```yaml title="config-git.yaml"
-registries:
+sources:
   - name: toolhive
     format: toolhive
     git:
@@ -108,6 +116,9 @@ registries:
       path: pkg/catalog/toolhive/data/registry-legacy.json
     syncPolicy:
       interval: '30m'
+registries:
+  - name: default
+    sources: ['toolhive']
 ```
 
 **Configuration options:**
@@ -134,7 +145,7 @@ To access private Git repositories, configure the `auth` section with your
 credentials:
 
 ```yaml title="config-git-private.yaml"
-registries:
+sources:
   - name: private-registry
     format: toolhive
     git:
@@ -148,6 +159,9 @@ registries:
       # highlight-end
     syncPolicy:
       interval: '30m'
+registries:
+  - name: default
+    sources: ['private-registry']
 ```
 
 **Authentication options:**
@@ -214,13 +228,16 @@ Sync from upstream MCP Registry APIs. Supports federation and aggregation
 scenarios.
 
 ```yaml title="config-api.yaml"
-registries:
+sources:
   - name: mcp-upstream
     format: upstream
     api:
       endpoint: https://registry.modelcontextprotocol.io
     syncPolicy:
       interval: '1h'
+registries:
+  - name: default
+    sources: ['mcp-upstream']
 ```
 
 **Configuration options:**
@@ -241,26 +258,32 @@ etc.) to the endpoint URL.
 Read from filesystem. Ideal for local development and testing.
 
 ```yaml title="config-file.yaml"
-registries:
+sources:
   - name: local
     format: upstream
     file:
       path: /data/registry.json
     syncPolicy:
       interval: '15m'
+registries:
+  - name: default
+    sources: ['local']
 ```
 
 Alternatively, the source can be a custom URL.
 
-```yaml title="config-file.yaml"
-registries:
+```yaml title="config-url.yaml"
+sources:
   - name: remote
     format: upstream
     file:
       url: https://www.example.com/registry.json
       timeout: 5s
     syncPolicy:
       interval: '15m'
+registries:
+  - name: default
+    sources: ['remote']
 ```
 
 The fields `file` and `url` are mutually exclusive.
@@ -280,10 +303,13 @@ API-managed registry for directly publishing and deleting MCP servers via the
 API. Does not sync from external sources.
 
 ```yaml title="config-managed.yaml"
-registries:
+sources:
   - name: internal
     format: upstream
     managed: {}
+registries:
+  - name: default
+    sources: ['internal']
 ```
 
 **Configuration options:**
@@ -307,15 +333,11 @@ endpoint documentation and request/response examples.
 Discovers MCP servers from running Kubernetes deployments. Automatically creates
 registry entries for deployed MCP servers in your cluster.
 
-:::note[Operator-managed registry]
-
-When using the ToolHive operator, a single Kubernetes registry named `default`
-is automatically created and managed. You cannot configure additional Kubernetes
-registries through the `MCPRegistry` CR or configuration file, as only one
-Kubernetes registry instance is supported per Registry Server instance.
+:::note[Operator deployments]
 
-The configuration example below is for reference when running the Registry
-Server standalone (without the operator).
+When using the ToolHive operator with the `configYAML` path, you must explicitly
+declare Kubernetes discovery sources in your configuration. Only one Kubernetes
+source is supported per Registry Server instance.
 
 :::
 
@@ -326,10 +348,13 @@ By default, the Registry server discovers resources in all namespaces
 details and RBAC requirements.
 
 ```yaml title="config-kubernetes.yaml"
+sources:
+  - name: k8s
+    format: upstream
+    kubernetes: {}
 registries:
   - name: default
-    format: toolhive
-    kubernetes: {}
+    sources: ['k8s']
 ```
 
 **Configuration options:**
@@ -431,12 +456,12 @@ resources via a Service Account, check the details in the
 
 ## Sync policy
 
-Configure automatic synchronization of registry data on a per-registry basis.
-Only applicable to synced registries (Git, API, File). Not required for managed
-or Kubernetes registries.
+Configure automatic synchronization of registry data on a per-source basis. Only
+applicable to synced sources (Git, API, File). Not required for managed or
+Kubernetes sources.
 
 ```yaml
-registries:
+sources:
   - name: toolhive
     git:
       repository: https://github.com/stacklok/toolhive-catalog.git
@@ -448,22 +473,22 @@ registries:
 ```
 
 The `interval` field specifies how often the server should fetch updates from
-the registry. Use Go duration format (e.g., `"30m"`, `"1h"`, `"24h"`).
+the source. Use Go duration format (e.g., `"30m"`, `"1h"`, `"24h"`).
 
 :::note
 
-Sync policy is per-registry and must be specified within each registry
-configuration. Managed and Kubernetes registries do not require sync policies.
+Sync policy is per-source and must be specified within each source
+configuration. Managed and Kubernetes sources do not require sync policies.
 
 :::
 
 ## Server filtering
 
-Optionally filter which servers are exposed through the API on a per-registry
-basis. Only applicable to synced registries (Git, API, File).
+Optionally filter which servers are exposed through the API on a per-source
+basis. Only applicable to synced sources (Git, API, File).
 
 ```yaml
-registries:
+sources:
   - name: toolhive
     git:
       repository: https://github.com/stacklok/toolhive-catalog.git
@@ -489,7 +514,7 @@ registries:
 
 :::note
 
-Filters are per-registry and specified within each registry configuration.
+Filters are per-source and specified within each source configuration.
 
 :::