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 three resource types:

• MCPServer — run a containerized MCP server inside your cluster
• MCPRemoteProxy — proxy an MCP server hosted outside your cluster
• VirtualMCPServer — aggregate 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 Sentinel session storage

How to deploy Redis Sentinel and configure persistent session storage for the ToolHive embedded authorization server and 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.

📄️CRD Reference

ToolHive Kubernetes Operator Custom Resource Definitions (CRDs) reference.