thv-operator

ToolHive Kubernetes Operator

The ToolHive Kubernetes Operator manages MCP (Model Context Protocol) servers and registries in Kubernetes clusters. It allows you to define MCP servers and registries as Kubernetes resources and automates their deployment and management.

This operator is built using Kubebuilder, a framework for building Kubernetes APIs using Custom Resource Definitions (CRDs).

This guide is intended for developers working on the ToolHive Operator. For user-facing documentation, please refer to the ToolHive docs website.

Overview

The operator introduces two main Custom Resource Definitions (CRDs):

MCPServer

Represents an MCP server in Kubernetes. When you create an MCPServer resource, the operator automatically:

1. Creates a Deployment to run the MCP server
2. Sets up a Service to expose the MCP server
3. Configures the appropriate permissions and settings
4. Manages the lifecycle of the MCP server

MCPRegistry

Represents an MCP server registry in Kubernetes. When you create an MCPRegistry resource, the operator automatically:

1. Synchronizes registry data from various sources (ConfigMap, Git)
2. Deploys a Registry API service for server discovery
3. Provides image validation
4. Manages automatic and manual synchronization policies

For detailed MCPRegistry documentation, see REGISTRY.md.

---
config:
  theme: dark
  look: classic
  layout: dagre
---
flowchart LR
 subgraph Kubernetes
   direction LR
    namespace
    User1["Client"]
 end
 subgraph namespace[namespace: toolhive-system]
    operator["POD: Operator"]
    sse
    streamable-http
    stdio
 end

 subgraph sse[SSE MCP Server Components]
    operator -- creates --> THVProxySSE[POD: ToolHive-Proxy] & TPSSSE[SVC: ToolHive-Proxy]
    THVProxySSE -- creates --> MCPServerSSE[POD: MCPServer] & MCPHeadlessSSE[SVC: MCPServer-HeadlessService]
    User1 -- HTTP/SSE --> TPSSSE
    TPSSSE -- HTTP/SSE --> THVProxySSE
    THVProxySSE -- HTTP/SSE --> MCPHeadlessSSE
    MCPHeadlessSSE -- HTTP/SSE --> MCPServerSSE
 end

 subgraph stdio[STDIO MCP Server Components]
    operator -- creates --> THVProxySTDIO[POD: ToolHive-Proxy] & TPSSTDIO[SVC: ToolHive-Proxy]
    THVProxySTDIO -- creates --> MCPServerSTDIO[POD: MCPServer]
    User1 -- HTTP/SSE --> TPSSTDIO
    TPSSTDIO -- HTTP/SSE --> THVProxySTDIO
    THVProxySTDIO -- Attaches/STDIO --> MCPServerSTDIO
 end

Installation

Running Operator Unit & Integration Tests

To run the basic operator-only tests (unit and integration), use the following command from the root of the project:

task operator:operator-test

This will run all Go tests in the operator codebase.

Running Operator E2E Tests

The task commands for the operator are designed to be run from the root of the project.

E2E Test Prerequisites

To run the Operator end-to-end (E2E) tests locally, ensure you have the following installed:

• Go
• Kind
• Kind Load Balancer
• Task
• Chainsaw (automatically installed by the Taskfile for local runs)

Steps

1. Set up the Kind cluster:

task operator:kind-setup

1. Run the Operator E2E tests:

task operator:operator-e2e-test

Note: The Taskfile will ensure Chainsaw is installed locally if not present. In CI, Chainsaw is installed via the GitHub Action.

Prerequisites

• Kubernetes cluster (v1.19+)
• kubectl configured to communicate with your cluster

Installing the Operator via Helm

1. Install the CRD:

helm upgrade -i toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds

1. Install the operator:

# Standard installation
helm upgrade -i <release_name> oci://ghcr.io/stacklok/toolhive/toolhive-operator --version=<version> -n toolhive-system --create-namespace

Usage

