toolhive-registry-server

ToolHive Registry Server

The central metadata hub for enterprise MCP governance and discovery

The ToolHive Registry Server (thv-registry-api) implements the official Model Context Protocol (MCP) Registry API specification. It serves as the centralized metadata engine for the ToolHive platform, enabling enterprises to curate, discover, and govern MCP servers with security and auditability built-in.

Table of contents

• Features
• Quickstart
• Core Concepts
  • Data Sources
  • Architecture
• API Endpoints
• Configuration
• Deployment
• Development
• Documentation
• Contributing

Features

Enterprise governance & security

• OAuth 2.0/OIDC authentication: Integrate with enterprise identity providers (Okta, Auth0, Azure AD)
• Multi-provider support: Combine corporate SSO with Kubernetes service accounts
• Secure by default: OAuth mode enabled by default, with granular access control
• Audit trail: Track MCP discovery and access through centralized metadata

Flexible registry sources

• Curated registries: Aggregate multiple sources into a unified catalog
• Upstream verified: Sync from public MCP registries implementing the standard API
• File-based registries: Support both ToolHive and upstream server.json formats
• Internal custom MCPs: Manage organization-specific MCP servers
• Kubernetes discovery: Automatically discover MCPs deployed in your clusters
• Automatic synchronization: Background sync with configurable intervals and retry logic

Enterprise integration

• Central metadata hub: Powers the ToolHive Enterprise UI with MCP metadata
• ToolHive Operator integration: Provides metadata for Kubernetes-native MCP deployment
• PostgreSQL backend: Scalable database storage with automatic migrations
• Standards-compliant: Implements the official MCP Registry API specification
• Production-ready: Built-in health checks, graceful shutdown, and observability

Quickstart

Prerequisites

• Go 1.23 or later (for building from source)
• Task for build automation
• PostgreSQL 16+ (optional, for database backend)

Build and run

# Build the binary
task build

# Run with Git source
thv-registry-api serve --config examples/config-git.yaml

# Run with local file
thv-registry-api serve --config examples/config-file.yaml

The server starts on http://localhost:8080 by default.

Docker quickstart

# Using Task (recommended - ensures fresh state)
task docker-up

# Or detached mode
task docker-up-detached

# Access the API
curl http://localhost:8080/registry/v0.1/servers

# Stop and clean up
task docker-down

Note: The task docker-up command ensures a fresh start by rebuilding the image and clearing all volumes (database + registry data). This prevents stale state issues.

What happens on startup

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

Core concepts

Data sources

The Registry Server enables enterprises to curate MCP catalogs from multiple sources, creating a unified view for developers and knowledge workers:

Key capability: Configure multiple registries simultaneously to create a federated catalog that combines:

• Official MCP Registry (registry.modelcontextprotocol.io) or any registry implementing the upstream specification
• Internal organization-specific MCPs
• Kubernetes-deployed MCPs
• Custom curated collections

Configuration example:

registries:
  - name: local
    format: toolhive
    file:
      path: /data/registry.json

For Git-based registries:

registries:
  - name: toolhive
    format: toolhive
    git:
      repository: https://github.com/stacklok/toolhive.git
      branch: main
      path: pkg/registry/data/registry.json
    syncPolicy:
      interval: '30m'

See Configuration Guide for complete details.

Architecture

The server follows clean architecture with clear separation of concerns:

┌─────────────────────────────────────────────┐
│  API Layer (Chi Router)                     │
│  ├─ Registry API v0.1                       │
│  ├─ Extension API v0                        │
│  └─ OAuth/OIDC Middleware                   │
└─────────────────────────────────────────────┘
                    │
┌─────────────────────────────────────────────┐
│  Service Layer                              │
│  ├─ DB Service (PostgreSQL)                 │
│  └─ In-Memory Service                       │
└─────────────────────────────────────────────┘
                    │
┌─────────────────────────────────────────────┐
│  Data Source Layer                          │
│  ├─ Git Handler                             │
│  ├─ API Handler                             │
│  ├─ File Handler                            │
│  ├─ Managed Handler                         │
│  └─ Kubernetes Handler                      │
└─────────────────────────────────────────────┘
                    │
