Skip to main content

Frequently asked questions

General questions​

What is ToolHive?​

ToolHive is an open source platform for running, securing, and managing Model Context Protocol (MCP) servers and agent skills. It runs MCP servers in isolated containers and gives you a desktop app, command-line tool, and Kubernetes operator to manage them, plus a gateway and registry server for team and enterprise deployments.

What is the Model Context Protocol (MCP)?​

MCP is an open protocol that lets AI applications connect to external data sources and tools in a standard way. It gives AI models access to real-world context like APIs, source code repositories, databases, and other systems. Think of it as a bridge between AI models and the systems where your data and applications live. For more background, see the MCP primer.

Do I need to know how to code to use ToolHive?​

No. The ToolHive desktop app doesn't require coding knowledge. Some MCP servers need configuration or secrets like API keys that you'll set up through the UI. The CLI is more technical but is fully documented if you prefer a terminal workflow.

Is ToolHive free to use?​

Yes. ToolHive is open source under the Apache 2.0 license and free to use, with the source code on GitHub. Stacklok also offers a paid commercial distribution called Stacklok Enterprise; see "What's the difference between ToolHive and Stacklok Enterprise?" below.

What's the difference between ToolHive and Stacklok Enterprise?​

ToolHive is the open source project: a complete platform for running MCP servers locally or in Kubernetes, free to use, with community support through GitHub and Discord. It's the right starting point for individual developers and teams evaluating MCP.

Stacklok Enterprise is a hardened, semantically versioned distribution of ToolHive built for production use. It adds turnkey identity provider integrations (Okta, Entra ID), built-in functionality for day-2 and day-3 operations, backported security patches, hardened container images, an enterprise cloud UI, and SLA-backed support. It's self-hosted, so your data stays in your environment.

If you're running MCP in production at organizational scale, need SSO and governance, or have compliance requirements, Stacklok Enterprise is the supported path.

Can I use the ToolHive UI and CLI together?​

Yes, but the desktop app manages the CLI for you. When you install the UI, it creates a symlink to its bundled CLI and configures your PATH so that running thv from your terminal uses the UI-managed version.

If you also have a standalone CLI installed (via Homebrew, WinGet, or a manual install), it conflicts with the UI-managed version and shows an error. Uninstall the standalone version to resolve this.

For details, see the CLI access guide and CLI conflict resolution.

ToolHive components​

What is the Virtual MCP Server (vMCP)?​

The Virtual MCP Server (vMCP) is ToolHive's MCP gateway. It aggregates multiple backend MCP servers behind a single endpoint so clients connect once instead of juggling many URLs, credentials, and overlapping tool surfaces. vMCP also centralizes authentication, authorization, and tool filtering, and supports multi-step composite workflows across backends.

vMCP runs as part of the ToolHive Kubernetes Operator for cluster deployments. A local CLI version is available for evaluating aggregation on your machine.

What's the difference between the built-in registry and the Registry Server?​

The built-in registry is the default catalog of vetted MCP servers shipped with the ToolHive UI and CLI. Browse it from the Registry tab in the UI or run thv registry list in the CLI. No deployment is required.

The ToolHive Registry Server is a separate component you deploy yourself to host your own catalog of MCP servers and skills. Use it when you want to curate a private or team-specific registry, publish internal MCP servers, aggregate entries from multiple sources, or apply authentication and authorization to registry access. It implements the official MCP Registry API.

What are skills?​

Skills are reusable, versioned bundles of instructions, prompts, and configuration that teach an AI agent how to perform a specific task. Where MCP servers provide the raw tools an agent can call, skills provide the knowledge of when, why, and how to use those tools together.

ToolHive lets you run skills locally, manage them from the UI or CLI, and publish them through the Registry Server alongside your MCP servers. Skills follow the open Agent Skills specification supported by clients like Claude Code, GitHub Copilot, and Cursor.

Using MCP servers​

How do I find available MCP servers?​

ToolHive includes a curated registry of vetted MCP servers. Browse it from the Registry tab in the UI or run thv registry list in the CLI.

What MCP servers are available?​

The registry includes servers for common use cases like web content retrieval with the GoFetch MCP server, and for popular services and platforms such as:

  • Atlassian - access Jira and Confluence
  • AWS Documentation - query AWS service documentation
  • GitHub - access repositories, issues, and pull requests
  • Kubernetes - interact with Kubernetes clusters via the MKP MCP server
  • MongoDB, PostgreSQL, Redis - connect to databases
  • Notion - connect to Notion workspaces
  • And many more

Don't see what you need? See How do I get my MCP server added to the ToolHive registry? below.

Can I run MCP servers that aren't in the registry?​

Yes. You can run any MCP server from a container image or source package, even if it's not in the registry. Provide the image name or package details when starting the server through the CLI or UI. See the custom MCP server sections in the UI guide and the CLI guide.

The Kubernetes Operator also supports custom MCP servers packaged as container images.

ToolHive can also proxy remote (hosted) MCP servers; see Does ToolHive support remote MCP servers? below.

tip

You can use the CLI to run a custom MCP server from a source package once, then export the resulting container image to your registry or Kubernetes cluster to use it with the operator.

Does ToolHive support remote MCP servers?​

Yes. ToolHive can proxy remote (hosted) MCP servers so you can manage them alongside locally-run servers using the same configuration, authentication, and observability. ToolHive supports both Server-Sent Events (SSE) and Streamable HTTP transports for remote servers. For Kubernetes, see Remote MCP server proxying.

Which AI clients work with ToolHive?​

