stacklok · danbarr · Mar 27, 2026 · Mar 19, 2026 · Mar 19, 2026 · Mar 19, 2026
diff --git a/docs/toolhive/concepts/auth-framework.mdx b/docs/toolhive/concepts/auth-framework.mdx
@@ -346,3 +346,5 @@ standardized across clients.
   [Backend authentication](./backend-auth.mdx)
 - For detailed policy writing guidance, see
   [Cedar policies](./cedar-policies.mdx)
+- For a complete end-to-end example with Okta OIDC and role-based access
+  control, see [Role-based authorization with Okta](../integrations/okta.mdx)
diff --git a/docs/toolhive/concepts/cedar-policies.mdx b/docs/toolhive/concepts/cedar-policies.mdx
@@ -407,3 +407,5 @@ When policies don't work as expected, follow this systematic approach:
   [Authentication and authorization framework](./auth-framework.mdx)
 - For detailed Cedar policy syntax, see
   [Cedar documentation](https://docs.cedarpolicy.com/)
+- For a practical example of Cedar policies enforcing role-based access control,
+  see [Role-based authorization with Okta](../integrations/okta.mdx)
diff --git a/docs/toolhive/guides-cli/api-server.mdx b/docs/toolhive/guides-cli/api-server.mdx
@@ -13,7 +13,7 @@ The API server isn't intended for production use. It's designed for local
 automation and UI development, and doesn't implement any authentication or
 authorization mechanisms.
 
-For production use cases, consider using the ToolHive Kubernetes operator, which
+For production use cases, consider using the ToolHive Kubernetes Operator, which
 provides a more robust and secure way to manage ToolHive instances in a
 multi-user environment.
 

diff --git a/docs/toolhive/guides-cli/index.mdx b/docs/toolhive/guides-cli/index.mdx
@@ -26,6 +26,16 @@ both installed.
 
 :::
 
+## Where to start
+
+- **New to ToolHive CLI?** Follow the [Quickstart](./quickstart.mdx) to install
+  `thv` and run your first MCP server in minutes.
+- **Already installed?** Jump to [Run MCP servers](./run-mcp-servers.mdx) to
+  start managing servers from the command line.
+- **Building or automating?** See advanced workflows for [auth](./auth.mdx),
+  [CI/CD](./advanced-cicd.mdx), [container builds](./build-containers.mdx), and
+  more.
+
 ## Contents
 
 <DocCardList />
diff --git a/docs/toolhive/guides-k8s/auth-k8s.mdx b/docs/toolhive/guides-k8s/auth-k8s.mdx
@@ -771,6 +771,8 @@ kubectl logs -n toolhive-system -l app.kubernetes.io/name=weather-server-k8s
 - For detailed Cedar policy syntax, see
   [Cedar policies](../concepts/cedar-policies.mdx) and the
   [Cedar documentation](https://docs.cedarpolicy.com/)
+- For a complete end-to-end example with Okta OIDC and role-based access
+  control, see [Role-based authorization with Okta](../integrations/okta.mdx)
 - For running MCP servers without authentication, see
   [Run MCP servers in Kubernetes](./run-mcp-k8s.mdx)
 - For ToolHive Operator installation, see

diff --git a/docs/toolhive/guides-k8s/index.mdx b/docs/toolhive/guides-k8s/index.mdx
@@ -1,19 +1,34 @@
 ---
 title: Using the ToolHive Kubernetes Operator
 description:
-  How-to guides for using the ToolHive Kubernetes operator to run and manage MCP
+  How-to guides for using the ToolHive Kubernetes Operator to run and manage MCP
   servers.
 ---
 
 import DocCardList from '@theme/DocCardList';
 
 ## Introduction
 
-The ToolHive Kubernetes operator manages MCP servers in Kubernetes clusters. It
-provides a way to deploy, manage, and scale MCP servers in multi-user
-environments. By defining MCP servers as Kubernetes resources, the operator
-automates their deployment and management, making it easier to run MCP servers
-in multi-user environments.
+The ToolHive Kubernetes Operator manages MCP servers in Kubernetes clusters. You
+define MCP servers as Kubernetes custom resources and the operator automates
+their deployment, proxying, and lifecycle management. The operator supports
+three resource types:
+
+- **MCPServer** — run a containerized MCP server inside your cluster
+- **MCPRemoteProxy** — proxy an MCP server hosted outside your cluster
+- **VirtualMCPServer** — aggregate multiple servers behind a single endpoint
+
+## Where to start
+
+- **New to ToolHive on Kubernetes?** Start with the
+  [Quickstart](./quickstart.mdx) to deploy your first MCP server on a local kind
+  cluster.
+- **Operator already installed?** Jump to [Run MCP servers](./run-mcp-k8s.mdx),
+  [Proxy remote MCP servers](./remote-mcp-proxy.mdx), or set up a
+  [Virtual MCP Server](../guides-vmcp/index.mdx).
+- **Not sure which resource type to use?** See the
+  [decision guide](./intro.mdx#which-resource-type-should-i-use) in the
+  Introduction.
 
 ## Contents
 

diff --git a/docs/toolhive/guides-k8s/intro.mdx b/docs/toolhive/guides-k8s/intro.mdx
@@ -1,21 +1,22 @@
 ---
-title: Overview
-description: How to manage MCP servers in Kubernetes with the ToolHive operator
+title: Introduction
+description:
+  How to manage MCP servers in Kubernetes with the ToolHive Kubernetes Operator
 ---
 
-The ToolHive Kubernetes operator manages MCP servers in Kubernetes clusters. It
+The ToolHive Kubernetes Operator manages MCP servers in Kubernetes clusters. It
 lets you define MCP servers as Kubernetes resources and automates their
 deployment and management.
 
 :::info
 
 See the [ToolHive Operator quickstart tutorial](./quickstart.mdx) to get started
-quickly using a local kind cluster. We'd love for you to try it out and send
-feedback!
+quickly using a local kind cluster. Try it out and
+[share your feedback](https://discord.gg/stacklok)!
 
 :::
 
-## Overview
+## How the operator works
 
 The operator introduces new Custom Resource Definitions (CRDs) into your
 Kubernetes cluster. The primary CRDs for MCP server workloads are `MCPServer`,
@@ -57,6 +58,21 @@ The diagram shows how clients connect to MCP servers through a standard Ingress
 or Gateway. To learn how to expose your MCP servers and connect clients, see
 [Connect clients to MCP servers](./connect-clients.mdx).
 
+## Which resource type should I use?
+
+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 |
+
+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.
+
 ## Installation
 
 [Deploy the ToolHive operator](./deploy-operator.mdx) in your Kubernetes

diff --git a/docs/toolhive/guides-k8s/quickstart.mdx b/docs/toolhive/guides-k8s/quickstart.mdx
@@ -2,14 +2,14 @@
 title: 'Quickstart: ToolHive Kubernetes Operator'
 sidebar_label: Quickstart
 description:
-  Learn how to deploy the ToolHive Kubernetes operator and use it to manage MCP
+  Learn how to deploy the ToolHive Kubernetes Operator and use it to manage MCP
   servers in a Kubernetes cluster.
 ---
 
 import useBaseUrl from '@docusaurus/useBaseUrl';
 import ThemedImage from '@theme/ThemedImage';
 
-In this tutorial, you'll learn how to deploy the ToolHive Kubernetes operator
+In this tutorial, you'll learn how to deploy the ToolHive Kubernetes Operator
 and use it to manage MCP servers in a Kubernetes cluster. By the end, you'll
 have a working operator deployment that automatically manages MCP servers using
 Kubernetes resources.

diff --git a/docs/toolhive/guides-mcp/notion-remote.mdx b/docs/toolhive/guides-mcp/notion-remote.mdx
@@ -84,7 +84,7 @@ thv restart notion-remote
 
 :::note
 
-The ToolHive Kubernetes operator does not currently support remote MCP servers
+The ToolHive Kubernetes Operator does not currently support remote MCP servers
 using dynamic OAuth authentication. Instead, you can run the
 [local Notion MCP server](https://github.com/makenotion/notion-mcp-server) in
 Kubernetes using a static integration key.

diff --git a/docs/toolhive/guides-registry/index.mdx b/docs/toolhive/guides-registry/index.mdx
@@ -15,6 +15,24 @@ It provides a standardized REST API for discovering and accessing MCP servers
 from multiple backend sources, including Kubernetes clusters, Git repositories,
 API endpoints, and local files.
 
+:::note
+
+This section covers the **Registry Server**, a standalone service you deploy
+yourself. Looking for the built-in registry instead? See
+[Explore the registry](../guides-cli/registry.mdx) (CLI) or
+[Explore the registry](../guides-ui/registry.mdx) (UI).
+
+:::
+
+## Where to start
+
+- **Evaluating the Registry Server?** Read the [Introduction](./intro.mdx) for
+  architecture, features, and supported registry source types.
+- **Ready to deploy?** See [Deployment overview](./deployment.mdx) to choose
+  between Kubernetes Operator and manual deployment methods.
+- **Already running?** Jump to [Configuration](./configuration.mdx) or
+  [Authentication](./authentication.mdx).
+
 ## Contents
 
 <DocCardList />
diff --git a/docs/toolhive/guides-registry/intro.mdx b/docs/toolhive/guides-registry/intro.mdx
@@ -1,16 +1,27 @@
 ---
-title: Overview
-sidebar_label: Introduction
+title: Introduction
 description:
-  How to use the ToolHive Registry server to discover and access MCP servers and
+  How to use the ToolHive Registry Server to discover and access MCP servers and
   skills
 ---
 
-The ToolHive Registry server is a standards-compliant implementation of the MCP
+The ToolHive Registry Server is a standards-compliant implementation of the MCP
 Registry API specification. It provides a REST API for discovering and accessing
 MCP servers from multiple backend sources.
 
-## Overview
+:::note[Registry Server vs. built-in registry]
+
+This section covers the **Registry Server** — a standalone service you deploy
+yourself for hosting and curating your own MCP server catalog.
+
+ToolHive also ships with a **built-in registry** for browsing and discovering
+MCP servers from the default catalog. That's a different feature: see
+[Explore the registry](../guides-cli/registry.mdx) (CLI) or
+[Explore the registry](../guides-ui/registry.mdx) (UI).
+
+:::
+
+## How the Registry Server works
 
 The Registry server aggregates MCP server metadata from various sources and
 exposes it through a standardized API. When you start the server, it:

diff --git a/docs/toolhive/guides-ui/index.mdx b/docs/toolhive/guides-ui/index.mdx
@@ -42,6 +42,17 @@ details.
 
 :::
 
+## Where to start
+
+- **New to ToolHive?** Follow the [Quickstart](./quickstart.mdx) to install the
+  app and run your first MCP server in minutes.
+- **Already installed?** Jump straight to
+  [Run MCP servers](./run-mcp-servers.mdx) to discover and launch servers from
+  the registry.
+- **Want to connect your AI client?** See
+  [Client configuration](./client-configuration.mdx) to point Claude, Cursor, or
+  another client at your running servers.
+
 ## Contents
 
 <DocCardList />
diff --git a/docs/toolhive/guides-vmcp/index.mdx b/docs/toolhive/guides-vmcp/index.mdx
@@ -3,24 +3,25 @@ title: Virtual MCP Server
 description: Aggregate multiple MCP servers into a single unified endpoint.
 ---
 
-Virtual MCP Server (vMCP) is a feature of the ToolHive Kubernetes Operator that
-aggregates multiple backend MCP servers into a single endpoint, enabling unified
-tool access, centralized authentication, and multi-step workflows.
+import DocCardList from '@theme/DocCardList';
 
-## When to use vMCP
+## Introduction
 
-- You manage multiple MCP servers that should appear as one
-- You need to centralize authentication across backends
-- You want to create reusable workflows spanning multiple systems
+Virtual MCP Server (vMCP) is ToolHive's MCP gateway. It aggregates multiple
+backend MCP servers into a single endpoint, giving clients unified tool access,
+centralized authentication, and multi-step workflows — all through one
+connection.
 
-## Get started
+## Where to start
 
-- [Understanding Virtual MCP Server](../concepts/vmcp.mdx) - Learn what vMCP
-  does and when to use it
-- [Quickstart: Virtual MCP Server](./quickstart.mdx) - Deploy your first vMCP
+- **Evaluating vMCP?** Read
+  [Understanding Virtual MCP Server](../concepts/vmcp.mdx) for the full picture
+  of what it does and when it's the right fit.
+- **Ready to try it?** Follow the [Quickstart](./quickstart.mdx) to deploy your
+  first vMCP on a Kubernetes cluster.
+- **Already running vMCP?** Jump to [Configuration](./configuration.mdx) or
+  [Authentication](./authentication.mdx).
 
 ## Contents
 
-import DocCardList from '@theme/DocCardList';
-
 <DocCardList />
diff --git a/docs/toolhive/guides-vmcp/intro.mdx b/docs/toolhive/guides-vmcp/intro.mdx
@@ -3,7 +3,7 @@ title: Introduction to vMCP
 description: Understand what Virtual MCP Server (vMCP) does and when to use it.
 ---
 
-## Overview
+## What is vMCP?
 
 Virtual MCP Server (vMCP) is a feature of the ToolHive Kubernetes Operator that
 acts as an aggregation proxy, consolidating multiple backend MCP servers into a
@@ -109,5 +109,5 @@ guide.
 - [Quickstart: Virtual MCP Server](./quickstart.mdx)
 - [Understanding Virtual MCP Server](../concepts/vmcp.mdx)
 - [Optimize tool discovery](./optimizer.mdx)
-- [Scaling and Performance](./scaling-and-performance.mdx)
+- [Scaling and performance](./scaling-and-performance.mdx)
 - [Proxy remote MCP servers](../guides-k8s/remote-mcp-proxy.mdx)
diff --git a/docs/toolhive/integrations/opentelemetry.mdx b/docs/toolhive/integrations/opentelemetry.mdx
@@ -52,7 +52,7 @@ running in Docker containers. This approach is perfect for:
 
 **ToolHive Kubernetes Operator + in-cluster observability**
 
-Use the ToolHive Kubernetes operator to manage MCP servers in a cluster, with
+Use the ToolHive Kubernetes Operator to manage MCP servers in a cluster, with
 Jaeger and Prometheus deployed inside Kubernetes. This approach is ideal for:
 
 - Production-like environments