Skip to main content

Deploy Virtual MCP Server

This guide shows you how to aggregate multiple MCP servers using the VirtualMCPServer custom resource.

Prerequisites​

  • Kubernetes cluster with ToolHive operator installed (see Deploy the operator using Helm)
  • kubectl configured to communicate with your cluster
  • Basic familiarity with Kubernetes resources

Overview​

Deploying Virtual MCP Server involves three steps:

  1. Create an MCPGroup to organize your backend servers
  2. Deploy MCPServer resources within the group
  3. Create a VirtualMCPServer that aggregates the group

Step 1: Create an MCPGroup​

Step 2: Deploy backend MCPServers​

Step 3: Create a VirtualMCPServer​

Step 4: Verify the deployment​

What's happening?

When you create a VirtualMCPServer resource, the operator:

  1. Validates the MCPGroup reference exists and is ready
  2. Discovers all MCPServer backends in the group
  3. Creates a ConfigMap with the aggregation configuration
  4. Deploys the Virtual MCP server as a Deployment
  5. Creates a Service for client access
  6. Aggregates tools from all backends with conflict resolution

Step 5: Connect your client​

Next steps​

Troubleshooting​

VirtualMCPServer stuck in Pending

Check that the MCPGroup is ready and backend MCPServers are running.

Backends not discovered

Verify MCPServers reference the correct group.

Tools not appearing in client

Check the Virtual MCP server logs for errors.