ToolHive: a Go platform that puts every MCP server in a container

The problem ToolHive targets: MCP servers running outside anyone's control

An MCP server is a process that an AI client launches and talks to. The README's framing of the problem is that this arrangement spreads. It names shadow MCP use by developers as the thing platform teams want to stop, and it lists three audiences: developers who want to run servers with less credential exposure, platform engineers who want MCP on existing Kubernetes infrastructure, and enterprises whose compliance rules rule out SaaS handling of sensitive data. Those are three different buyers with three different budgets, and the README presents them as one table. The common thread is that ToolHive treats an MCP server as a workload to be deployed, not as a config snippet to paste into a client. The README claims the platform is 'trusted by developers and enterprises' and that it runs every server 'in an isolated container', with identity and access policy enforced per request 'when configured with an authentication source'. That qualifier matters: policy enforcement is conditional on configuration, not automatic.

Gateway, registry, runtime, interfaces: how the four pieces divide the work

The README describes a modular architecture with four named components. The runtime is the part that actually executes things: it deploys MCP servers locally via Docker or Podman, in a Kubernetes cluster via an operator, or proxies remote MCP servers for unified management. The gateway is the inbound path. It exposes dedicated endpoints, can orchestrate several tools into what the README calls a virtual MCP with a deterministic workflow engine, applies access policies, integrates with an IdP over OIDC/OAuth, and can filter tool descriptions to cut token usage. The registry, which lives in a separate repository (stacklok/toolhive-registry-server), is a curated catalog that can pull from the official MCP registry or hold custom servers, grouped by role or use case, with provenance verification and signing described as built-in controls. The interfaces are the CLI and the desktop UI in stacklok/toolhive-studio. The README's own four-step flow is admins curate in the registry, users discover and run through UI or CLI, the runtime deploys, and the gateway handles inbound traffic. That is a clean separation on paper. The interesting design choice is the deterministic workflow engine inside the gateway: composing multiple MCP servers into one virtual server with a fixed workflow is a different proposition from letting a model choose tools at runtime, and the README does not explain how the workflow is defined or what happens when a step fails.

Container isolation and the secrets model

The isolation claim is concrete in one respect: ToolHive wraps every MCP server in a container with what the README calls a minimal permission file, and states that no local credentials are used. That is the mechanism behind the security pitch. If an MCP server runs in its own container with a restricted permission set, a compromised or badly written server does not get the developer's home directory or their existing cloud credentials. The README also mentions managing encrypted secrets and controlling network isolation with local tooling. What it does not give in the material available here is the permission file format, the default network policy, or how secrets are injected into a container at run time. Those are the details that decide whether the isolation is meaningful in practice, and they sit behind the documentation links rather than in the README. Treat the isolation claim as a design intent to verify, not a guarantee you can read off the repository front page.

Getting it running: download, then CLI or UI

The README points installation at stacklok.com/download/ and splits the quickstarts three ways: docs.stacklok.com/toolhive/guides-ui/quickstart for the desktop app, guides-cli/quickstart for the terminal, and guides-k8s/quickstart for the Kubernetes operator. The local runtime requires Docker or Podman, since the README lists those as the two local execution paths. The README gives no raw install commands, no example config keys and no sample registry entry in the text available here, so any command you write into a runbook has to come from those quickstart pages rather than from the repository README. That is a real friction point for a platform team evaluating the project: the front page sells the outcome, and the operational detail is one hop away. The one command-adjacent claim the README does make is that you can connect Claude Code, Cursor or GitHub Copilot to MCP servers 'with a single click or command', which describes the UI and CLI respectively but does not show the invocation.

The token-saving claim needs its own evaluation

The README states that semantic tool search reduces 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. Two mechanisms are being described under one benefit, and the 85 percent figure is an upper bound with no stated workload, model, or tool count attached. Filtering tool descriptions and searching over tools semantically both change what the model sees, which can change which tool it picks. A reduction in tokens is not automatically a reduction in task success. If you evaluate ToolHive on this claim, measure it against your own tool set and your own prompts; the README does not supply the conditions under which the number was produced, and the material here does not say whether the semantic search runs locally or through a hosted model.

Where ToolHive is the wrong tool

Two cases stand out. First, a single developer running one or two MCP servers on a laptop. The container runtime, the client connection, and the server itself are the whole job at that scale; the gateway, registry and operator are components you would install and then not use, and each one is something else to keep patched. Second, teams whose compliance regime forbids container runtimes or whose servers must run as native processes with direct filesystem access. The README's entire security story rests on container isolation, so a workload that cannot be containerised gets none of the benefit and all of the orchestration overhead. There is also a scope question the README raises rather than answers: it says identity and access policy are enforced per request 'when configured with an authentication source'. If you run the local CLI path without wiring an IdP, you are running containers with a permission file and no per-request policy, which is a different product from the one the enterprise column describes.

Alternatives and the actual difference in approach

The most direct comparison is the plain MCP client configuration that every AI client already supports: you add a server entry to Claude Desktop, Cursor or VS Code and the client launches the process. That approach has no container boundary, no central registry, no gateway and no audit log, but it also has no components to operate, and it is what most individual developers are doing today. ToolHive's difference is that it moves the server out of the client's process tree and into a managed runtime, then puts a gateway in front of it. A second comparison is running MCP servers as ordinary Kubernetes deployments without an operator. You would get scheduling, resource limits and network policy from Kubernetes itself, but you would hand-write the deployment, service and secret manifests for each server, and you would have no registry, no tool filtering and no virtual MCP composition. ToolHive's operator exists to remove that manifest work; whether it does so without constraining you depends on the CRDs, which the README does not show. The README also positions Stacklok Enterprise as the commercial tier, with a comparison page at docs.stacklok.com/toolhive/enterprise, so the open source build is deliberately a subset of the vendor's offering.

Licence, maintenance and what to check before adopting

ToolHive is Apache-2.0, which permits commercial use, modification and redistribution provided you preserve the licence and notices. The README does not describe a contributor licence agreement, a governance model or a trademark policy, so the Apache-2.0 terms are what you have to work with. On maintenance, the repository shows a release cadence of roughly two to three versions per week across v0.47.0, v0.47.1 and v0.48.0 in September 2026, and the project is not archived. A version number still below 1.0 after that many releases is the honest signal here: the API surface, the CLI flags and the operator CRDs can still change between minor versions, so pin a version and read the release notes before upgrading rather than tracking main. The registry lives in a separate repository, which means two upgrade tracks to coordinate. Before you commit, check three things in the docs: which authentication sources the gateway accepts for OIDC/OAuth, what the operator's custom resources look like in the guides-k8s quickstart, and what the permission file actually grants by default. Those three answers determine whether ToolHive fits your environment or merely looks like it does.

Editorial conclusion

Adopt ToolHive if you already run Kubernetes or Docker and need MCP servers under an existing IdP and audit trail, rather than each developer wiring servers into a desktop client by hand. Do not adopt it if you only need one local MCP server for one developer: the container runtime plus a client is enough and the gateway and registry add moving parts you would not use. Before committing, verify two things against the docs: which authentication sources the gateway supports for OIDC/OAuth, and whether the Kubernetes operator path or the local Docker/Podman path matches your deployment target, because the README treats them as one product while the quickstart guides are separate.

Official sources

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