Introduction
The ToolHive Kubernetes Operator manages MCP servers in Kubernetes clusters. It lets you define MCP servers as Kubernetes resources and automates their deployment and management.
See the ToolHive Operator quickstart tutorial to get started quickly using a local kind cluster. Try it out and share your feedback!
How the operator works
The operator introduces new Custom Resource Definitions (CRDs) into your
Kubernetes cluster. The primary CRDs for MCP server workloads are MCPServer,
which represents a single MCP server running in Kubernetes, MCPRemoteProxy,
which represents an MCP server running outside the cluster that is proxied by
ToolHive, and VirtualMCPServer, which represents a virtual MCP server gateway
that aggregates multiple backend MCP servers.
When you create an MCPServer resource, the operator automatically:
- Creates a Deployment to run the MCP server
- Sets up a Service to expose the MCP server
- Configures the appropriate permissions and settings
- Manages the lifecycle of the MCP server
MCPRemoteProxy and VirtualMCPServer resources work similarly, with the
operator managing a proxy pod that connects to remote MCP servers or aggregates
multiple backends, respectively.
The diagram shows how clients connect to MCP servers through a standard Ingress or Gateway. To learn how to expose your MCP servers and connect clients, see Connect clients to MCP servers.
Which resource type should I use?
The operator introduces three resource types for MCP workloads. Choose based on where your MCP server runs and how many servers you need to manage:
| Resource | Use when |
|---|---|
| MCPServer | Running an MCP server as a container inside your cluster |
| MCPRemoteProxy | Connecting to an MCP server hosted outside your cluster (SaaS tools, external APIs, remote endpoints) |
| VirtualMCPServer | Aggregating multiple MCPServer and/or MCPRemoteProxy resources behind a single endpoint for a team or application |
Most teams start with MCPServer for container-based servers, add
MCPRemoteProxy for external SaaS tools, and graduate to VirtualMCPServer
when managing five or more servers or needing centralized authentication.
Installation
Deploy the ToolHive operator in your Kubernetes cluster.
Once the operator is installed, you can create and manage MCP servers: