toolhive

ToolHive manages the complete lifecycle of MCP servers (startup, shutdown, scaling, health monitoring) through a container runtime abstraction layer that supports multiple execution environments (Docker, Kubernetes, local processes). The system uses a RunConfig-based approach to define workload specifications, with middleware architecture enabling request-level policy enforcement and credential injection before tool execution. This abstraction decouples MCP server definitions from their deployment target, allowing the same server configuration to run locally during development or in Kubernetes clusters in production.

ToolHive maintains a centralized registry of available MCP servers with semantic search capabilities for tool discovery. The registry stores server metadata (capabilities, schemas, permissions) and uses semantic indexing to match user requests to appropriate tools based on intent rather than exact keyword matching. The system supports both local registry operations and integration with external registries, enabling organizations to curate approved tools while preventing unauthorized tool execution through permission profiles.

ToolHive integrates supply chain security controls for container images used by MCP servers, including image scanning for vulnerabilities and support for image attestation and signing verification. The system can validate that container images come from trusted sources and have not been tampered with before deploying them as MCP servers. This enables organizations to enforce security policies requiring only approved, scanned, and signed container images to be used for MCP server execution.

ToolHive provides comprehensive observability through structured logging of all operations, metrics collection for performance monitoring, and integration with standard observability platforms. The system logs request/response data, policy decisions, authentication events, and workload lifecycle events in structured JSON format suitable for log aggregation and analysis. Metrics are exposed in Prometheus format for integration with monitoring systems, enabling operators to track MCP server performance, request latency, error rates, and resource utilization.

ToolHive implements permission profiles that define granular access control policies mapping identities (users, applications, roles) to specific MCP servers and tools they can invoke. Permission profiles support multiple matching strategies (exact match, pattern matching, semantic matching) and can include conditions based on request context (time of day, source IP, etc.). The system evaluates permission profiles at request time, enabling dynamic access control decisions without requiring static role assignments.

ToolHive includes a skills system that enables extending platform capabilities through composable skill definitions. Skills are reusable components that encapsulate specific functionality (e.g., code review assistance, story implementation, PR splitting) and can be invoked through the platform. The skills system uses a declarative SKILL.md format for defining skill metadata, inputs, outputs, and implementation details. This enables platform teams to build and share custom capabilities without modifying core ToolHive code.

ToolHive enforces identity and access policies at the request level through an authentication and authorization system that validates caller identity, applies organizational policies, and injects credentials into MCP server execution contexts. The system uses a middleware architecture to intercept requests before tool execution, checking permissions against defined profiles and injecting secrets from a secure secrets management system. This enables fine-grained access control where different users or applications can invoke the same MCP server with different permission levels and credential sets.

ToolHive provides a secrets management system that securely stores and injects credentials into MCP server execution contexts at request time. The system integrates with external secret stores (Redis, Kubernetes Secrets) and uses a credential injection middleware to populate environment variables or configuration files for MCP servers without exposing secrets in logs or configurations. Secrets are retrieved on-demand during request processing and never persisted in workload definitions, reducing the attack surface for credential compromise.

ToolHive implements a Virtual MCP Server (vMCP) abstraction that allows multiple physical MCP servers to be composed into a single logical server interface. This enables tool aggregation where requests to a virtual server are routed to appropriate backend servers based on tool schemas and permissions. The vMCP system uses a middleware-based routing layer that matches incoming tool requests to backend servers, handles request/response transformation, and applies policies at the composition boundary.

ToolHive provides a Kubernetes operator that enables declarative management of MCP servers through Custom Resource Definitions (CRDs). The operator watches for MCP server resource definitions in Kubernetes and automatically creates, updates, and scales corresponding workloads. It integrates with Kubernetes' native resource management, enabling MCP servers to be managed using standard kubectl commands and GitOps workflows. The operator handles workload lifecycle events, health monitoring, and integration with Kubernetes networking and storage systems.

ToolHive abstracts MCP server communication through a transport protocol layer that supports multiple transport schemes (stdio, HTTP, WebSocket, gRPC) without requiring changes to server logic. The system uses a protocol scheme abstraction that maps incoming requests to appropriate transport handlers, enabling clients to communicate with MCP servers via different protocols depending on deployment context. This allows the same MCP server implementation to be accessed via stdio locally, HTTP in cloud environments, or gRPC for high-performance scenarios.

ToolHive provides a comprehensive CLI interface (thv command) for managing MCP server workloads with configuration builders that generate RunConfig specifications from command-line flags and interactive prompts. The CLI supports commands like `thv run` for starting servers, `thv proxy` for gateway operations, `thv registry` for server discovery, and `thv client` for client registration. The configuration builder system translates CLI inputs into structured RunConfig YAML/JSON, enabling users to define complex workload specifications without manually writing configuration files.

ToolHive exposes a comprehensive REST API for programmatic management of MCP server workloads, registry operations, client management, and configuration. The API follows standard REST conventions with JSON request/response bodies and includes endpoints for workload lifecycle operations (create, read, update, delete, list), registry queries, client registration, and health checks. The API is documented via OpenAPI/Swagger specifications and supports authentication through bearer tokens or custom auth schemes, enabling integration with external orchestration systems and CI/CD pipelines.

ToolHive implements a middleware architecture that intercepts requests before MCP server execution, enabling cross-cutting concerns like authentication, authorization, credential injection, logging, and policy enforcement. The middleware chain is composable, allowing operators to define the order and combination of middleware components. Each middleware can inspect and modify requests, apply policies, inject credentials, and log events without requiring changes to MCP server implementations. This architecture enables flexible policy enforcement and observability without coupling policies to server logic.