docs-website/docs/toolhive/guides-cli/registry.mdx at dc2aaa2ea3b1f6ba97fc727ef5036b925e570f19 · stacklok/docs-website

title	Explore the registry
description	How to use the built-in registry to find MCP servers.

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. Simply select one from the list and run it securely with a single command.

Find MCP servers

To list all MCP servers in the ToolHive registry, run:

thv registry list

This command displays a list of servers with their name, description, tier (official or community), and the number of stars and downloads to help you identify the most popular and useful servers.

Example output:

NAME           DESCRIPTION                                                    TIER        STARS   PULLS
atlassian      Model Context Protocol (MCP) server for Atlassian product...   Community   2194    7789
elasticsearch  Connect to your Elasticsearch data directly from any MCP ...   Official    305     5429
everything     This MCP server attempts to exercise all the features of ...   Community   56714   10441
fetch          A Model Context Protocol server that provides web content...   Community   56714   9078
filesystem     Node.js server implementing Model Context Protocol (MCP) ...   Community   56714   14041
firecrawl      A powerful web scraping and content extraction MCP server...   Official    3605    7630
git            A Model Context Protocol server for Git repository intera...   Community   56714   7000
github         The GitHub MCP Server provides seamless integration with ...   Official    16578   5000
grafana        A Model Context Protocol (MCP) server for Grafana that pr...   Official    1014    4900
k8s            MKP is a Model Context Protocol (MCP) server for Kubernet...   Community   32      8064

<... trimmed for brevity ...>

You can also search by keyword to find servers related to a specific topic or capability:

thv search <TERM>

For example, to locate servers related to GitHub:

thv search github

View server details

To view detailed information about a specific MCP server, run:

thv registry info <SERVER_NAME>

For example:

thv registry info github

ToolHive provides the server's description, available tools, configuration options, and other metadata.

By default, ToolHive displays the server's configuration in a human-readable format. To view the configuration in JSON format, use the --format option:

thv registry info <SERVER_NAME> --format json

Example output

Name: github
Image: ghcr.io/github/github-mcp-server:latest
Description: The GitHub MCP Server provides seamless integration with GitHub APIs, enabling advanced automation and interaction capabilities for developers and tools
Tier: Official
Status: Active
Transport: stdio
Repository URL: https://github.com/github/github-mcp-server
Has Provenance: Yes
Popularity: 13894 stars, 5000 pulls
Last Updated: 2025-05-20T00:21:46Z
Tools:
  - get_me
  - get_issue
  - create_issue
  - add_issue_comment
  - list_issues
<... trimmed for brevity ...>

Environment Variables:
  - GITHUB_PERSONAL_ACCESS_TOKEN (required): GitHub personal access token with appropriate permissions
  - GH_HOST: GitHub Enterprise Server hostname (optional)
Tags:
  api, create, fork, github, list, pull-request, push, repository, search, update, issues
Permissions:
  Network:
    Allow Transport: tcp
    Allow Host: docs.github.com, github.com
    Allow Port: 443
Example Command:
  thv run github

This information helps you understand the server's capabilities, requirements, and security profile before running it.

Server name (line 1): The server name to use with the thv run command
Metadata (lines 2-10): Details about the server, including the image name, description, status, transport method, repository URL, whether the server has SLSA provenance available for verification, and popularity
Tools list (line 11): The list of tools this MCP server provides
Configuration (line 19): Required and optional environment variables needed to run the server
Permissions (line 24): The permission profile applied to the server, including file system and network access (see Custom permissions)

Use a custom registry

By default, ToolHive uses a built-in registry of verified MCP servers. You can configure ToolHive to use a custom registry instead. This is useful for organizations that want to maintain their own private registry of MCP servers.

ToolHive supports two types of custom registries:

File-based registries: JSON files that follow either the ToolHive registry schema or the upstream registry schema
API-based registries: REST API endpoints that implement the MCP Registry API specification, which use the upstream registry schema

Once you configure a custom registry, ToolHive uses it for all commands that interact with the registry, such as thv registry list, thv registry info, and thv run.

Set a remote registry

To configure ToolHive to use a remote registry, set the registry URL or API endpoint:

thv config set-registry <URL>

The CLI automatically detects the registry type:

URLs ending with .json are treated as static registry files
Other URLs are probed to detect MCP Registry API endpoints, falling back to static files if the probe fails
Local paths are treated as local registry files

Examples:

# Static registry file
thv config set-registry https://example.com/registry.json

# API endpoint
thv config set-registry https://registry.example.com

Set a local registry file

To configure ToolHive to use a local registry file, set the file path:

thv config set-registry <PATH>

For example:

thv config set-registry /path/to/local-registry.json

Check the current registry

To see which registry is currently configured:

thv config get-registry

This displays the configured registry URL, API endpoint, or file path. If no custom registry is configured, this command indicates that the built-in registry is being used.