┌─────────────────────────────────────────────┐
│  Sync Layer (Background Coordinator)        │
└─────────────────────────────────────────────┘

Key directories:

• internal/api/ - HTTP API handlers
• internal/service/ - Business logic
• internal/sources/ - Data source handlers
• internal/sync/ - Background synchronization
• internal/auth/ - OAuth/OIDC authentication
• internal/db/ - Database access (sqlc generated)
• database/ - SQL migrations and queries

API endpoints

The server provides two types of registry endpoints to support different use cases:

1. Aggregated registry endpoints (read-only)

Unified view across all configured registries - ideal for enterprise-wide discovery:

• GET /registry/v0.1/servers - List all MCP servers from all registries
• GET /registry/v0.1/servers/{name}/versions - List all versions of a server
• GET /registry/v0.1/servers/{name}/versions/{version} - Get a specific server version

2. Per-registry endpoints (standards-compliant)

Individual registry access - fully compatible with upstream MCP Registry API specification:

Read operations (all registry types):

• GET /registry/{registryName}/v0.1/servers - List servers from a specific registry
• GET /registry/{registryName}/v0.1/servers/{name}/versions - List versions from a specific registry
• GET /registry/{registryName}/v0.1/servers/{name}/versions/{version} - Get specific version from a specific registry

Write operations (managed registries only):

• POST /registry/{registryName}/v0.1/publish - Publish a server to a managed registry
• DELETE /registry/{registryName}/v0.1/servers/{name}/versions/{version} - Delete a server version from a managed registry

Note: Write operations (POST, DELETE) are only supported for managed registry types. Git, API, File, and Kubernetes registries are read-only through the API.

Extension API (v0)

ToolHive-specific extensions for querying registry status:

• GET /extension/v0/registries - List all configured registries with status
• GET /extension/v0/registries/{name} - Get registry details and sync status

Note: Dynamic registry and server management endpoints (PUT/DELETE operations) are not yet implemented.

Operational endpoints

• GET /health - Health check
• GET /readiness - Readiness check
• GET /version - Version information
• GET /.well-known/oauth-protected-resource - OAuth discovery (RFC 9728)

Use cases

• Aggregated endpoints: Enterprise UI showing unified catalog of all MCPs
• Per-registry endpoints: Direct access to specific registries (e.g., only upstream verified MCPs)
• Extension API: Query registry status and configuration

See the MCP Registry API specification for full API details.

Configuration

All configuration is done via YAML files. The server requires a --config flag.

Basic example

registryName: my-registry

registries:
  - name: local
    format: toolhive
    file:
      path: /data/registry.json

auth:
  mode: anonymous # Use "oauth" for production

# Optional: Add more registries
# - name: toolhive
#   format: toolhive
#   git:
#     repository: https://github.com/stacklok/toolhive.git
#     branch: main
#     path: pkg/registry/data/registry.json
#   syncPolicy:
#     interval: "30m"

# Optional: Database backend
# database:
#   host: localhost
#   port: 5432
#   user: registry
#   database: registry

📖 Complete guides

• Configuration reference - Complete configuration options
• Environment variables - Using environment variables for configuration
• Database setup - PostgreSQL configuration, migrations, and security
• Authentication - OAuth/OIDC setup and security

Configuration examples

See examples/ directory for complete working examples:

• config-git.yaml - Git repository source
• config-api.yaml - API endpoint source
• config-file.yaml - Local file source
• config-database-dev.yaml - With database (development)
• config-database-prod.yaml - With database (production)
• config-docker.yaml - For Docker Compose

Deployment

Docker Compose

Quick start with PostgreSQL (ensures fresh state):

# Start with fresh state (recommended)
task docker-up

# Or detached mode
task docker-up-detached

# View logs
task docker-logs           # All logs
FOLLOW=true task docker-logs  # Tail logs

# Stop and clean up
task docker-down

Note: Always use task docker-up instead of docker-compose up directly. The task command ensures fresh state by rebuilding the image and clearing volumes.

See Docker deployment guide for details.

Kubernetes

Basic deployment:

kubectl apply -f examples/kubernetes/

