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. 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:

Legacy format no longer accepted

The legacy ToolHive-native registry format is no longer accepted by thv config set-registry or by remote registries. To migrate an existing custom registry file, run thv registry convert:

thv registry convert --in registry.json --in-place

The conversion is lossless: every ToolHive-specific field is mapped to a publisher-provided extension on the corresponding MCP server entry.

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
Host your own registry

You can deploy the ToolHive Registry Server to host a registry with authentication, multiple data sources, and automatic synchronization. Point thv config set-registry to your Registry Server endpoint.

Authenticate to a protected registry​

Some remote registries require authentication before you can list, inspect, or run their servers. ToolHive authenticates to these registries using an interactive OAuth login backed by an OpenID Connect (OIDC) identity provider. If your registry is open to anonymous access, you don't need to log in.

Logging in needs three values: the registry URL, the OIDC issuer URL, and an OAuth client ID. Supply them as flags the first time you authenticate. ToolHive validates and saves them, then opens your browser to complete the OAuth flow:

thv registry login \
  --registry https://registry.example.com/api \
  --issuer https://auth.example.com \
  --client-id my-app

ToolHive caches the resulting tokens and reuses the saved settings, so later logins (after you log out or your tokens expire) need no flags:

thv registry login

Pass --issuer or --client-id again to override the saved values.

The login command accepts the following flags:

FlagDescription
--registryRegistry URL. Persisted to your configuration if not already set.
--issuerOIDC issuer URL for the identity provider. ToolHive validates it via discovery.
--client-idOAuth client ID registered with the identity provider.
--audienceOAuth audience parameter (optional).
--scopesComma-separated OAuth scopes to request. Defaults to openid,offline_access.
-p, --allow-private-ipAllow --registry to reference a private IP address. Defaults to false.
note

OAuth login applies only to remote registries (a URL or API endpoint). It isn't supported for local registry files. Supplying a new --registry URL clears any previously saved credentials so that tokens are never sent to the wrong server.

When you're done, clear the cached credentials with:

thv registry logout

This removes the cached OAuth tokens for the configured registry. The next registry command that requires authentication prompts you to log in again.

For details on configuring authentication on the server side, see Authentication configuration in the Registry Server documentation.

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 under data.groups in your custom registry. Each group has a name, description, and an array of servers:

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

See the registry schema for the full server object structure.

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

Full example​

For a complete custom registry file with both top-level servers and groups, see the Full example in the registry schema reference.

Use registry servers with groups​

You can organize registry servers into runtime groups after running them:

thv group create dev-toolkit
thv run --group dev-toolkit github
thv run --group dev-toolkit heroku

You can pass environment variables and secrets to each server individually:

thv run --group dev-toolkit --secret github-token,target=GITHUB_PERSONAL_ACCESS_TOKEN github
thv run --group dev-toolkit --secret heroku-key,target=HEROKU_API_KEY heroku

Groups provide a convenient way to start multiple related servers with a single command. See Group management for more details on creating and managing groups.

Next steps​

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

Learn how to create a custom MCP registry.