Skip to main content

Quickstart: Cloud UI

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:

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:

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:

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:

cd toolhive-cloud-ui
make compose-up-mock

Alternatively, use Docker Compose directly:

docker compose --profile mock up --build

This starts five services:

ServicePortDescription
cloud-ui3000The Cloud UI web application
registry-api8080The Registry Server API
auth-db5433PostgreSQL database for authentication
postgres5432PostgreSQL database for the registry
oidc-mock4000Mock OIDC provider for local testing

Wait until all services are healthy. You can check their status with:

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 guide.

Clean up​

To stop all services and remove the containers:

make compose-down

Or with Docker Compose directly:

docker compose --profile mock down

To also remove the database volumes (deletes all stored data):

docker compose --profile mock down -v

Next steps​