# Introduction to vMCP

## What is vMCP?[​](#what-is-vmcp "Direct link to What is vMCP?")

Virtual MCP Server (vMCP) is a ToolHive feature that acts as an aggregation proxy, consolidating multiple backend MCP servers into a single unified interface. Instead of configuring clients to connect to each MCP server individually, you connect once to vMCP and access all backend tools through a single endpoint.

You can run vMCP two ways:

* **On Kubernetes** through the `VirtualMCPServer` custom resource managed by the ToolHive operator. This is the recommended option for shared, multi-tenant, or production deployments.
* **Locally from the CLI** with the `thv vmcp` command, which aggregates a local [ToolHive group](/toolhive/concepts/groups.md) without a cluster. See [Run vMCP locally with the CLI](/toolhive/guides-vmcp/local-cli.md).

The underlying aggregation, tool routing, and optimizer capabilities are the same in both modes. The rest of this page focuses on the Kubernetes deployment model. For individual development or local testing without a cluster, see [Run vMCP locally with the CLI](/toolhive/guides-vmcp/local-cli.md).

vMCP supports three types of backends:

* **MCPServer**: Container-based MCP servers running in your cluster
* **MCPRemoteProxy**: Proxies to external remote MCP servers (such as Notion, analytics platforms, or other SaaS MCP endpoints)
* **MCPServerEntry**: Zero-infrastructure catalog entries that point vMCP at a remote MCP server without deploying a proxy pod

vMCP aggregates these backend types and authenticates to each one using its configured outgoing authentication strategy. See [Proxy remote MCP servers](/toolhive/guides-k8s/remote-mcp-proxy.md#use-with-virtual-mcp-server) for details on aggregating remote proxies behind a vMCP.

## Core capabilities[​](#core-capabilities "Direct link to Core capabilities")

* **Multi-server aggregation**: Connect to one endpoint instead of many, including both local container-based servers and remote MCP proxies
* **Tool conflict resolution**: Automatic namespacing when backend MCP servers have overlapping tool names
* **Centralized authentication**: Single sign-on with per-backend token exchange
* **Composite workflows**: Multi-step operations across backend MCP servers with parallel execution, approval gates, and error handling
* **Tool optimization**: Replace all individual tool definitions with two lightweight primitives (`find_tool` and `call_tool`) to reduce token usage and improve tool selection. See [Optimize tool discovery](/toolhive/guides-vmcp/optimizer.md) and the underlying [concepts](/toolhive/concepts/tool-optimization.md)
* **Code mode**: Let agents submit a single Starlark script that orchestrates many backend tool calls server-side instead of one round-trip per tool. See [Run tool calls server-side with code mode](/toolhive/guides-vmcp/code-mode.md)

## When to use vMCP[​](#when-to-use-vmcp "Direct link to When to use vMCP")

### Good fit[​](#good-fit "Direct link to Good fit")

* You manage 5+ MCP servers (local or remote)
* You need cross-system workflows requiring coordination
* You have centralized authentication and authorization requirements
* You need reusable workflow definitions
* You want to aggregate external SaaS MCP servers with internal tools
* You want to reduce token usage and improve tool selection accuracy across many backends with the [optimizer](/toolhive/guides-vmcp/optimizer.md)

### Not needed[​](#not-needed "Direct link to Not needed")

* You use a single MCP server
* You have simple, one-step operations
* You have no orchestration requirements

## Architecture overview[​](#architecture-overview "Direct link to Architecture overview")

<!-- -->

## How it works[​](#how-it-works "Direct link to How it works")

1. You define an MCPGroup (a resource that organizes related MCP servers)

2. Backend resources reference the group using `groupRef`:

   <!-- -->

   * **MCPServer** resources for container-based MCP servers
   * **MCPRemoteProxy** resources for external remote MCP servers
   * **MCPServerEntry** resources for remote MCP servers registered without a proxy pod

3. You create a VirtualMCPServer that references the group

4. The operator discovers all MCPServer, MCPRemoteProxy, and MCPServerEntry backends in the group and aggregates their capabilities

5. Clients connect to the VirtualMCPServer endpoint and see a unified view of all tools from both local and remote backends

## Optimize tool discovery[​](#optimize-tool-discovery "Direct link to Optimize tool discovery")

As the number of aggregated backends grows, clients receive a large number of tool definitions that consume tokens and can degrade tool selection accuracy. The vMCP optimizer addresses this by replacing all individual tool definitions with two lightweight primitives (`find_tool` and `call_tool`) and using hybrid semantic and keyword search to surface only the most relevant tools per request. To enable the optimizer, add an `embeddingServerRef` to your VirtualMCPServer resource. See [Optimize tool discovery](/toolhive/guides-vmcp/optimizer.md) for the full setup guide.

## Next steps[​](#next-steps "Direct link to Next steps")

* [Try the Quickstart](/toolhive/guides-vmcp/quickstart.md) to deploy your first vMCP on a Kubernetes cluster
* [Run vMCP locally with the CLI](/toolhive/guides-vmcp/local-cli.md) to aggregate a local ToolHive group without Kubernetes
* [Configure vMCP servers](/toolhive/guides-vmcp/configuration.md) to set up groups, backends, and tool aggregation

## Related information[​](#related-information "Direct link to Related information")

* [Understanding Virtual MCP Server](/toolhive/concepts/vmcp.md)
* [Optimize tool discovery](/toolhive/guides-vmcp/optimizer.md)
* [Run tool calls server-side with code mode](/toolhive/guides-vmcp/code-mode.md)
* [Scaling and performance](/toolhive/guides-vmcp/scaling-and-performance.md)
* [Proxy remote MCP servers](/toolhive/guides-k8s/remote-mcp-proxy.md)
* [Connect ToolHive to an enterprise identity provider](/toolhive/integrations/vmcp-idp-overview.md)