stacklok · peppescg · May 17, 2026
diff --git a/docs/toolhive/guides-cloud-ui/configuration.mdx b/docs/toolhive/guides-cloud-ui/configuration.mdx
@@ -0,0 +1,140 @@
+---
+title: Cloud UI configuration
+sidebar_label: Configuration
+description:
+  Configure environment variables, OIDC authentication, and deployment options
+  for the Cloud UI
+---
+
+This guide covers the environment variables and configuration options for
+running the Cloud UI in different environments.
+
+## Environment variables
+
+The Cloud UI is configured entirely through environment variables. The table
+below lists the required and optional variables.
+
+### Required variables
+
+| Variable             | Description                                                                             |
+| -------------------- | --------------------------------------------------------------------------------------- |
+| `OIDC_ISSUER_URL`    | Issuer URL of your OIDC provider (for example, `https://your-org.okta.com`)             |
+| `OIDC_CLIENT_ID`     | OAuth2 client ID registered with your OIDC provider                                     |
+| `OIDC_CLIENT_SECRET` | OAuth2 client secret for the registered client                                          |
+| `BETTER_AUTH_SECRET` | Secret used to encrypt session tokens. Generate one with `openssl rand -base64 32`      |
+| `BETTER_AUTH_URL`    | Base URL where the Cloud UI is accessible (for example, `https://cloud-ui.example.com`) |
+| `API_BASE_URL`       | URL of the Registry Server API (for example, `https://registry.example.com`)            |
+
+### Optional variables
+
+| Variable          | Description                                                                                                      |
+| ----------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `DATABASE_URL`    | PostgreSQL connection string for the auth database. When omitted, the Cloud UI uses an in-memory SQLite database |
+| `TRUSTED_ORIGINS` | Comma-separated list of allowed CORS origins                                                                     |
+
+## Configure OIDC authentication
+
+The Cloud UI delegates authentication to an external OIDC provider using
+[Better Auth](https://www.better-auth.com/). It works with any
+standards-compliant provider, including Okta, Microsoft Entra ID, and Auth0.
+
+To configure your provider:
+
+1. Register a new OAuth2/OIDC application in your identity provider.
+2. Set the redirect URI to `<BETTER_AUTH_URL>/api/auth/callback/oidc` (for
+   example, `https://cloud-ui.example.com/api/auth/callback/oidc`).
+3. Copy the issuer URL, client ID, and client secret into the corresponding
+   environment variables.
+
+:::tip
+
+For local development or testing, use the built-in mock OIDC provider by
+starting the Docker Compose stack with the `mock` profile. See the
+[quickstart](./quickstart.mdx) for details.
+
+:::
+
+## Deployment options
+
+### Docker
+
+Build and run the Cloud UI as a standalone container:
+
+```bash title="Build the image"
+docker build -t toolhive-cloud-ui:latest .
+```
+
+```bash title="Run the container"
+docker run -p 3000:3000 \
+  -e OIDC_ISSUER_URL=https://your-org.okta.com \
+  -e OIDC_CLIENT_ID=your-client-id \
+  -e OIDC_CLIENT_SECRET=your-client-secret \
+  -e BETTER_AUTH_SECRET=$(openssl rand -base64 32) \
+  -e BETTER_AUTH_URL=http://localhost:3000 \
+  -e API_BASE_URL=http://your-registry-server:8080 \
+  toolhive-cloud-ui:latest
+```
+
+The application listens on port 3000.
+
+### Docker Compose
+
+The repository includes a Docker Compose file that starts the full stack (Cloud
+UI, Registry Server, and databases). See the [quickstart](./quickstart.mdx) for
+a walkthrough.
+
+For production use with a real OIDC provider, create a `.env` file with your
+credentials and start without the `mock` profile:
+
+```bash title=".env"
+OIDC_ISSUER_URL=https://your-org.okta.com
+OIDC_CLIENT_ID=your-client-id
+OIDC_CLIENT_SECRET=your-client-secret
+BETTER_AUTH_SECRET=your-generated-secret
+```
+
+```bash
+make compose-up
+```
+
+### Kubernetes (Helm)
+
+The Cloud UI repository includes a Helm chart in the `helm/` directory. To
+deploy on Kubernetes:
+
+```bash
+helm install cloud-ui ./helm \
+  --set env.OIDC_ISSUER_URL=https://your-org.okta.com \
+  --set env.OIDC_CLIENT_ID=your-client-id \
+  --set env.OIDC_CLIENT_SECRET=your-client-secret \
+  --set env.BETTER_AUTH_SECRET=your-generated-secret \
+  --set env.BETTER_AUTH_URL=https://cloud-ui.example.com \
+  --set env.API_BASE_URL=http://registry-server:8080
+```
+
+:::info
+
+For production Kubernetes deployments, store sensitive values like
+`OIDC_CLIENT_SECRET` and `BETTER_AUTH_SECRET` in a Kubernetes Secret rather than
+passing them as Helm values.
+
+:::
+
+The Helm chart supports:
+
+- Replica count and horizontal pod autoscaling (HPA)
+- Resource requests and limits
+- Liveness and readiness probes
+- Ingress configuration
+- Custom service types (ClusterIP, NodePort, LoadBalancer)
+
+Refer to the chart's `values.yaml` for the full set of configurable parameters.
+
+## Next steps
+
+- [Publish servers](../guides-registry/publish-servers.mdx) to populate your
+  catalog with MCP server entries.
+- Set up [Registry Server authentication](../guides-registry/authentication.mdx)
+  to control access to the catalog API.
+- Learn about the [Registry Server architecture](../guides-registry/intro.mdx)
+  to understand how the backend works.
diff --git a/docs/toolhive/guides-cloud-ui/index.mdx b/docs/toolhive/guides-cloud-ui/index.mdx
@@ -0,0 +1,71 @@
+---
+title: ToolHive Cloud UI
+description:
+  Browse and manage MCP servers from a web-based catalog backed by the Registry
+  Server
+---
+
+import DocCardList from '@theme/DocCardList';
+
+## Introduction
+
+The ToolHive Cloud UI is a web application that gives your team a shared catalog
+of MCP servers. It connects to a [Registry Server](../guides-registry/index.mdx)
+and displays every registered server in a browsable interface, so team members
+can discover available servers and copy connection URLs into their AI agents or
+clients.
+
+Use the Cloud UI when you want to:
+
+- Give your team a single place to discover MCP servers without using the CLI or
+  desktop app.
+- Provide a self-service catalog where users copy server URLs directly into
+  their AI workflows.
+- Layer authentication on top of the catalog with your existing identity
+  provider (IdP).
+
+:::note
+
+The Cloud UI is a **read-oriented catalog** that works alongside the Registry
+Server. It does not start or stop MCP servers. To manage server lifecycles, use
+the [ToolHive CLI](../guides-cli/index.mdx),
+[ToolHive UI](../guides-ui/index.mdx), or
+[Kubernetes Operator](../guides-k8s/index.mdx).
+
+:::
+
+## Architecture overview
+
+The Cloud UI is a Next.js application with two main dependencies:
+
+- **Registry Server** - provides the MCP server catalog through the
+  [MCP Registry API](../reference/registry-api.mdx). The Cloud UI reads server
+  entries from this API.
+- **OIDC provider** - handles user authentication. The Cloud UI uses
+  [Better Auth](https://www.better-auth.com/) with any standards-compliant OIDC
+  provider (Okta, Microsoft Entra ID, Auth0, and others).
+
+```text
++-----------+       +----------+       +-----------------+
+|  Browser  | ----> | Cloud UI | ----> | Registry Server |
++-----------+       +----------+       +-----------------+
+                         |
+                         v
+                  +---------------+
+                  | OIDC Provider |
+                  +---------------+
+```
+
+## Where to start
+
+- **New to the Cloud UI?** Follow the [quickstart](./quickstart.mdx) to deploy a
+  local instance with Docker Compose.
+- **Configuring a deployment?** See [Configuration](./configuration.mdx) for
+  environment variables, OIDC setup, and deployment options.
+- **Setting up the backend?** The Cloud UI requires a running Registry Server.
+  See the [Registry Server quickstart](../guides-registry/quickstart.mdx) to get
+  one running.
+
+## Contents
+
+<DocCardList />
diff --git a/docs/toolhive/guides-cloud-ui/quickstart.mdx b/docs/toolhive/guides-cloud-ui/quickstart.mdx
@@ -0,0 +1,134 @@
+---
+title: 'Quickstart: Cloud UI'
+sidebar_label: Quickstart
+description:
+  Deploy the ToolHive Cloud UI locally with Docker Compose and browse your MCP
+  server catalog
+schema_type: tutorial
+---
+
+In this tutorial, you'll deploy the ToolHive Cloud UI alongside the Registry
+Server using Docker Compose. By the end, you'll have a running web catalog where
+you can browse MCP servers and copy their connection URLs.
+
+## What you'll learn
+
+- How to clone and configure the Cloud UI repository
+- How to start the full stack (Cloud UI, Registry Server, and databases) with
+  Docker Compose
+- How to sign in with a mock OIDC provider for local testing
+- How to browse the MCP server catalog
+
+## Prerequisites
+
+Before starting, make sure you have:
+
+- [Docker](https://docs.docker.com/get-docker/) and
+  [Docker Compose](https://docs.docker.com/compose/install/) (v2.20+)
+- [Git](https://git-scm.com/downloads)
+
+## Step 1: Clone the repositories
+
+The Cloud UI depends on the Registry Server, which is included as a Docker
+Compose reference from a sibling directory. Clone both repositories into the
+same parent folder:
+
+```bash
+git clone https://github.com/stacklok/toolhive-registry-server.git
+git clone https://github.com/stacklok/toolhive-cloud-ui.git
+```
+
+Your directory layout should look like this:
+
+```text
+parent-folder/
+  toolhive-registry-server/
+  toolhive-cloud-ui/
+```
+
+## Step 2: Start the stack with mock authentication
+
+Change into the Cloud UI directory and start all services using the `mock`
+profile. This profile includes a built-in OIDC mock server so you don't need to
+configure a real identity provider:
+
+```bash
+cd toolhive-cloud-ui
+make compose-up-mock
+```
+
+Alternatively, use Docker Compose directly:
+
+```bash
+docker compose --profile mock up --build
+```
+
+This starts five services:
+
+| Service          | Port | Description                            |
+| ---------------- | ---- | -------------------------------------- |
+| **cloud-ui**     | 3000 | The Cloud UI web application           |
+| **registry-api** | 8080 | The Registry Server API                |
+| **auth-db**      | 5433 | PostgreSQL database for authentication |
+| **postgres**     | 5432 | PostgreSQL database for the registry   |
+| **oidc-mock**    | 4000 | Mock OIDC provider for local testing   |
+
+Wait until all services are healthy. You can check their status with:
+
+```bash
+docker compose --profile mock ps
+```
+
+## Step 3: Open the Cloud UI
+
+Open your browser and navigate to `http://localhost:3000`. You'll see the
+sign-in page.
+
+Sign in using the mock OIDC provider. The mock provider accepts any credentials,
+so you can use any email and password combination.
+
+## Step 4: Browse the catalog
+
+After signing in, you'll see the MCP server catalog. The catalog displays
+servers registered in the Registry Server. From here, you can:
+
+- Browse available MCP servers
+- View server details and connection information
+- Copy server URLs for use in your AI agents or MCP clients
+
+:::tip
+
+The Registry Server starts with a default configuration file. To add your own
+MCP server entries, see the
+[Registry Server configuration](../guides-registry/configuration.mdx) guide.
+
+:::
+
+## Clean up
+
+To stop all services and remove the containers:
+
+```bash
+make compose-down
+```
+
+Or with Docker Compose directly:
+
+```bash
+docker compose --profile mock down
+```
+
+To also remove the database volumes (deletes all stored data):
+
+```bash
+docker compose --profile mock down -v
+```
+
+## Next steps
+
+- [Configure the Cloud UI](./configuration.mdx) for production use with a real
+  OIDC provider.
+- [Deploy the Registry Server](../guides-registry/deployment.mdx) on Kubernetes
+  for a production-grade backend.
+- Learn about [publishing servers](../guides-registry/publish-servers.mdx) to
+  populate your catalog.
diff --git a/docs/toolhive/guides-registry/index.mdx b/docs/toolhive/guides-registry/index.mdx
@@ -31,6 +31,14 @@ If you want to host and operate your own catalog, use the Registry Server. If
 you only need to browse the default ToolHive catalog from the UI or CLI, you do
 not need to deploy it.
 
+:::tip
+
+Want a web-based interface for your Registry Server catalog? The
+[Cloud UI](../guides-cloud-ui/index.mdx) connects to the Registry Server and
+gives your team a browsable catalog with OIDC-based authentication.
+
+:::
+
 ## Where to start
 
 - **New to the Registry Server?** Follow the

diff --git a/sidebars.ts b/sidebars.ts
@@ -261,6 +261,21 @@ const sidebars: SidebarsConfig = {
       ],
     },
 
+    {
+      type: 'category',
+      label: 'Cloud UI',
+      description:
+        'How to deploy and use the ToolHive Cloud UI to browse and manage MCP servers',
+      link: {
+        type: 'doc',
+        id: 'toolhive/guides-cloud-ui/index',
+      },
+      items: [
+        'toolhive/guides-cloud-ui/quickstart',
+        'toolhive/guides-cloud-ui/configuration',
+      ],
+    },
+
     {
       type: 'html',
       value: 'Shared guides',