Deploy with the ToolHive Operator

Prerequisites

A Kubernetes cluster (current and two previous minor versions are supported)
Permissions to create resources in the cluster
kubectl configured to communicate with your cluster
The ToolHive operator installed in your cluster (see Deploy the operator)
A PostgreSQL database

Overview

The ToolHive operator deploys the Registry server in Kubernetes by creating MCPRegistry resources. Alternatively, you can deploy the Registry Server manually by following the manual deployment instructions.

High-level architecture

This diagram shows the basic relationship between components. The ToolHive operator watches for MCPRegistry resources and automatically creates the necessary infrastructure to run the Registry server.

Create a registry

You can create MCPRegistry resources in the namespaces where the ToolHive Operator is deployed.

See Deploy the operator to learn about the different deployment modes.

To create a registry, define an MCPRegistry resource and apply it to your cluster. The recommended approach uses the configYAML field, which passes the registry server's configuration directly without the operator parsing or transforming it.

This minimal example creates a registry that syncs from the ToolHive Git repository.

my-registry.yaml
apiVersion: toolhive.stacklok.dev/v1alpha1
kind: MCPRegistry
metadata:
  name: my-registry
  namespace: my-namespace # Update with your namespace
spec:
  displayName: My MCP Registry
  configYAML: |
    sources:
      - name: toolhive
        format: toolhive
        git:
          repository: https://github.com/stacklok/toolhive-catalog.git
          branch: main
          path: pkg/catalog/toolhive/data/registry-legacy.json
        syncPolicy:
          interval: '30m'
    registries:
      - name: default
        sources: ["toolhive"]
    auth:
      mode: anonymous

Apply the resource:

kubectl apply -f my-registry.yaml

What's happening?

When you apply an MCPRegistry resource, here's what happens:

