From f251bf0a54749ded9d4be33af87f6c7f5eb764ca Mon Sep 17 00:00:00 2001
From: Radoslav Dimitrov <radoslav@stacklok.com>
Date: Tue, 14 Apr 2026 00:00:18 +0300
Subject: [PATCH 1/2] Add cross-references to Registry Server from existing
 docs

Add inbound links to the Registry Server documentation from five
existing pages so users discover it at relevant points in their
journey. Adds tip admonitions to the UI and CLI registry guides,
a disambiguation note to registry criteria, a paragraph and bullet
to the custom registry tutorial, and a mention in the K8s operator
introduction.

Closes #366

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 docs/toolhive/concepts/registry-criteria.mdx |  9 +++++++++
 docs/toolhive/guides-cli/registry.mdx        |  9 +++++++++
 docs/toolhive/guides-k8s/index.mdx           |  5 +++++
 docs/toolhive/guides-ui/registry.mdx         |  9 +++++++++
 docs/toolhive/tutorials/custom-registry.mdx  | 10 ++++++++++
 5 files changed, 42 insertions(+)

diff --git a/docs/toolhive/concepts/registry-criteria.mdx b/docs/toolhive/concepts/registry-criteria.mdx
index 2b23066e..9a850cc5 100644
--- a/docs/toolhive/concepts/registry-criteria.mdx
+++ b/docs/toolhive/concepts/registry-criteria.mdx
@@ -9,6 +9,15 @@ The ToolHive registry is a curated list of MCP servers that meet specific
 criteria. We aim to establish a curated, community-auditable list of
 high-quality MCP servers through clear, observable, and objective criteria.
 
+:::note[Built-in registry vs. Registry Server]
+
+This page describes criteria for MCP servers included in the built-in registry
+that ships with the ToolHive CLI and UI. To host your own registry in
+production, see the [ToolHive Registry Server](../guides-registry/index.mdx)
+documentation.
+
+:::
+
 ## Contribute to the registry
 
 If you have an MCP server that you'd like to add to the ToolHive registry, you
diff --git a/docs/toolhive/guides-cli/registry.mdx b/docs/toolhive/guides-cli/registry.mdx
index cdf587ae..282d1b83 100644
--- a/docs/toolhive/guides-cli/registry.mdx
+++ b/docs/toolhive/guides-cli/registry.mdx
@@ -173,6 +173,15 @@ thv config set-registry https://example.com/registry.json
 thv config set-registry https://registry.example.com
 ```
 
+:::tip[Host your own registry]
+
+You can deploy the [ToolHive Registry Server](../guides-registry/index.mdx) to
+host a registry with authentication, multiple data sources, and automatic
+synchronization. Point `thv config set-registry` to your Registry Server
+endpoint.
+
+:::
+
 ### Set a local registry file
 
 To configure ToolHive to use a local registry file, set the file path:
diff --git a/docs/toolhive/guides-k8s/index.mdx b/docs/toolhive/guides-k8s/index.mdx
index 0c9957b6..0e9d1972 100644
--- a/docs/toolhive/guides-k8s/index.mdx
+++ b/docs/toolhive/guides-k8s/index.mdx
@@ -18,6 +18,11 @@ three resource types:
 - **MCPRemoteProxy** — proxy an MCP server hosted outside your cluster
 - **VirtualMCPServer** — aggregate multiple servers behind a single endpoint
 
+The operator also deploys
+[ToolHive Registry Server](../guides-registry/index.mdx) instances via
+MCPRegistry resources, enabling automatic discovery of cluster-hosted MCP
+servers.
+
 ## Where to start
 
 - **New to ToolHive on Kubernetes?** Start with the
diff --git a/docs/toolhive/guides-ui/registry.mdx b/docs/toolhive/guides-ui/registry.mdx
index 1c85e953..f21b0341 100644
--- a/docs/toolhive/guides-ui/registry.mdx
+++ b/docs/toolhive/guides-ui/registry.mdx
@@ -116,6 +116,15 @@ apply your configuration.
 For detailed information on creating a custom registry, see the
 [custom registry tutorial](../tutorials/custom-registry.mdx).
 
+:::tip[Host your own registry]
+
+You can deploy the [ToolHive Registry Server](../guides-registry/index.mdx) to
+host a registry with authentication, multiple data sources, and automatic
+synchronization. Point the **Remote Registry (URL)** setting to your Registry
+Server endpoint.
+
+:::
+
 <ThemedImage
   alt='Registry settings showing Local Registry File Path option selected with Registry File Path input field'
   sources={{
diff --git a/docs/toolhive/tutorials/custom-registry.mdx b/docs/toolhive/tutorials/custom-registry.mdx
index c17dd44f..5e29daf0 100644
--- a/docs/toolhive/tutorials/custom-registry.mdx
+++ b/docs/toolhive/tutorials/custom-registry.mdx
@@ -25,6 +25,12 @@ Creating a custom registry allows you to:
 - Pre-configure server settings for easier deployment
 - Ensure all servers meet your organization's quality and security standards
 
+For production environments, you can also deploy the
+[ToolHive Registry Server](../guides-registry/index.mdx) to host your registry
+with authentication, multiple data sources, and automatic synchronization. This
+tutorial focuses on creating the registry data file itself, which the Registry
+Server can also consume as a file source.
+
 ## Create your first custom registry
 
 In this tutorial, you'll create a custom MCP registry for ToolHive and configure
@@ -304,6 +310,10 @@ you should:
 - **Implement proper access controls** to prevent unauthorized modifications
 - **Set up automated validation** to ensure registry entries follow the schema
 - **Regularly update** the registry with new servers and remove deprecated ones
+- **Deploy the ToolHive Registry Server** for production registries with
+  built-in authentication, multiple data sources, Kubernetes integration, and
+  automatic synchronization (see
+  [Registry Server documentation](../guides-registry/index.mdx))
 
 For production use, configure ToolHive to use a remote registry URL:
 

From ffe7effaae228c10716637cfd4999ef853568356 Mon Sep 17 00:00:00 2001
From: Radoslav Dimitrov <radoslav@stacklok.com>
Date: Tue, 14 Apr 2026 00:04:43 +0300
Subject: [PATCH 2/2] Clarify MCPRegistry is separate from MCP server resource
 types

Reword the Registry Server paragraph in the K8s operator intro to
make it clear that MCPRegistry is a separate capability, not a 4th
MCP server resource type.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 docs/toolhive/guides-k8s/index.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/toolhive/guides-k8s/index.mdx b/docs/toolhive/guides-k8s/index.mdx
index 0e9d1972..dc439d99 100644
--- a/docs/toolhive/guides-k8s/index.mdx
+++ b/docs/toolhive/guides-k8s/index.mdx
@@ -18,7 +18,7 @@ three resource types:
 - **MCPRemoteProxy** — proxy an MCP server hosted outside your cluster
 - **VirtualMCPServer** — aggregate multiple servers behind a single endpoint
 
-The operator also deploys
+Beyond managing MCP servers, the operator can deploy
 [ToolHive Registry Server](../guides-registry/index.mdx) instances via
 MCPRegistry resources, enabling automatic discovery of cluster-hosted MCP
 servers.