Skip to main content

Registry policy

Without a registry policy, developers can point ToolHive to any MCP registry, including unapproved ones. This guide shows you how to lock all clients to your internal registry so developers always pull from your vetted server catalog. The registry can be a self-hosted Registry Server, the upstream MCP registry, or any MCP-compatible registry.

You'll need your registry's URL (for example, https://registry.example.com) and the Enterprise Manager already deployed and reachable by clients.

Configure the registry directive​

Add the registry directive to your enterprise configuration. Replace the example URL with your registry's address and pick an enforcement level.

values.yaml
enterpriseConfig:
  registry:
    value:
      # The registry API URL all clients connect to
      api_url: 'https://registry.example.com'
    # "enforced" blocks local overrides; "default" lets users override locally
    enforcement: 'enforced'

Use enforced in regulated environments or when you need to guarantee that only vetted servers are accessible. Use default when you want to recommend a registry URL across your organization but allow teams or developers to switch for testing or local development.

After updating your configuration, apply the change.

Variations​

Advisory registry​

Suggest the registry URL as an org-wide default while allowing local overrides:

values.yaml
enterpriseConfig:
  registry:
    value:
      api_url: 'https://registry.example.com'
    enforcement: 'default'

Registry on a private IP​

If your registry responds with private IP addresses (for example, a registry that runs inside your VPC), set allow_private_ip: true so clients accept those responses:

values.yaml
enterpriseConfig:
  registry:
    value:
      api_url: 'https://registry.internal.example.com'
      allow_private_ip: true
    enforcement: 'enforced'

Registry URL for the console​

The registry directive sets two URLs because ToolHive clients and the console connect to the registry differently. The api_url value is for ToolHive clients: depending on your registry, that's either the registry's root URL (as in the examples above) or a per-registry path on a Stacklok Registry Server (for example, https://registry.example.com/registry/<REGISTRY_NAME>). The console needs the Registry Server's API root instead, set with server_api_url:

values.yaml
enterpriseConfig:
  registry:
    value:
      # For ToolHive clients: the registry API URL (one registry)
      api_url: 'https://registry.example.com/registry/toolhive'
      # For the console: the Registry Server's API root
      server_api_url: 'https://registry.example.com'
    enforcement: 'enforced'

When server_api_url isn't set, the console falls back to its API_BASE_URL environment variable.

Next steps​