ToolHive: running MCP servers in containers, from a laptop to Kubernetes

The problem ToolHive targets: MCP servers with no perimeter

An MCP server is a process your AI client talks to. That process usually needs credentials for whatever it reaches, it usually runs with your user's permissions, and it usually gets installed by whoever wants the tool that day. The README frames the consequence directly: shadow MCP use by developers, and a security team that has no audit logs and no identity enforcement. ToolHive's answer is to stop treating an MCP server as a local binary and treat it as a deployed workload. Every server runs in an isolated container with what the README calls a minimal permission file and no local credentials. That single decision is what makes the rest of the platform possible: if the server is a container, you can schedule it on Kubernetes, put a gateway in front of it, and log what it does. The audience follows from that. Individual developers get a CLI and a desktop UI; platform engineers get a Kubernetes operator; enterprises get a self-hosted registry and gateway so that, in the README's words, sensitive info is not processed by SaaS providers. If your MCP usage is one server in one editor and you control the machine, ToolHive is solving a problem you do not have yet.

Gateway, Registry, Runtime: how the pieces fit

The README describes a modular architecture with three named components and two interfaces, and the repository layout backs that up: cmd/ holds the entry points, pkg/ the implementation, deploy/ the Kubernetes manifests, and sdk/ a separate module for programmatic use. The Runtime is the part that actually deploys MCP servers, locally through Docker or Podman, remotely through Kubernetes, or by proxying an MCP server that already exists somewhere else. The Registry Server curates which servers are available; the README points to a separate repository, stacklok/toolhive-registry-server, and notes integration with the official MCP registry plus custom entries, grouping by role, provenance verification and signing. The Gateway is the inbound path: it defines endpoints, applies access policy, integrates with an identity provider over OIDC or OAuth, and can orchestrate several tools into what the README calls a virtual MCP with a deterministic workflow engine. The documented data flow is a loop. Admins curate servers and policy in the Registry. Users pick and run them through the UI or CLI. The Runtime deploys them. The Gateway handles inbound traffic and enforces policy. Two details in the dependency list are worth noting because they indicate how policy is expressed: the go.mod requires cel.dev/cel-go and github.com/cedar-policy/cedar-go, and the examples directory contains examples/authz-config.json, examples/authz-httpv1-config.yaml and examples/authz-config-with-entities.json. Authorization here is a policy language, not a checkbox.

Installing ToolHive and running a first MCP server

The README does not inline install commands. It routes downloads through https://stacklok.com/download/ and keeps three quickstarts in the documentation: one for the desktop app, one for the CLI, and one for the Kubernetes operator. The CLI quickstart is the shortest path to something running, so start there. The README states that local MCP servers run via Docker or Podman, so one of the two must be running on the machine before ToolHive can deploy anything. The repository also ships example manifests that show the shape of a configured server. examples/mcpserver-with-audit.yaml is the one to read first if audit logging is why you are here, and examples/vmcp-config.yaml shows how a virtual MCP is declared for the gateway. Both are files in the repository you can open directly rather than generated output. For a Kubernetes deployment, the operator quickstart in the docs is the entry point, and deploy/ in the repository holds the manifests it installs. The README does not state the cluster version or prerequisites inline, so read the quickstart before assuming your cluster qualifies. For connecting a client, the README says ToolHive connects managed servers to compatible AI clients and names Claude Code, Cursor, GitHub Copilot, Claude Desktop, VS Code and VS Code Server.

Token savings and tool filtering are the claims to test yourself

The README says ToolHive uses semantic tool search to reduce token usage by up to 85 percent, and separately that the Gateway can customize and filter tools and descriptions to improve performance and reduce token usage. Both statements are about the same underlying mechanism: an MCP client that sees fewer, more relevant tool definitions sends a smaller prompt. That mechanism is real and the direction of the effect is not in question. The number is. An 85 percent reduction depends on how many tools you expose, how well the semantic search ranks them for a given request, and what your client does with the filtered list. The README does not publish the configuration under which the figure was measured, and no benchmark is described. Treat it as a ceiling for a favourable setup, not a planning figure. The practical way to check is to run the same workload with and without the Gateway's filtering and compare the token counts your client reports. If you are evaluating ToolHive mainly for cost, that comparison is the evaluation.

