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.acme.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.acme.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.acme.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.acme.com'
      allow_private_ip: true
    enforcement: 'enforced'

Registry URL for the Cloud UI​

The registry directive carries two distinct URLs because its two consumers expect different shapes. The api_url value is for ToolHive clients (CLI and Stacklok Desktop) and typically points at a single registry on your Registry Server (for example, https://registry.acme.com/registry/toolhive). The Enterprise Cloud UI instead needs the Registry Server's API root, set with server_api_url:

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

Don't point the Cloud UI at the client-shaped api_url — its API routes are relative to the server root, so requests return 404 errors. When server_api_url isn't set, the Cloud UI falls back to its API_BASE_URL environment variable (see Registry API URL resolution).

warning

The Enterprise Manager rejects configuration fields it doesn't recognize and refuses to start. When upgrading, deploy the platform version that introduces server_api_url before adding the field to your configuration.

Next steps​