diff --git a/docs/toolhive/guides-cli/registry.mdx b/docs/toolhive/guides-cli/registry.mdx
index e2b5d317..ac8617fd 100644
--- a/docs/toolhive/guides-cli/registry.mdx
+++ b/docs/toolhive/guides-cli/registry.mdx
@@ -132,48 +132,70 @@ By default, ToolHive uses a built-in registry of verified MCP servers. You can
 configure ToolHive to use a custom registry instead. This is useful for
 organizations that want to maintain their own private registry of MCP servers.
 
-The registry is a JSON file that follows the
-[ToolHive registry schema](../reference/registry-schema-toolhive.mdx). Once you
-configure a custom registry, ToolHive uses it for all commands that interact
-with the registry, such as `thv registry list`, `thv registry info`, and
-`thv run`.
+ToolHive supports two types of custom registries:
 
-Refer to the
-[built-in registry file](https://github.com/stacklok/toolhive/blob/main/pkg/registry/data/registry.json)
-for examples of MCP server entries.
+- **File-based registries**: JSON files that follow either the
+  [ToolHive registry schema](../reference/registry-schema-toolhive.mdx) or the
+  [upstream registry schema](../reference/registry-schema-upstream.mdx)
+- **API-based registries**: REST API endpoints that implement the
+  [MCP Registry API specification](../guides-registry/index.mdx), which use the
+  [upstream registry schema](../reference/registry-schema-upstream.mdx)
 
-### Set a remote registry URL
+Once you configure a custom registry, ToolHive uses it for all commands that
+interact with the registry, such as `thv registry list`, `thv registry info`,
+and `thv run`.
 
-To configure ToolHive to use a remote registry, set the registry URL:
+### Set a remote registry
+
+To configure ToolHive to use a remote registry, set the registry URL or API
+endpoint:
 
 ```bash
 thv config set-registry <URL>
 ```
 
-For example:
+The CLI automatically detects the registry type:
+
+- URLs ending with `.json` are treated as static registry files
+- Other URLs are probed to detect MCP Registry API endpoints, falling back to
+  static files if the probe fails
+- Local paths are treated as local registry files
+
+Examples:
 
 ```bash
+# Static registry file
 thv config set-registry https://example.com/registry.json
+
+# API endpoint
+thv config set-registry https://registry.example.com
 ```
 
 ### Set a local registry file
 
-To configure ToolHive to use a local registry, set the registry file:
+To configure ToolHive to use a local registry file, set the file path:
 
 ```bash
 thv config set-registry <PATH>
 ```
 
-### Check the current registry location
+For example:
+
+```bash
+thv config set-registry /path/to/local-registry.json
+```
+
+### Check the current registry
 
-To see which registry (URL or path) is currently configured:
+To see which registry is currently configured:
 
 ```bash
 thv config get-registry
 ```
 
-If no custom registry is configured, this command indicates that the built-in
-registry is being used.
+This displays the configured registry URL, API endpoint, or file path. If no
+custom registry is configured, this command indicates that the built-in registry
+is being used.
 
 ### Revert to the built-in registry