Skip to main content

Authentication

Virtual MCP implements a two-boundary authentication model that separates client authentication from backend authentication, giving you centralized control over access while supporting diverse backend requirements.

Two-boundary authentication model​

Boundary 1 (Incoming): Clients authenticate to Virtual MCP using the mechanism defined in the MCP specification. This is your organization's identity layer.

Boundary 2 (Outgoing): Virtual MCP obtains appropriate credentials for each backend. Each backend API receives a token or credential scoped to its requirements.

Incoming authentication​

Configure how clients authenticate to Virtual MCP.

Anonymous (development only)​

No authentication required. Use only for local development.

spec:
  incomingAuth:
    type: anonymous
warning

Never use anonymous incoming authentication in production environments.

OIDC authentication​

Validate tokens from an external identity provider:

spec:
  incomingAuth:
    type: oidc
    oidcConfig:
      type: inline
      inline:
        issuer: https://auth.example.com
        clientId: your-client-id
        audience: vmcp

When using an identity provider that issues opaque OAuth tokens, add a clientSecretRef referencing a Kubernetes Secret to enable token introspection:

spec:
  incomingAuth:
    type: oidc
    oidcConfig:
      type: inline
      inline:
        issuer: https://auth.example.com
        clientId: your-client-id
        audience: vmcp
        clientSecretRef:
          name: oidc-client-secret
          key: clientSecret

Create the Secret:

apiVersion: v1
kind: Secret
metadata:
  name: oidc-client-secret
  namespace: toolhive-system
type: Opaque
stringData:
  clientSecret: your-client-secret

Kubernetes service account tokens​

Authenticate using Kubernetes service account tokens for in-cluster clients:

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

This configuration uses the Kubernetes API server as the OIDC issuer and validates service account tokens. The defaults work for most clusters:

  • issuer: https://kubernetes.default.svc (auto-detected)
  • audience: toolhive (configurable)

Outgoing authentication​

Configure how Virtual MCP authenticates to backend MCP servers.

Discovery mode​

When using discovery mode, Virtual MCP checks each backend MCPServer's externalAuthConfigRef to determine how to authenticate. If a backend has no auth config, Virtual MCP connects without authentication.

spec:
  outgoingAuth:
    source: discovered

This is the recommended approach for most deployments. Backends that don't require authentication work automatically, while backends with externalAuthConfigRef configured use their specified authentication method.