Skip to main content

Create a custom MCP registry

Overview​

ToolHive includes a built-in registry of MCP servers with verified configurations that meet a minimum quality standard.

But you can also create your own custom registry to include the MCP servers that are relevant to your organization or specific use cases. This allows you to curate a list of servers that meet your specific needs.

Why create a custom registry?​

Creating a custom registry allows you to:

  • Curate a list of MCP servers tailored to your organization's needs
  • Include private or internal servers not listed in the public registry
  • Pre-configure server settings for easier deployment
  • Ensure all servers meet your organization's quality and security standards

Create your first custom registry​

In this tutorial, you'll create a custom MCP registry for ToolHive and configure it to use your own curated list of MCP servers. By the end, you'll have a working custom registry that you can extend with your organization's specific MCP servers.

What you'll build​

You'll create a JSON registry file containing a simple MCP server entry, configure ToolHive to use your custom registry, and verify it works by listing and running servers from your registry.

Prerequisites​

Before you start, make sure you have:

Step 1: Create the registry file​

First, create a new directory for your custom registry and navigate to it:

mkdir my-custom-registry
cd my-custom-registry

Create a new file called registry.json and add the following content:

registry.json
{
  "$schema": "https://raw.githubusercontent.com/stacklok/toolhive/main/pkg/registry/data/schema.json",
  "version": "1.0.0",
  "last_updated": "2025-08-15T10:00:00Z",
  "servers": {
    "my-fetch": {
      "description": "A custom web content fetching MCP server for our organization",
      "image": "ghcr.io/stackloklabs/gofetch/server:latest",
      "status": "Active",
      "tier": "Community",
      "transport": "streamable-http",
      "args": ["--user-agent", "Mozilla/5.0 (compatible;MyOrgFetchBot/1.0)"],
      "tags": ["web", "fetch", "content"],
      "tools": ["fetch"],
      "permissions": {
        "network": {
          "outbound": {
            "allow_host": [".example.com", "api.mycompany.com"],
            "allow_port": [80, 443]
          }
        }
      }
    }
  }
}

This registry defines a single MCP server called my-fetch with:

  • A description explaining its purpose
  • The container image to use
  • Required metadata like status and tier
  • A list of tools it provides
  • Command-line arguments for customization
  • Network permissions for security

Step 2: Configure ToolHive to use your registry​

Configure ToolHive to use your custom registry.

  1. Open the ToolHive application
  2. Navigate to Settings → Registry
  3. Select the Local Registry option
  4. Enter the full path to your registry.json file (for example: /Users/<YOUR_NAME>/my-custom-registry/registry.json)
  5. Click Save to apply the configuration

The UI will validate the registry file and confirm it's been set successfully.

Step 3: Test your custom registry​

Verify your custom registry is working.

  1. Navigate to the Registry page from the menu bar
  2. You should see your my-fetch server displayed alongside any other servers in your custom registry
  3. Click on the server to view its details, including description, tools, and configuration options

Step 4: Run a server from your registry​

Finally, run the MCP server from your custom registry.

  1. On the Registry page, click on your my-fetch server
  2. Click the Install server button
  3. Configure any required settings (the defaults from your registry will be pre-populated)
  4. Click Install server to start the MCP server
  5. Navigate to the MCP Servers page to see your running server and manage it

The server will appear in your MCP servers list, where you can start, stop, view logs, and manage it like any other MCP server.

Step 5: Add more servers (optional)​

You can extend your registry by adding more servers to the servers object. For example, add a second server (note this is just an example, it will not function if you try to run it):

registry.json
{
  "$schema": "https://raw.githubusercontent.com/stacklok/toolhive/main/pkg/registry/data/schema.json",
  "version": "1.0.0",
  "last_updated": "2025-08-15T10:00:00Z",
  "servers": {
    "my-fetch": {
      // ... existing server configuration
    },
    "company-tools": {
      "description": "Internal company tools and utilities MCP server",
      "image": "registry.company.com/mcp/company-tools:v1.2.0",
      "status": "Active",
      "tier": "Community",
      "transport": "stdio",
      "tools": ["get_employee_info", "create_ticket", "check_inventory"],
      "tags": ["internal", "company", "tools"],
      "env_vars": [
        {
          "name": "COMPANY_API_KEY",
          "description": "API key for accessing company internal services",
          "required": true,
          "secret": true
        }
      ]
    }
  }
}

After updating the file, the new server is immediately available for ToolHive CLI commands. For the UI, navigate to the registry settings and click Save to see the new server listed.

Production considerations​

While this tutorial uses a local file for simplicity, in production environments you should:

  • Host your registry on a secure HTTP server
  • Use version control to track changes to your registry
  • Implement proper access controls to prevent unauthorized modifications
  • Set up automated validation to ensure registry entries follow the schema
  • Regularly update the registry with new servers and remove deprecated ones

For production use, configure ToolHive to use a remote registry URL:

thv config set-registry https://registry.example.com/mcp-registry.json

What you've learned​

You've successfully:

  • Created a custom MCP registry following the JSON schema
  • Configured ToolHive to use your custom registry
  • Added MCP servers with proper metadata and permissions
  • Tested your registry by listing and running servers

You can now maintain your own curated list of MCP servers tailored to your organization's needs. The registry can include both public servers from container registries and private servers hosted within your organization.

Next steps​

Cleanup: Revert to the default registry​

If you want to switch back to using ToolHive's built-in registry after completing this tutorial, you can easily revert your configuration.

To revert to the default registry through the UI:

  1. Navigate to Settings → Registry
  2. Select the Default Registry option
  3. Click Save to apply the configuration

The UI will confirm that you're now using the built-in ToolHive registry.

After reverting, all registry commands (thv registry list, thv registry info, thv search) will use ToolHive's built-in registry instead of your custom one.