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 a token with aud=vmcp. This is your organization's identity layer.

Boundary 2 (Outgoing): Virtual MCP exchanges the client token for backend-specific tokens. Each backend API receives a token 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

OIDC authentication​

Validate tokens from an external identity provider.

Kubernetes service account tokens​

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

Outgoing authentication​

Configure how Virtual MCP authenticates to backend APIs.

Automatically discover authentication configuration from each backend's MCPServer resource:

spec:
  outgoingAuth:
    source: discovered
    default:
      type: unauthenticated

Token exchange (RFC 8693)​

Exchange the client's token for a backend-specific token:

Header injection (API keys)​

Inject a static header value (such as an API key or bearer token) into requests:

spec:
  outgoingAuth:
    source: inline
    backends:
      github:
        type: header_injection
        headerInjection:
          headerName: 'Authorization'
          headerValueRef:
            name: github-api-secret
            key: token

Unauthenticated​

For backends that require no authentication:

spec:
  outgoingAuth:
    source: inline
    backends:
      public-api:
        type: unauthenticated

Authorization with Cedar​

Add fine-grained authorization using Cedar policies:

See Cedar policies for policy syntax.

Token caching​

Virtual MCP caches exchanged tokens to reduce latency and load on identity providers:

spec:
  tokenCache:
    provider: memory
    memory:
      maxEntries: 1000
      ttlOffset: 5m # Refresh 5 minutes before expiry

Example: Complete authentication setup​