Skip to main content

Configuring Virtual MCP Server

This guide covers common configuration patterns for VirtualMCPServer. For a complete field reference, see the VirtualMCPServer CRD specification.

Minimal configuration​

At minimum, a VirtualMCPServer requires a reference to an MCPGroup and an authentication type:

apiVersion: toolhive.stacklok.dev/v1alpha1
kind: VirtualMCPServer
metadata:
  name: my-vmcp
spec:
  groupRef:
    name: my-group
  incomingAuth:
    type: anonymous # Disables authentication; do not use in production

The MCPGroup must exist in the same namespace and be in a Ready state before the VirtualMCPServer can start.

Adding authentication​

Development (no authentication)​

For local development only:

spec:
  incomingAuth:
    type: anonymous
warning

Never use anonymous authentication in production environments.

OIDC authentication​

Validate tokens from an external identity provider:

spec:
  incomingAuth:
    type: oidc
    oidcConfig:
      type: inline
      inline:
        issuer: https://your-idp.example.com
        audience: vmcp
        clientId: your-client-id
        # For token introspection, add clientSecretRef referencing a Secret

Kubernetes service account tokens​

For in-cluster clients using service account tokens:

spec:
  incomingAuth:
    type: oidc
    oidcConfig:
      type: kubernetes
      kubernetes:
        audience: toolhive

See Authentication for complete authentication options.

Configuring backend authentication​

Control how Virtual MCP authenticates to backend MCP servers:

spec:
  outgoingAuth:
    source: discovered

With discovery mode, Virtual MCP checks each backend MCPServer's externalAuthConfigRef to determine how to authenticate.

Exposing the service​

Choose how to expose the Virtual MCP endpoint:

spec:
  serviceType: ClusterIP # Default: internal access only
  # serviceType: LoadBalancer # External access via cloud load balancer
  # serviceType: NodePort     # External access via node ports

Monitoring status​

Check the VirtualMCPServer status to verify it's ready:

kubectl get virtualmcpserver my-vmcp

Key status fields:

FieldDescription
phaseCurrent state (Pending, Ready, Degraded, Failed)
urlService URL for client connections
backendCountNumber of discovered backend MCP servers
discoveredBackendsDetails about each backend and its auth type