Skip to main content

Use the registry

ToolHive includes a built-in registry of MCP servers with verified configurations that meet a minimum quality standard, allowing you to discover and deploy high-quality tools effortlessly. You can browse the registry, select servers, and run them securely through the user interface.

You can also configure ToolHive to use a custom registry instead. This is useful for organizations that want to maintain their own private registry of MCP servers.

Find MCP servers​

The ToolHive interface includes a dedicated Registry section in the main menu. This section lets you explore the various MCP servers available in either the built-in or custom registry.

ToolHive Registry PageToolHive Registry Page

The registry interface displays a list of available servers. You can browse through the list, use search functionality, and click on any server to view detailed information before installing it.

View server details​

Click on any server in the registry to view detailed information including:

  • Server name and description: Full description of what the server does
  • Tier badge: Shows whether the server is Official or Community
  • Transport type: Shows the communication method (e.g., stdio)
  • Popularity: Star count and download statistics
  • Provenance: Security verification status (e.g., "Provenance signed by Sigstore")
  • Tools listed: Names of all available tools the server provides
  • Action buttons: Install server and GitHub (if repository available)

This detailed view helps you understand the server's purpose and capabilities before adding it to your ToolHive installation.

Registry groups​

Registry groups allow you to organize related MCP servers and run them together as a cohesive unit. This is particularly useful for creating team-specific toolkits, workflow-based server collections, or environment-specific configurations.

The default ToolHive registry contains only individual servers. To use groups, configure a custom registry that defines them.

Key characteristics​

  • Optional: Groups are entirely optional. You only need a custom registry with groups if you want to install multiple servers together
  • Independent server definitions: Each group contains complete server configurations, not references to top-level servers
  • Self-contained: Groups can define servers with the same names as individual servers but with different configurations
  • Flexible membership: The same server can appear in multiple groups with different configurations

Browse and view groups​

When you use a custom registry that includes groups, they appear in the registry grid alongside individual servers. Click on any group to view its name, description, and a list of all included servers with their descriptions. From the group details page, you can click Install group to begin installation.

Install a group​

To install a group:

  1. Click Install group to open the wizard
  2. Configure each server following the same process as installing an individual server
  3. Click Next after each server, or Finish on the last one

The wizard guides you through each server one at a time, showing your progress (for example, "Installing server 1 of 3"). After installation, the group appears in the MCP Servers page where you can manage the servers together.

Registry settings​

To configure your registry, ToolHive provides a dedicated Registry settings section in Settings → Registry with four options:

  • Default Registry - Use ToolHive's built-in verified registry
  • Remote Registry (JSON URL) - Specify a URL pointing to a static JSON registry file hosted on a web server
  • Local Registry (JSON File Path) - Specify a local file path to a JSON registry file on your system
  • Registry Server API - Connect to a ToolHive Registry Server endpoint with optional OIDC authentication

When you select Local Registry (JSON File Path), a Registry File Path field appears where you provide the absolute path to your local JSON registry file (for example: /path/myregistry/db.json).

When you select Registry Server API, a Registry Server API URL field appears where you provide the URL of your Registry Server endpoint (for example: https://registry.example.com:8080/api/registry). If your Registry Server requires authentication, expand the Authenticate with your OIDC provider section and enter the following fields:

  • Client ID - The OAuth client ID registered with your identity provider
  • Issuer URL - The OIDC issuer URL for your identity provider (for example: https://accounts.example.com)

After you save, ToolHive initiates the OAuth login flow with your OIDC provider.

tip

The Registry Server API option allows private IP addresses and HTTP connections, so you can use it with a locally hosted Registry Server during development.

Click Save to apply your configuration.

For detailed information on creating a custom registry, see the custom registry tutorial.

Registry settings showing Local Registry File Path option selected with Registry File Path input fieldRegistry settings showing Local Registry File Path option selected with Registry File Path input field

Next steps​

After exploring the registry and finding servers you want to use:

  • Install servers: Click on servers from the registry to install and configure them for your environment
  • Customize tools: Selectively enable or disable tools from installed registry servers to create focused tool sets
  • Manage running servers: Use the MCP Servers section to start, stop, and monitor your installed servers
  • Create custom registries: Set up your own private registry for organization-specific servers