ToolHive works with any AI client that supports MCP. Tested clients include:

  • Coding assistants like GitHub Copilot, Cursor, Windsurf, Claude Code, OpenAI Codex, Google Antigravity, Cline, Goose, and Zed, available as IDE extensions, terminal CLIs, and native apps
  • Desktop AI apps like Claude Desktop, ChatGPT Desktop, and LM Studio
  • Agent frameworks like PydanticAI

Many clients support automatic configuration so you can connect without manual setup. See the client compatibility reference for the full list, minimum versions, and per-client notes.

What container runtimes does ToolHive support?​

For local use (UI and CLI), ToolHive supports:

  • Docker / Docker Desktop
  • Podman / Podman Desktop
  • Colima with the Docker runtime
  • Rancher Desktop with the dockerd/moby runtime (experimental)

For cluster deployments, the ToolHive Kubernetes Operator runs MCP servers as standard Kubernetes pods using whatever container runtime your cluster is configured with.

How do I get my MCP server added to the ToolHive registry?​

The registry has inclusion criteria such as being open source, following good security practices, and maintaining code quality. Review the criteria and submit your server for consideration.

Privacy and data collection​

Does ToolHive collect any data?​

ToolHive collects anonymous usage metrics to help improve the product. These metrics include only tool call counts and are completely anonymous. No personal information, user identifiers, or sensitive data is collected.

The metrics collection:

  • Is enabled by default
  • Only tracks the number of tool calls
  • Uses a randomly generated instance ID (not tied to your identity)
  • Is automatically disabled in CI environments
  • Can be easily disabled

How do I disable usage metrics?​

You can opt out of usage metrics collection in two ways:

Option 1: Persistent configuration (recommended)

Use the ToolHive CLI to disable metrics permanently:

thv config usage-metrics disable

Option 2: Environment variable

Set an environment variable to disable metrics for the current session:

export TOOLHIVE_USAGE_METRICS_ENABLED=false

Once you opt out, ToolHive stops collecting and sending usage metrics. You need to restart any running servers for the change to take effect.

Security and permissions​

Is it safe to run MCP servers?​

ToolHive runs MCP servers in isolated containers with minimal default permissions. Each server runs in its own container with restricted access to your system and network.

tip

For extra security, review the permission profiles and network isolation options before running new or untrusted MCP servers.

How does ToolHive handle secrets like API keys?​

ToolHive provides secure secrets management with several backend options:

  • A built-in encrypted store that uses your operating system's keyring to protect a local secrets file
  • 1Password integration for retrieving secrets from a 1Password vault
  • HashiCorp Vault integration for Kubernetes deployments

Secrets are passed to MCP servers as environment variables and never appear in plaintext in configuration files. See the secrets management guides for the CLI, UI, and the Vault integration for Kubernetes.

Can I control what an MCP server can access?​

Yes. ToolHive uses permission profiles to control:

  • File system access - which directories the server can read or write
  • Network access - which hosts and ports the server can connect to

You can use built-in profiles or create custom ones for specific security requirements.

What's network isolation and when should I use it?​

Network isolation creates a secure network architecture that filters all outbound connections from MCP servers. Use the --isolate-network flag when running servers that need strict network controls, especially in enterprise environments.

Does ToolHive integrate with my identity provider for SSO?​

Yes. ToolHive supports OIDC-based authentication for MCP servers, so you can front your servers with any OIDC-compliant identity provider and use Cedar policies for fine-grained authorization. For details, see Authentication and authorization and the auth guides for the CLI and Kubernetes Operator.

Stacklok Enterprise adds turnkey integrations for Okta and Entra ID, including IdP group to ToolHive role mapping and canonical policy packs.

Can I see who called what tools?​

Yes. ToolHive includes built-in OpenTelemetry instrumentation that captures detailed traces and metrics for every MCP request and tool call, plus audit logging for compliance and security review. See Observability and the OpenTelemetry integration guide for the full picture.

Operations and enterprise​

Can I use ToolHive in my organization?​

Yes. ToolHive is built to scale from a single developer's machine to enterprise deployments. Small teams can run the CLI or desktop app locally; larger deployments use the Kubernetes Operator for centralized management, the vMCP gateway for unified access, and the Registry Server for a governed catalog.

If you need turnkey IdP integration, hardened images, semantic versioning, backported security patches, or SLA-backed support, see Stacklok Enterprise.

How do I deploy ToolHive in Kubernetes?​

Use the ToolHive Kubernetes Operator to deploy and manage MCP servers as Kubernetes resources. See the Kubernetes guides for detailed instructions, including a quickstart, authentication setup, and production patterns like rate limiting and Redis-backed session storage.

Can I use ToolHive behind a corporate firewall?​

Yes. ToolHive supports corporate environments with:

  • Custom CA certificate configuration for TLS inspection
  • Network isolation and permission profiles
  • Integration with secret management systems

Getting help​

Where can I get help if I'm stuck?​

  • Documentation - check the comprehensive guides and reference documentation
  • Lok, our AI assistant - chat with Lok using the widget on this site for quick answers
  • GitHub Issues - report bugs or request features on the ToolHive GitHub repository
  • Discord community - join the Stacklok Discord for community support
  • Troubleshooting sections - each guide includes troubleshooting tips for common issues

How do I report a bug or request a feature?​

Open an issue in the appropriate GitHub repository:

Is there a community I can join?​

Yes. Join the Stacklok Discord to connect with other ToolHive users, ask questions, and share your experiences. There's a dedicated #toolhive-developers channel for technical discussions.