Authentication Overview

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

Scenario	Recommended Mode	Why
Local development	`public`	No setup required
Existing IdP (Auth0, Okta)	`transparent`	Direct token pass-through
Multi-provider federation	`remote`	Unified session, multiple IdPs
Self-contained auth	`local`	Full control, built-in OAuth server

Configuration Levels

Authentication can be configured at two levels:

Server Level
App Level

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 {}

Each app defines its own auth provider (required when splitByApp: true):

@App({
  name: 'Billing',
  auth: {
    mode: 'transparent',
    provider: 'https://auth.example.com',
  },
})
export class BillingApp {}

@FrontMcp({
  info: { name: 'Suite', version: '1.0.0' },
  apps: [BillingApp, CrmApp],
  splitByApp: 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 Mode	Token Storage	Refresh	Multi-Instance
Stateful	Server-side (Redis/memory)	Silent refresh	Requires shared storage
Stateless	Embedded in JWT	Client must re-auth	Works 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:

Endpoint	Description
`/.well-known/oauth-authorization-server`	OAuth 2.0 Authorization Server Metadata (RFC 8414)
`/.well-known/jwks.json`	JSON Web Key Set for token verification (RFC 7517)
`/.well-known/oauth-protected-resource`	Protected 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

Get Started

Concepts

Build

Deploy

Plugins

Adapters

Extensibility

Testing

React SDK

Guides

Authentication Overview

Authentication Modes

Public Mode

Transparent Mode

Local Mode

Remote Mode

Quick Mode Selection

Configuration Levels

OAuth 2.1 Compliance

Session Management

Discovery Endpoints

Next Steps

Authorization Modes

Token & Sessions

Remote OAuth

Production Checklist

​Authentication Modes

Public Mode

Transparent Mode

Local Mode

Remote Mode

​Quick Mode Selection

​Configuration Levels

​OAuth 2.1 Compliance

​Session Management

​Discovery Endpoints

​Next Steps

Authorization Modes

Token & Sessions

Remote OAuth

Production Checklist

Authentication Modes

Quick Mode Selection

Configuration Levels

OAuth 2.1 Compliance

Session Management

Discovery Endpoints

Next Steps