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:

apiVersion: toolhive.stacklok.dev/v1alpha1
kind: VirtualMCPServer
metadata:
  name: my-vmcp
spec:
  groupRef:
    name: my-group

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

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 # Auto-discover from backend MCPServer configs
    default:
      type: discovered

For backends requiring specific auth, reference an MCPExternalAuthConfig:

spec:
  outgoingAuth:
    source: mixed
    backends:
      github:
        type: external_auth_config_ref
        externalAuthConfigRef:
          name: github-auth

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

Token caching​

Enable token caching to reduce latency:

spec:
  tokenCache:
    provider: memory
    memory:
      maxEntries: 1000
      ttlOffset: 5m

For high-availability deployments, use Redis:

spec:
  tokenCache:
    provider: redis
    redis:
      address: redis.default.svc:6379
      keyPrefix: 'vmcp:tokens:'

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