Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.agentfront.dev/llms.txt

Use this file to discover all available pages before exploring further.

FrontMCP implements a flexible authentication system with four modes designed for both development simplicity and production security.

​
Authentication Modes

FrontMCP supports four authentication modes, each designed for different deployment scenarios:

Public Mode

mode: 'public' — No authentication required. Anonymous sessions are auto-generated for all requests.Best for: Development, testing, public APIs

Transparent Mode

mode: 'transparent' — Pass-through tokens from external identity providers. FrontMCP validates tokens against upstream JWKS.Best for: Existing Auth0, Okta, Azure AD integrations

Local Mode

mode: 'local' — Built-in OAuth 2.1 authorization server. FrontMCP issues and validates its own tokens.Best for: Self-contained auth, multi-app scenarios, progressive authorization

Remote Mode

mode: 'remote' — FrontMCP runs as an OAuth 2.1 server that proxies user authentication to an upstream IdP.Best for: Federated auth, IdPs without DCR, custom consent layer

​
Quick Mode Selection

ScenarioRecommended ModeWhy
Local developmentpublicNo setup required
Existing IdP (Auth0, Okta)transparentDirect token pass-through
Multi-provider federationremoteUnified session, multiple IdPs
Self-contained authlocalFull control, built-in OAuth server

​
Configuration Levels

Authentication can be configured at two levels:
Apply the same auth configuration to all apps:
@FrontMcp({
  info: { name: 'MyServer', version: '1.0.0' },
  apps: [BillingApp, AnalyticsApp],
  auth: {
    mode: 'local',
    consent: { enabled: true },
  },
})
export class Server {}
When using splitByApp: true, you must configure auth per app. Server-level auth is not allowed.

​
OAuth 2.1 Compliance

FrontMCP’s local mode is fully OAuth 2.1 compliant. In remote mode, FrontMCP’s own endpoints (the surface the MCP client talks to) are OAuth 2.1-aligned, but the end-to-end behavior also depends on the upstream identity provider FrontMCP is proxying to. The guarantees below apply to FrontMCP’s own implementation:
PKCE Required - Only S256 code challenge method supported (downstream)
Authorization Code Flow - No implicit or password grants
Refresh Token Rotation - FrontMCP-issued refresh tokens rotate on each use (local mode; remote mode mirrors upstream behavior)
JWT Access Tokens - Signed with RS256 or ES256

​
Session Management

Sessions determine how tokens are stored and managed:
Session ModeToken StorageRefreshMulti-Instance
StatefulServer-side (Redis/memory)Silent refreshRequires shared storage
StatelessEmbedded in JWTClient must re-authWorks anywhere
Use stateful sessions when working with short-lived upstream tokens. You’ll get automatic refresh without client round-trips.
auth: {
  mode: 'local',
  tokenStorage: {
    redis: { host: 'localhost', port: 6379 },
  },
}

​
Discovery Endpoints

FrontMCP exposes standard OAuth discovery endpoints:
EndpointDescription
/.well-known/oauth-authorization-serverOAuth 2.0 Authorization Server Metadata (RFC 8414)
/.well-known/jwks.jsonJSON Web Key Set for token verification (RFC 7517)
/.well-known/oauth-protected-resourceProtected Resource Metadata

​
Next Steps

Authorization Modes

Deep dive into public, transparent, local, and remote modes

Token & Sessions

Configure token lifetimes and session management

Remote OAuth

Connect to external identity providers

Production Checklist

Security requirements for production deployments