Where ToolHive is the wrong choice

The container-per-server model is the source of both ToolHive's guarantees and its friction. It assumes a working container runtime on every machine where MCP servers run. On a locked-down corporate laptop where Docker Desktop is not permitted and Podman is not installed, the local path does not exist, and the Kubernetes path assumes you have a cluster and the authority to deploy an operator into it. The README does not document a fallback for running an MCP server without a container runtime. A second limitation is documentation surface area. The desktop UI is a separate repository, stacklok/toolhive-studio, and the Registry Server is likewise separate, so the main README describes capabilities without describing their internals. The README also does not document rollback, what happens to running servers when the CLI or operator is upgraded, or how a failed deployment is cleaned up. Those are exactly the questions that decide whether a platform tool is safe to put in front of a team, and they are answered, if at all, in the docs rather than here. Finally, if your requirement is a single MCP server for a single developer on a machine they fully control, the registry, gateway and policy layers are unused weight. Running the server directly is simpler and you give up nothing you were relying on.

ToolHive compared with running MCP servers directly or through a hosted broker

The realistic alternative is not another platform of the same shape. It is running MCP servers yourself: install the server, point your client's configuration at it, manage credentials by hand. The difference is where policy lives. In the direct approach, policy is whatever your client and your operating system enforce, which is to say nothing specific to MCP. In ToolHive, policy is expressed in the Gateway and Registry, with CEL and Cedar both present in the dependency list and authorization examples in the repository, and enforcement happens on inbound requests. You gain auditability and a place to change rules centrally; you take on a control plane to operate. The second alternative is a hosted MCP broker, where a vendor runs the servers and you connect your client to their endpoint. That removes operational work and, for many teams, removes the option entirely, because the README's enterprise pitch is precisely that compliance requirements prohibit sensitive information from being processed by SaaS providers. ToolHive's position is self-hosting: the registry, the gateway and the runtime all run on infrastructure you control. The trade is that you now own upgrades, identity provider integration and observability, which the README lists as OpenTelemetry and Prometheus rather than as a managed service.

Maintenance, licensing and what an upgrade costs you

The repository is not archived and the last push was on 2026-09-10, the same day v0.48.0 was released; v0.47.1 and v0.47.0 landed two days earlier. That cadence, three releases in three days, is a signal about how the project is being developed rather than a promise about stability. It means the version you pin matters: a platform tool that releases this often will change between minor versions, and the README does not describe an upgrade procedure or a compatibility policy for the CLI, the operator or the registry API. The licence is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant; it also means that if you modify the code and distribute it, you carry the notice and attribution obligations that come with the licence. That is a general property of Apache-2.0, not legal advice, and anything about your own distribution obligations belongs with your counsel. The commercial boundary is visible in the README: Stacklok Enterprise is presented as added capabilities on top of the open source platform, with a linked comparison page. The open source project is the whole of what this repository contains, and the README is explicit that the platform can be piloted entirely self-hosted. Budget for the operational cost of running the registry and gateway, not just for the licence.

Editorial conclusion

Adopt ToolHive if you already run Docker or Podman on developer machines and Kubernetes in production, and you need MCP server access to be auditable and self-hosted rather than brokered through a SaaS control plane. Do not adopt it if you only need one local MCP server in a single client: the container wrapper, registry and gateway are overhead you will not use. Before committing, verify that the CLI quickstart in the docs matches the release you install, check whether your clients are among the ones the README names (Claude Code, Cursor, GitHub Copilot, Claude Desktop, VS Code), and confirm what your Kubernetes cluster must already provide, since the README links to the operator quickstart rather than stating prerequisites inline.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. stacklok/toolhive on GitHub