The ToolHive operator detects the new resource (if it's in an allowed namespace)
The operator creates the necessary RBAC resources in the target namespace
The operator creates a Deployment containing the Registry server pod and service
The Registry server syncs data from the configured sources
The Registry API becomes available at the service endpoint

Configure registry sources

The registry server's configYAML uses a v2 configuration format that separates data sources (where registry data comes from) from registry views (logical registries that aggregate one or more sources). Each source defines a data origin, and each registry view references sources by name.

configYAML: |
  sources:
    - name: my-source
      format: toolhive
      git: { ... }
  registries:
    - name: default
      sources: ["my-source"]

You must explicitly declare all sources, including Kubernetes discovery sources.

Git repository source

Clone and sync from Git repositories. Ideal for version-controlled registries.

registry-git.yaml
apiVersion: toolhive.stacklok.dev/v1alpha1
kind: MCPRegistry
metadata:
  name: git-registry
spec:
  configYAML: |
    sources:
      - name: toolhive
        format: toolhive
        git:
          repository: https://github.com/stacklok/toolhive-catalog.git
          branch: main
          path: pkg/catalog/toolhive/data/registry-legacy.json
        syncPolicy:
          interval: '30m'
    registries:
      - name: default
        sources: ["toolhive"]
    auth:
      mode: anonymous

Git source fields:

Field	Required	Description
`repository`	Yes	Git repository URL (HTTP/HTTPS/SSH)
`branch`	No	Branch name (mutually exclusive with `tag`, `commit`)
`tag`	No	Tag name (mutually exclusive with `branch`, `commit`)
`commit`	No	Commit SHA (mutually exclusive with `branch`, `tag`)
`path`	No	Path to registry file (default: `registry.json`)

tip

You can use branch, tag, or commit to pin to a specific version. If multiple are specified, commit takes precedence over tag, which takes precedence over branch.

ConfigMap source

Read from a Kubernetes ConfigMap. Mount the ConfigMap as a volume and reference the file path in configYAML.

registry-configmap.yaml
apiVersion: toolhive.stacklok.dev/v1alpha1
kind: MCPRegistry
metadata:
  name: configmap-registry
spec:
  volumes:
    - name: registry-data
      configMap:
        name: registry-data
  volumeMounts:
    - name: registry-data
      mountPath: /data/registry
      readOnly: true
  configYAML: |
    sources:
      - name: local
        format: upstream
        file:
          path: /data/registry/registry.json
        syncPolicy:
          interval: '15m'
    registries:
      - name: default
        sources: ["local"]
    auth:
      mode: anonymous

The ConfigMap must exist in the same namespace as the MCPRegistry resource.

API source

Sync from an upstream MCP Registry API. Supports federation and aggregation scenarios.

registry-api.yaml
apiVersion: toolhive.stacklok.dev/v1alpha1
kind: MCPRegistry
metadata:
  name: api-registry
spec:
  configYAML: |
    sources:
      - name: upstream
        format: upstream
        api:
          endpoint: https://registry.example.com
        syncPolicy:
          interval: '1h'
    registries:
      - name: default
        sources: ["upstream"]
    auth:
      mode: anonymous

The controller automatically appends the appropriate API paths to the endpoint URL.

Kubernetes discovery source

Discover MCP servers from running Kubernetes resources in the cluster.

registry-k8s-discovery.yaml
apiVersion: toolhive.stacklok.dev/v1alpha1
kind: MCPRegistry
metadata:
  name: k8s-registry
spec:
  configYAML: |
    sources:
      - name: k8s
        format: upstream
        kubernetes: {}
    registries:
      - name: default
        sources: ["k8s"]
    auth:
      mode: anonymous

URL source

Fetch registry data from an HTTP/HTTPS URL.

registry-url.yaml
apiVersion: toolhive.stacklok.dev/v1alpha1
kind: MCPRegistry
metadata:
  name: url-registry
spec:
  configYAML: |
    sources:
      - name: remote
        format: upstream
        file:
          url: https://example.com/registry.json
        syncPolicy:
          interval: '1h'
    registries:
      - name: default
        sources: ["remote"]
    auth:
      mode: anonymous

Configure synchronization

Each source can have its own sync policy that controls automatic synchronization.

syncPolicy:
  interval: '30m' # Go duration format: "1h", "30m", "24h"

Filter registry content

You can filter which servers are exposed through the API using name and tag patterns on individual sources.

registry-filtered.yaml
apiVersion: toolhive.stacklok.dev/v1alpha1
kind: MCPRegistry
metadata:
  name: filtered-registry
spec:
  configYAML: |
    sources:
      - name: toolhive
        format: toolhive
        git:
          repository: https://github.com/stacklok/toolhive-catalog.git
          branch: main
          path: pkg/catalog/toolhive/data/registry-legacy.json
        filter:
          names:
            include:
              - 'official/*'
            exclude:
              - '*/deprecated'
          tags:
            include:
              - production
            exclude:
              - experimental
        syncPolicy:
          interval: '30m'
    registries:
      - name: default
        sources: ["toolhive"]
    auth:
      mode: anonymous

Configure database storage

Configure PostgreSQL database storage for the Registry server. With the configYAML approach, database settings go directly into the config and you use pgpassSecretRef for password management.

registry-with-database.yaml
apiVersion: v1
kind: Secret
metadata:
  name: registry-pgpass
type: Opaque
stringData:
  .pgpass: |
    postgres.database.svc.cluster.local:5432:registry:db_app:app_password
    postgres.database.svc.cluster.local:5432:registry:db_migrator:migrator_password
---
apiVersion: toolhive.stacklok.dev/v1alpha1
kind: MCPRegistry
metadata:
  name: production-registry
spec:
  pgpassSecretRef:
    name: registry-pgpass
    key: .pgpass
  configYAML: |
    sources:
      - name: toolhive
        format: toolhive
        git:
          repository: https://github.com/stacklok/toolhive-catalog.git
          branch: main
          path: pkg/catalog/toolhive/data/registry-legacy.json
        syncPolicy:
          interval: '30m'
    registries:
      - name: default
        sources: ["toolhive"]
    auth:
      mode: anonymous
    database:
      host: postgres.database.svc.cluster.local
      port: 5432
      user: db_app
      migrationUser: db_migrator
      database: registry
      sslMode: verify-full
      maxOpenConns: 25
      maxIdleConns: 5
      connMaxLifetime: '30m'

Database configuration fields:

Field	Default	Description
`host`	`postgres`	Database server hostname
`port`	`5432`	Database server port
`user`	`db_app`	Application user (SELECT, INSERT, UPDATE, DELETE)
`migrationUser`	`db_migrator`	Migration user (CREATE, ALTER, DROP)
`database`	`registry`	Database name
`sslMode`	`prefer`	SSL mode (disable, prefer, require, verify-full)
`maxOpenConns`	`10`	Maximum open connections
`maxIdleConns`	`2`	Maximum idle connections
`connMaxLifetime`	`30m`	Maximum connection lifetime

tip

Use pgpassSecretRef on the MCPRegistry resource to provide database credentials. The operator handles mounting and file permissions automatically. Create a Kubernetes Secret containing a pgpass-formatted file and reference it in your MCPRegistry spec.

Configure authentication

You can configure authentication in the auth section within configYAML.

Authentication modes

Mode	Description	Use case
`oauth`	Validates access tokens from identity providers	Production deployments
`anonymous`	No authentication required	Development and testing only

Secure by default

Configuring an authentication mode is mandatory, if you're not interested you can set it to anonymous.

OAuth authentication

OAuth mode validates JWT tokens from one or more identity providers. Configure providers in the auth.oauth.providers array within configYAML.

registry-oauth.yaml
apiVersion: toolhive.stacklok.dev/v1alpha1
kind: MCPRegistry
metadata:
  name: registry
  namespace: toolhive-system
spec:
  displayName: 'Authenticated MCP Server Registry'
  configYAML: |
    sources:
      - name: toolhive
        format: toolhive
        git:
          repository: https://github.com/stacklok/toolhive-catalog.git
          branch: main
          path: pkg/catalog/toolhive/data/registry-legacy.json
        syncPolicy:
          interval: '30m'
    registries:
      - name: default
        sources: ["toolhive"]
    auth:
      mode: oauth
      oauth:
        providers:
          - name: kubernetes
            issuerUrl: https://kubernetes.default.svc.cluster.local
            jwksUrl: https://kubernetes.default.svc/openid/v1/jwks
            audience: registry-server
            caCertPath: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt
            authTokenFile: /var/run/secrets/kubernetes.io/serviceaccount/token
            allowPrivateIP: true

OAuth configuration fields

Field	Required	Default	Description
`mode`	No	`oauth`	Authentication mode (`oauth` or `anonymous`)
`resourceUrl`	No	-	URL identifying this protected resource (RFC 9728)
`realm`	No	`mcp-registry`	Protection space identifier for WWW-Authenticate
`scopesSupported`	No	`[mcp-registry:read, mcp-registry:write]`	OAuth scopes supported by this resource

Provider configuration fields

Field	Required	Description
`name`	Yes	Unique identifier for this provider (for logging and monitoring)
`issuerUrl`	Yes	OIDC issuer URL (e.g., `https://accounts.google.com`)
`audience`	Yes	Expected audience claim in the access token
`jwksUrl`	No	JWKS endpoint URL (skips OIDC discovery if specified)
`clientId`	No	OAuth client ID for token introspection
`clientSecretFile`	No	Path to file containing the client secret
`caCertPath`	No	Path to CA certificate for TLS verification
`authTokenFile`	No	Path to token file for authenticating to OIDC/JWKS endpoints
`introspectionUrl`	No	Token introspection endpoint URL for opaque token validation (RFC 7662)
`allowPrivateIP`	No	Allow connections to private IP addresses (required for in-cluster)

Kubernetes service account authentication

For in-cluster deployments, you can configure OAuth to validate Kubernetes service account tokens:

registry-k8s-auth.yaml
apiVersion: toolhive.stacklok.dev/v1alpha1
kind: MCPRegistry
metadata:
  name: registry
spec:
  configYAML: |
    sources:
      - name: k8s
        format: upstream
        kubernetes: {}
    registries:
      - name: default
        sources: ["k8s"]
    auth:
      mode: oauth
      oauth:
        providers:
          - name: kubernetes
            issuerUrl: https://kubernetes.default.svc.cluster.local
            jwksUrl: https://kubernetes.default.svc/openid/v1/jwks
            audience: registry-server
            caCertPath: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt
            authTokenFile: /var/run/secrets/kubernetes.io/serviceaccount/token
            allowPrivateIP: true

Kubernetes provider settings

issuerUrl: for most Kubernetes distributions, https://kubernetes.default.svc.cluster.local is the correct value to match the iss claim in Kubernetes service account tokens.
jwksUrl: Specify directly to skip OIDC discovery (the Kubernetes API server doesn't support standard discovery).
allowPrivateIP: Required for in-cluster communication with the API server.

Multiple providers

You can configure multiple OAuth providers to accept tokens from different identity sources:

registry-multi-provider.yaml
apiVersion: toolhive.stacklok.dev/v1alpha1
kind: MCPRegistry
metadata:
  name: registry
spec:
  configYAML: |
    sources:
      - name: k8s
        format: upstream
        kubernetes: {}
    registries:
      - name: default
        sources: ["k8s"]
    auth:
      mode: oauth
      oauth:
        providers:
          # Kubernetes service accounts (in-cluster workloads)
          - name: kubernetes
            issuerUrl: https://kubernetes.default.svc.cluster.local
            jwksUrl: https://kubernetes.default.svc/openid/v1/jwks
            audience: registry-server
            caCertPath: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt
            authTokenFile: /var/run/secrets/kubernetes.io/serviceaccount/token
            allowPrivateIP: true
          # External identity provider
          - name: okta
            issuerUrl: https://YOUR_DOMAIN.okta.com/oauth2/default
            audience: registry

The server validates tokens against each provider in order until one succeeds.

Anonymous authentication

For development and testing, you can disable authentication entirely:

registry-anonymous.yaml
apiVersion: toolhive.stacklok.dev/v1alpha1
kind: MCPRegistry
metadata:
  name: registry
spec:
  configYAML: |
    sources:
      - name: toolhive
        format: toolhive
        git:
          repository: https://github.com/stacklok/toolhive-catalog.git
          branch: main
          path: pkg/catalog/toolhive/data/registry-legacy.json
        syncPolicy:
          interval: '30m'
    registries:
      - name: default
        sources: ["toolhive"]
    auth:
      mode: anonymous

No access control

Anonymous mode provides no access control. Only use it in trusted environments or when other security measures are in place. Do not use anonymous mode in production.

For detailed information about authentication configuration, including provider-specific examples for Keycloak, Auth0, Azure AD, and Okta, see the Authentication configuration guide.

Customize the Registry server pod

You can customize the Registry server pod using the podTemplateSpec field. This gives you full control over the pod specification.

registry-custom-pod.yaml
apiVersion: toolhive.stacklok.dev/v1alpha1
kind: MCPRegistry
metadata:
  name: custom-registry
spec:
  podTemplateSpec:
    spec:
      containers:
        - name: registry-api # This name must be "registry-api"
          resources:
            limits:
              cpu: '500m'
              memory: '512Mi'
            requests:
              cpu: '100m'
              memory: '128Mi'
  configYAML: |
    sources:
      - name: toolhive
        format: toolhive
        git:
          repository: https://github.com/stacklok/toolhive-catalog.git
          branch: main
          path: pkg/catalog/toolhive/data/registry-legacy.json
        syncPolicy:
          interval: '30m'
    registries:
      - name: default
        sources: ["toolhive"]
    auth:
      mode: anonymous

Container name requirement

When customizing containers in podTemplateSpec, you must use name: registry-api for the main container to ensure the operator can properly manage the Registry server. The container name is hardcoded to avoid conflict issues with user provided containers. Mandating a container name on the Operator side explicitly tells the Operator it is the main registry server container and any other containers provided by the user are sidecars/init containers.

Check registry status

To check the status of your registries in a specific namespace:

kubectl -n <NAMESPACE> get mcpregistries

To check registries across all namespaces:

kubectl get mcpregistries --all-namespaces

The status displays the phase, message, and age of each registry.

For more details about a specific registry:

kubectl -n <NAMESPACE> describe mcpregistry <NAME>

Registry phases

Phase	Description
`Pending`	The registry is being initialized
`Ready`	The registry is ready and operational
`Failed`	The registry has encountered an error
`Terminating`	The registry is being deleted

You can also use kubectl wait to wait for the registry to be ready:

kubectl -n <NAMESPACE> wait --for=condition=Ready mcpregistry/<NAME>

Next steps

Learn how to configure authentication for the Registry server in the Authentication configuration guide.

Configure additional registry sources and filtering options in the Configuration guide.

Kubernetes CRD reference - Reference for the MCPRegistry Custom Resource Definition (CRD)
Deploy the operator - Install the ToolHive operator
Database configuration - Configure PostgreSQL storage

Troubleshooting

MCPRegistry resource not creating pods

If your MCPRegistry resource is created but no pods appear:

Ensure you created the MCPRegistry resource in an allowed namespace
Check the operator's configuration:

helm get values toolhive-operator -n toolhive-system

Check the MCPRegistry status and operator logs:

# Check MCPRegistry status
kubectl -n <NAMESPACE> describe mcpregistry <NAME>

# Check operator logs
kubectl -n toolhive-system logs -l app.kubernetes.io/name=toolhive-operator

# Verify the operator is running
kubectl -n toolhive-system get pods -l app.kubernetes.io/name=toolhive-operator

Common causes include:

Operator not running: Ensure the ToolHive operator is deployed and running
RBAC issues: Check for cluster-level permission issues
Resource quotas: Check if namespace resource quotas prevent pod creation

Registry stuck in Pending phase

If the registry is stuck in Pending phase:

# Check registry status
kubectl -n <NAMESPACE> describe mcpregistry <NAME>

# Check registry pod logs
kubectl -n <NAMESPACE> logs -l app.kubernetes.io/instance=<NAME>

Common causes include:

Git repository inaccessible: Verify the repository URL is correct and accessible
ConfigMap doesn't exist: Ensure referenced resources exist in the same namespace
Network policies: Check if network policies are blocking external access
Invalid registry file format: Verify the registry JSON file is valid

Database connection errors

If you see database connection errors:

# Check registry pod logs
kubectl -n <NAMESPACE> logs -l app.kubernetes.io/instance=<NAME>

Common causes include:

Database not reachable: Verify database host and port are correct
Invalid credentials: Check that pgpass file is properly mounted
SSL configuration mismatch: Verify sslMode matches your database configuration
Permission issues: Ensure database users have required privileges

Sync failures

If synchronization is failing:

# Check registry status and conditions
kubectl -n <NAMESPACE> get mcpregistry <NAME> -o jsonpath='{.status.phase}'
kubectl -n <NAMESPACE> get mcpregistry <NAME> -o jsonpath='{.status.conditions}'

# Check logs
kubectl -n <NAMESPACE> logs -l app.kubernetes.io/instance=<NAME>

Common causes include:

Source unavailable: Git repository, API endpoint, or file is inaccessible
Invalid JSON format: Registry file contains invalid JSON
Format mismatch: The format field doesn't match the actual data format
Filter too restrictive: Filters may be excluding all servers

Prerequisites​

Overview​

High-level architecture​

Create a registry​

Configure registry sources​

Git repository source​

ConfigMap source​

API source​

Kubernetes discovery source​

URL source​

Configure synchronization​

Filter registry content​

Configure database storage​

Configure authentication​

Authentication modes​

OAuth authentication​

OAuth configuration fields​

Provider configuration fields​

Kubernetes service account authentication​

Multiple providers​

Anonymous authentication​

Customize the Registry server pod​

Check registry status​

Registry phases​

Next steps​

Related information​

Troubleshooting​

Prerequisites

Overview

High-level architecture

Create a registry

Configure registry sources

Git repository source

ConfigMap source

API source

Kubernetes discovery source

URL source

Configure synchronization

Filter registry content

Configure database storage

Configure authentication

Authentication modes

OAuth authentication

OAuth configuration fields

Provider configuration fields

Kubernetes service account authentication

Multiple providers

Anonymous authentication

Customize the Registry server pod

Check registry status

Registry phases

Next steps

Related information

Troubleshooting