Skip to main content

Introduction

The ToolHive Registry Server gives you a way to publish, curate, and control a catalog of MCP servers and skills for your organization. Use it when you want a trusted catalog for discoverability, team-scoped access, publishing, or multi-source aggregation.

It pulls entries from multiple sources, stores them centrally, and exposes them through a standard MCP Registry API that ToolHive and other clients can consume.

Registry Server vs. built-in registry

This section covers the Registry Server for hosting and curating your own MCP server and skills 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 Use the registry (CLI) or Use the registry (UI).

Why use the Registry Server?​

Use the Registry Server when you need to:

  • Curate a private or team-specific catalog instead of relying only on the default public catalog
  • Publish MCP servers or skills for internal use
  • Aggregate entries from multiple sources behind one registry API
  • Apply authentication and authorization policies to registry access
  • Surface cluster-hosted workloads to users through a managed catalog

Key concepts​

The Registry Server is built around three core concepts:

  • A source is where data comes from: a Git repository, an upstream API, a local file, a Kubernetes cluster, or a managed API endpoint. Each source syncs or receives MCP servers and skills.
  • An entry is an individual MCP server or skill stored in the database. Sources produce entries; each entry belongs to exactly one source.
  • A registry is a named API surface that aggregates entries from one or more sources. Clients access entries through a registry name in the URL (for example, GET /registry/default/v0.1/servers). You can create multiple registries from the same sources to serve different audiences or apply different access controls.

How the Registry Server works​

The Registry Server aggregates MCP server and skills metadata from various sources and exposes it through a standardized API. When you start the server, it:

  1. Loads configuration from a YAML file
  2. Runs database migrations automatically
  3. Immediately fetches registry data from the configured sources
  4. Starts a background sync coordinator for automatic updates (for synced sources)
  5. Serves MCP Registry API endpoints on the configured address

Features​

  • Standards-compliant: Implements the official MCP Registry API specification
  • Multiple registry sources: Git repositories, API endpoints, local files, managed sources, and Kubernetes discovery
  • Automatic synchronization: Background sync with configurable intervals and retry logic for Git, API, and File sources
  • Container-ready: Designed for deployment in Kubernetes clusters, but can be deployed anywhere
  • Flexible deployment: Works standalone or as part of ToolHive infrastructure
  • Production-ready: Built-in health checks, graceful shutdown, and sync status persistence
  • Kubernetes-aware: Automatic discovery of MCP servers deployed via ToolHive Operator
  • Multi-tenant authorization: Claims-based access control with role-based administration, enabling team-scoped registries and entry visibility
  • Skills registry: Publish and discover reusable skills via the extensions API and synced sources

Registry sources​

The server supports five source types:

  1. Managed - A fully-managed MCP source

    • Ideal for hosting private MCP server catalogs
    • Automatically exposes entries following upstream MCP Registry format
    • Supports publishing MCP servers and skills via the /v1/entries admin API

  2. Upstream API - Sync from upstream MCP Registry APIs

    • Supports federation and aggregation scenarios
    • Syncs both MCP servers and skills from upstream sources
    • Does not support publishing

  3. Kubernetes - Automatically creates registry entries for running workloads

    • Ideal for surfacing running MCP servers to end users without manual registration
    • Useful for larger organizations where MCP server developers differ from consumers
    • Does not support publishing

  4. Git - Clone and sync from Git repositories

    • Supports branch, tag, or commit pinning
    • Syncs both MCP servers and skills (upstream format)
    • Does not support publishing

  5. File - Read from filesystem

    • Ideal for local development and testing
    • Syncs both MCP servers and skills (upstream format)
    • Does not support publishing

Registry Server and the rest of ToolHive​

The Registry Server is one part of the broader ToolHive platform. It is different from the built-in catalog that the ToolHive CLI and UI ship with for browsing public MCP servers, but the pieces work together:

  • The CLI's thv search and thv registry commands query the built-in catalog by default, but can also be pointed at a Registry Server you host with thv config set-registry.
  • Kubernetes deployments driven by the ToolHive operator can register discovered MCPServer workloads as entries in a Registry Server through the Kubernetes source type.

If you want a private or team-scoped catalog with publishing, claims-based access control, and multi-source aggregation, deploy a Registry Server. If you only need to browse the public ToolHive catalog, the built-in registry is enough.

Next steps​