Configuration

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

Configuration file structure

config.yaml

# Registry name/identifier (optional, defaults to "default")
registryName: my-registry

# Data source configuration (required)
source:
  # Source type: git, api, or file
  type: git

  # Data format: toolhive (native) or upstream (MCP registry format)
  format: toolhive

  # Source-specific configuration
  git:
    repository: https://github.com/stacklok/toolhive.git
    branch: main
    path: pkg/registry/data/registry.json

# Automatic sync policy (required)
syncPolicy:
  # Sync interval (e.g., "30m", "1h", "24h")
  interval: '30m'

# Optional: Server filtering
filter:
  names:
    include: ['official/*']
    exclude: ['*/deprecated']
  tags:
    include: ['production']
    exclude: ['experimental']

# Optional: Database configuration
database:
  host: localhost
  port: 5432
  user: registry
  database: registry
  sslMode: require
  maxOpenConns: 25
  maxIdleConns: 5
  connMaxLifetime: '5m'

Command-line flags

Flag	Description	Required	Default
--config	Path to YAML configuration file	Yes	-
--address	Server listen address	No	:8080

Data sources

The server supports three data source types, each with its own configuration options.

Git repository source

Clone and sync from Git repositories. Ideal for version-controlled registries.

config-git.yaml

source:
  type: git
  format: toolhive
  git:
    repository: https://github.com/stacklok/toolhive.git
    branch: main
    path: pkg/registry/data/registry.json

Configuration options:

• repository (required): Git repository URL
• branch (optional): Branch name to use (defaults to main)
• tag (optional): Tag name to pin to a specific version
• commit (optional): Commit SHA to pin to a specific commit
• path (required): Path to the registry file within the repository

tip

You can use branch, tag, or commit to pin to a specific version. If multiple are specified, commit takes precedence over tag, which takes precedence over branch.

API endpoint source

Sync from upstream MCP Registry APIs. Supports federation and aggregation scenarios.

config-api.yaml

source:
  type: api
  format: upstream
  api:
    endpoint: https://registry.example.com/registry/v0.1/servers

Configuration options:

• endpoint (required): URL of the upstream MCP Registry API endpoint

Local file source

Read from filesystem. Ideal for local development and testing.

config-file.yaml

source:
  type: file
  format: toolhive
  file:
    path: /path/to/registry.json

Configuration options:

• path (required): Path to the registry file on the filesystem

Sync policy

Configure automatic synchronization of registry data.

syncPolicy:
  # Sync interval (e.g., "30m", "1h", "24h")
  interval: '30m'

The interval field specifies how often the server should fetch updates from the data source. Use Go duration format (e.g., "30m", "1h", "24h").

Server filtering

Optionally filter which servers are exposed through the API.

filter:
  names:
    include: ['official/*']
    exclude: ['*/deprecated']
  tags:
    include: ['production']
    exclude: ['experimental']

Filter options:

• names.include: List of name patterns to include (supports wildcards)
• names.exclude: List of name patterns to exclude (supports wildcards)
• tags.include: List of tags that servers must have
• tags.exclude: List of tags that servers must not have

Database configuration

The server optionally supports PostgreSQL database connectivity for storing registry state and metadata. See the Database configuration guide for detailed information.

Next steps

• Deploy the server with your configuration
• Configure database storage for production use