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

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

Learn how to deploy the ToolHive Kubernetes Operator and use it to manage MCP servers in a Kubernetes cluster.

📄️ Deploy the operator

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

📄️ Run MCP servers in Kubernetes

How to deploy MCP servers in Kubernetes using the ToolHive operator

📄️ Proxy remote MCP servers

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

📄️ Connect clients to MCP servers

Learn how to connect clients to your Kubernetes-hosted MCP servers in ToolHive.

📄️ 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.

📄️ 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

How to enable OpenTelemetry (metrics and traces) and Prometheus instrumentation for ToolHive MCP servers inside of Kubernetes using the ToolHive Operator

📄️ Audit logging

Configure and manage logging for ToolHive in Kubernetes environments

📄️ CRD Reference

ToolHive Kubernetes Operator Custom Resource Definitions (CRDs) reference.