VirtualMCPServer configuration reference
This reference documents all configuration options for the VirtualMCPServer custom resource.
Spec fields
spec.groupRef (required)
References the MCPGroup containing backend MCPServers to aggregate.
spec:
groupRef:
name: engineering-tools
The MCPGroup must exist in the same namespace and be in a Ready state before the VirtualMCPServer can start.
spec.incomingAuth
Configures authentication for clients connecting to Virtual MCP. See Authentication for detailed configuration.
Supported types:
| Type | Description |
|---|---|
anonymous | No authentication required (development only) |
oidc | OpenID Connect authentication |
kubernetes | Kubernetes service account tokens |
spec.outgoingAuth
Configures authentication from Virtual MCP to backend APIs.
Source options:
| Source | Description |
|---|---|
discovered | Auto-discover from backend MCPServer.spec.externalAuthConfigRef |
inline | Explicit per-backend configuration |
mixed | Discover most, override specific backends |
spec.aggregation
Controls how tools from multiple backends are aggregated.
See Tool aggregation for detailed configuration.
spec.tokenCache
Configures caching for exchanged tokens.
Providers:
| Provider | Description |
|---|---|
memory | In-memory cache (default) |
redis | Distributed Redis cache (for HA deployments) |
spec.operational
Configures timeouts and failure handling.
spec.compositeTools
Defines multi-step workflows that span multiple backends.
See Composite tools for detailed configuration.
spec.serviceType
Kubernetes service type for the Virtual MCP endpoint.
spec:
serviceType: ClusterIP # ClusterIP | NodePort | LoadBalancer
spec.podTemplateSpec
Custom pod specification for advanced configuration. The container name must be
vmcp.
Status fields
status.phase
Current lifecycle state:
| Phase | Description |
|---|---|
Pending | Waiting for dependencies |
Ready | Fully operational |
Degraded | Running but some backends unavailable |
Failed | Configuration or critical error |
status.conditions
Detailed condition information:
Ready: Whether VirtualMCPServer is ready to serve requestsGroupRefValidated: Whether MCPGroup reference is validAuthConfigured: Whether authentication is configuredBackendsDiscovered: Whether backends were discovered
status.url
Service URL for client connections:
http://vmcp-{name}.{namespace}.svc.cluster.local:4483
status.discoveredBackends
Array of discovered backend information including name, status, auth configuration, and last health check timestamp.
Example configurations
Minimal configuration
apiVersion: toolhive.stacklok.dev/v1alpha1
kind: VirtualMCPServer
metadata:
name: my-vmcp
spec:
groupRef:
name: my-group