Creating an MCP Server

To create an MCP server, define an MCPServer resource and apply it to your cluster:

apiVersion: toolhive.stacklok.dev/v1alpha1
kind: MCPServer
metadata:
  name: fetch
spec:
  image: docker.io/mcp/fetch
  transport: stdio
  proxyPort: 8080
  mcpPort: 8080
  resources:
    limits:
      cpu: '100m'
      memory: '128Mi'
    requests:
      cpu: '50m'
      memory: '64Mi'

Apply this resource:

kubectl apply -f your-mcpserver.yaml

Using Secrets

For MCP servers that require authentication tokens or other secrets:

apiVersion: toolhive.stacklok.dev/v1alpha1
kind: MCPServer
metadata:
  name: github
  namespace: toolhive-system
spec:
  image: ghcr.io/github/github-mcp-server
  proxyPort: 8080
  mcpPort: 8080
  secrets:
    - name: github-token
      key: token
      targetEnvName: GITHUB_PERSONAL_ACCESS_TOKEN

First, create the secret:

kubectl create secret generic github-token -n toolhive-system --from-literal=token=<YOUR_GITHUB_TOKEN>

Then apply the MCPServer resource.

The secrets field has the following parameters:

• name: The name of the Kubernetes secret (required)
• key: The key in the secret itself (required)
• targetEnvName: The environment variable to be used when setting up the secret in the MCP server (optional). If left unspecified, it defaults to the key.

Checking MCP Server Status

To check the status of your MCP servers:

kubectl get mcpservers

This will show the status, URL, and age of each MCP server.

For more details about a specific MCP server:

kubectl describe mcpserver <name>

Configuration Reference

MCPServer Spec

Creating an MCP Registry

First, create a ConfigMap containing ToolHive registry data. The ConfigMap must be user-defined and is not managed by the operator:

# Create ConfigMap from existing registry data
kubectl create configmap my-registry-data --from-file registry.json=pkg/registry/data/registry.json -n toolhive-system

# Or create from your own registry file
kubectl create configmap my-registry-data --from-file registry.json=/path/to/your/registry.json -n toolhive-system

Then create the MCPRegistry resource that references the ConfigMap:

apiVersion: toolhive.stacklok.dev/v1alpha1
kind: MCPRegistry
metadata:
  name: my-registry
  namespace: toolhive-system
spec:
  displayName: 'My MCP Registry'
  source:
    type: configmap
    configMapRef:
      name: my-registry-data # References the user-created ConfigMap
      key: registry.json # Key in ConfigMap (required)
  syncPolicy:
    interval: '1h'

For complete MCPRegistry examples and documentation, see REGISTRY.md.

Examples

• MCPServer examples: examples/operator/mcp-servers/ directory
• MCPRegistry examples: examples/operator/mcp-registries/ directory

Development

Building the Operator

To build the operator:

go build -o bin/thv-operator cmd/thv-operator/main.go

Running Locally

For development, you can run the operator locally:

go run cmd/thv-operator/main.go

This will use your current kubeconfig to connect to the cluster.

Using Kubebuilder

This operator is scaffolded using Kubebuilder. If you want to make changes to the API or controller, you can use Kubebuilder commands to help you.

Prerequisites

• Install Kubebuilder: https://book.kubebuilder.io/quick-start.html#installation

Common Commands

Generate CRD manifests:

kubebuilder create api --group toolhive --version v1alpha1 --kind MCPServer

Update CRD manifests after changing API types:

task operator-manifests

Run the controller locally:

task operator-run

Project Structure

The Kubebuilder project structure is as follows:

• api/v1alpha1/: Contains the API definitions for the CRDs
• controllers/: Contains the reconciliation logic for the controllers
• config/: Contains the Kubernetes manifests for deploying the operator
• PROJECT: Kubebuilder project configuration file

For more information on Kubebuilder, see the Kubebuilder Book.