Using the ToolHive Kubernetes Operator

Introduction

The ToolHive Kubernetes Operator manages MCP servers in Kubernetes clusters. You define MCP servers as Kubernetes custom resources and the operator automates their deployment, proxying, and lifecycle management. The operator supports several primary resource types:

• MCPServer: run a containerized MCP server inside your cluster
• MCPRemoteProxy: proxy an MCP server hosted outside your cluster
• MCPServerEntry: register a remote MCP server as a catalog entry for vMCP discovery
• VirtualMCPServer: aggregate and optimize multiple servers behind a single endpoint

Beyond managing MCP servers, the operator can deploy ToolHive Registry Server instances via MCPRegistry resources, enabling automatic discovery of cluster-hosted MCP servers.

Where to start

• New to ToolHive on Kubernetes? Start with the Quickstart to deploy your first MCP server on a local kind cluster.
• Operator already installed? Jump to Run MCP servers, Proxy remote MCP servers, or set up a Virtual MCP Server.
• Not sure which resource type to use? See the decision guide in the Introduction.

Contents

📄️Introduction

How to manage MCP servers in Kubernetes with the ToolHive Kubernetes Operator

📄️Quickstart

Deploy the ToolHive Kubernetes Operator and run your first MCP server in a cluster.

📄️Deploy the operator

How to deploy the ToolHive operator in a Kubernetes cluster using Helm or kubectl

📄️Run MCP servers in Kubernetes

Deploy and configure MCP servers in Kubernetes using MCPServer custom resources.

📄️Proxy remote MCP servers

How to deploy proxies for remote MCP servers in Kubernetes using the ToolHive operator

📄️Declare remote MCP server entries

Register remote MCP servers as lightweight catalog entries for vMCP discovery without deploying proxy infrastructure.

📄️Connect clients to MCP servers

Connect AI clients to Kubernetes-hosted MCP servers managed by the ToolHive operator.

📄️Customize tools

Filter and rename MCP server tools using the MCPToolConfig CRD and toolConfigRef.

📄️Authentication and authorization

How to set up authentication and authorization for MCP servers in Kubernetes using the ToolHive Operator.

📄️Redis session storage

Deploy Redis Sentinel for the ToolHive embedded auth server, or a standalone Redis instance for MCPServer and VirtualMCPServer horizontal scaling.

📄️Rate limiting

Configure per-user and shared rate limits on MCPServer resources to prevent noisy neighbors and protect downstream services.

📄️Configure token exchange for backend authentication

How to set up token exchange so MCP servers can authenticate to backend services in Kubernetes using the ToolHive Operator.

📄️Telemetry and metrics

Enable OpenTelemetry and Prometheus metrics for ToolHive MCP servers running in Kubernetes.

📄️Audit logging

Configure log levels, formats, and output for the ToolHive operator and MCP servers in Kubernetes.

📄️Migrate to v1beta1

Breaking changes and migration steps for the CRD API stabilization track from v0.15.0 through v0.21.0

📄️CRD Reference

ToolHive Kubernetes Operator Custom Resource Definitions (CRDs) reference.