Virtual MCP Server
Introduction
Virtual MCP Server (vMCP) helps when one MCP server is no longer enough. It lets you combine multiple backend servers behind one endpoint so clients can use one connection instead of juggling separate URLs, authentication settings, and overlapping tool surfaces.
Within the ToolHive platform, vMCP is the gateway layer. It gives you unified tool access, centralized authentication, and multi-step workflows across multiple MCP backends.
For cluster deployments, vMCP runs as part of the ToolHive Kubernetes Operator. If you only want to evaluate aggregation locally, see run vMCP locally with the CLI.
Where to start
- Evaluating vMCP? Read Understanding Virtual MCP Server for the full picture of what it does and when it's the right fit.
- Ready to deploy? Follow the Quickstart to deploy your first vMCP through the Kubernetes Operator.
- Already running vMCP? Jump to Configuration or Authentication.
- Local testing only? Run vMCP locally with the CLI to aggregate a local ToolHive group without a cluster.
Contents
Introduction to vMCP
Virtual MCP Server (vMCP) aggregates multiple MCP servers into one endpoint for simpler client configuration.
Quickstart
Aggregate multiple MCP servers into a single endpoint using Virtual MCP Server.
Configure vMCP servers
How to configure a Virtual MCP Server for common scenarios.
Backend discovery modes
Choose between discovered and inline backend discovery for Virtual MCP Server.
Authentication
Configure client and backend authentication for vMCP.
Tool aggregation and conflict resolution
How vMCP aggregates tools from multiple backend MCP servers and resolves naming conflicts.
Composite tools and workflows
Create multi-step workflows that span multiple backend MCP servers.
Optimize tool discovery
Enable the optimizer in vMCP to reduce token usage and improve tool selection across aggregated backends.
Failure handling
Configure circuit breaker and partial failure modes to handle backend failures gracefully.
Telemetry and metrics
How to enable OpenTelemetry traces and metrics for Virtual MCP Server.
Audit logging
Configure audit logging for Virtual MCP Server to meet security compliance requirements and track MCP operations.
Scaling and performance
How to scale Virtual MCP Server deployments vertically and horizontally.
Run vMCP locally with the CLI
Run Virtual MCP Server locally with the thv vmcp command to aggregate a ToolHive group without Kubernetes.