Skip to main content

Registry policy

Use the registry policy to configure the MCP registry used by Stacklok clients. 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 to require the configured registry. Use default to let client operators override the registry 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​