Revert to the built-in registry

To remove the custom registry configuration and revert to using the built-in registry:

thv config unset-registry

This restores the default behavior of using ToolHive's built-in registry.

Organize servers with 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.

:::note

Registry groups are different from runtime groups. Registry groups organize server definitions within registry files, while runtime groups organize running server instances for access control.

:::

Group structure

Groups are defined as a top-level array in your custom registry:

{
  "servers": {
    // Individual servers
  },
  "groups": [
    {
      "name": "group-name",
      "description": "Description of what this group provides",
      "servers": {
        "server-name": {
          // Complete server definition
        }
      },
      "remote_servers": {
        "remote-server-name": {
          // Complete remote server definition
        }
      }
    }
  ]
}

Key characteristics

Optional: Groups are entirely optional. Omit the groups section if you only need individual servers
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 top-level servers but with different configurations
Flexible membership: The same server can appear in multiple groups with different configurations

Example: Multi-environment groups

Here's an example showing how groups can organize servers for different purposes:

{
  "$schema": "https://raw.githubusercontent.com/stacklok/toolhive-core/main/registry/types/data/toolhive-legacy-registry.schema.json",
  "version": "1.0.0",
  "last_updated": "2025-08-15T10:00:00Z",
  "servers": {
    "production-fetch": {
      "description": "Production web content fetching server",
      "image": "ghcr.io/stackloklabs/gofetch/server:latest",
      "status": "Active",
      "tier": "Community",
      "transport": "streamable-http",
      "permissions": {
        "network": {
          "outbound": {
            "allow_host": [".company.com"],
            "allow_port": [443]
          }
        }
      }
    }
  },
  "groups": [
    {
      "name": "devops-toolkit",
      "description": "Complete DevOps toolkit for development teams",
      "servers": {
        "github": {
          "description": "GitHub integration for repository and issue management",
          "image": "ghcr.io/github/github-mcp-server:v0.15.0",
          "status": "Active",
          "tier": "Official",
          "transport": "stdio",
          "env_vars": [
            {
              "name": "GITHUB_PERSONAL_ACCESS_TOKEN",
              "description": "GitHub personal access token",
              "required": true,
              "secret": true
            }
          ]
        },
        "heroku": {
          "description": "Heroku platform deployment and management",
          "image": "ghcr.io/stacklok/dockyard/npx/heroku-mcp-server:1.0.7",
          "status": "Active",
          "tier": "Community",
          "transport": "stdio",
          "env_vars": [
            {
              "name": "HEROKU_API_KEY",
              "description": "Heroku API key",
              "required": true,
              "secret": true
            }
          ]
        }
      }
    },
    {
      "name": "testing-suite",
      "description": "Servers needed for automated testing workflows",
      "servers": {
        "test-fetch": {
          "description": "Restricted fetch server for testing",
          "image": "ghcr.io/stackloklabs/gofetch/server:latest",
          "status": "Active",
          "tier": "Community",
          "transport": "streamable-http",
          "args": ["--timeout", "5s"],
          "permissions": {
            "network": {
              "outbound": {
                "allow_host": ["test.example.com"],
                "allow_port": [443]
              }
            }
          }
        }
      }
    }
  ]
}

This registry provides:

A production-ready production-fetch server at the top level
A devops-toolkit group with GitHub and Heroku servers for complete DevOps workflows
A testing-suite group with a restricted test-fetch server

Notice how the devops-toolkit group contains multiple servers that work together—GitHub for repository management and Heroku for deployment—demonstrating how groups can bundle related functionality.

Run registry groups

You can run entire groups using the group command:

# Run all servers in the devops-toolkit group (GitHub + Heroku)
thv group run devops-toolkit

# Run all servers in the testing-suite group
thv group run testing-suite

# You can also pass environment variables and secrets to specific servers in the group
thv group run devops-toolkit --secret github-token,target=github.GITHUB_PERSONAL_ACCESS_TOKEN --secret heroku-key,target=heroku.HEROKU_API_KEY

Groups provide a convenient way to start multiple related servers with a single command.

Next steps

See Run MCP servers to run an MCP server from the registry.

Learn how to create a custom MCP registry.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Find MCP servers

View server details

Example output

Use a custom registry

Set a remote registry

Set a local registry file

Check the current registry

Revert to the built-in registry

Organize servers with registry groups

Group structure

Key characteristics

Example: Multi-environment groups

Run registry groups

Next steps

Related information

FilesExpand file tree

registry.mdx

Latest commit

History

registry.mdx

File metadata and controls

Find MCP servers

View server details

Example output

Use a custom registry

Set a remote registry

Set a local registry file

Check the current registry

Revert to the built-in registry

Organize servers with registry groups

Group structure

Key characteristics

Example: Multi-environment groups

Run registry groups

Next steps

Related information