See Kubernetes deployment guide for production setup.

Standalone binary

# Linux/macOS
./bin/thv-registry-api serve --config config.yaml

# With environment variables
export THV_REGISTRY_DATABASE_HOST=postgres.example.com
export THV_REGISTRY_AUTH_MODE=anonymous
./bin/thv-registry-api serve --config config.yaml

📖 Deployment guides

• Docker & Docker Compose - Container deployment
• Kubernetes - K8s deployment, HA, and production best practices

Development

Build commands

# Build the binary
task build

# Run linting (auto-fix)
task lint-fix

# Run tests
task test

# Generate mocks
task gen

# Build container image
task build-image

# Run database migrations
task migrate-up CONFIG=examples/config-database-dev.yaml

# Regenerate documentation
task docs

# All checks (lint + test + build)
task all

Testing

# Generate mocks before testing
task gen

# Run all tests
task test

# Run specific test
go test ./internal/service/... -v

The project uses table-driven tests with mocks generated via go.uber.org/mock.

Project structure

cmd/thv-registry-api/    # Main application
├── app/                 # CLI commands (serve, migrate, prime-db, version)
└── main.go

internal/                # Internal packages
├── api/                 # HTTP API handlers
├── auth/                # OAuth/OIDC authentication
├── config/              # Configuration loading
├── db/                  # Database access (sqlc generated)
├── service/             # Business logic
├── sources/             # Data source handlers
├── sync/                # Background sync coordination
├── filtering/           # Registry entry filtering
├── git/                 # Git operations
├── kubernetes/          # Kubernetes discovery
└── registry/            # Registry data models

database/                # Database schema and queries
├── migrations/          # SQL migrations
└── queries/             # SQL queries for sqlc

examples/                # Example configurations
docs/                    # Documentation

Documentation

📚 Complete documentation

• Configuration reference - All configuration options
• Environment variables - Using environment variables for configuration
• Database setup - PostgreSQL setup and migrations
• Authentication - OAuth/OIDC security
• Kubernetes deployment - K8s deployment guide
• Docker deployment - Docker & Docker Compose
• API documentation - Auto-generated OpenAPI docs
• CLI reference - Command-line interface docs
• Examples - Working configuration examples
• CLAUDE.md - AI assistant guidance for contributors

Common Tasks

Integration with ToolHive

The Registry API server is the central metadata engine of the ToolHive platform:

Enterprise UI integration

• Metadata source: Provides MCP details (name, description, URL, version, branding)
• Server status: Reports sync status and availability for each registry
• Discovery experience: Powers the catalog browsing and search in the Enterprise UI
• Authentication: Enforces OAuth/OIDC access control from your identity provider

ToolHive Operator integration

• Deployment metadata: Operator references registry data when deploying MCPs to Kubernetes
• Automated discovery: Kubernetes-deployed MCPs automatically appear in the registry
• Custom Resource binding: MCPRegistry CRDs are backed by Registry Server data
• Lifecycle management: Tracks deployed MCP versions and configurations

Security & governance

• Centralized control: Single source of truth for approved MCPs
• Identity integration: Seamless integration with Okta, Auth0, Azure AD, and other providers
• Kubernetes-native: All MCP execution stays within your Kubernetes boundary
• Audit trail: Track MCP discovery and consumption patterns

See the ToolHive documentation for the complete platform architecture.

Contributing

We welcome contributions! Please see:

• Contributing guide - How to contribute
• Code of conduct - Community guidelines
• Security policy - Report security vulnerabilities
• CLAUDE.md - AI assistant guidance for development

Development guidelines

• Run task lint-fix before committing
• Ensure tests pass with task test
• Follow Go standard project layout
• Use mockgen for test mocks (never hand-written)
• Write table-driven tests
• Keep documentation up to date

Quick start for contributors

# Clone the repository
git clone https://github.com/stacklok/toolhive-registry-server.git
cd toolhive-registry-server

# Install dependencies
go mod download

# Run all checks
task all

# Make your changes...

# Run tests
task gen
task test

# Submit PR

License

This project is licensed under the Apache 2.0 License.

Part of the ToolHive project - Simplify and secure MCP servers