Production Checklist

Before deploying FrontMCP authentication to production, review this comprehensive checklist covering security, configuration, and operational requirements.

Pre-Deployment Checklist

Configure Persistent Token Storage

Replace in-memory storage with a persistent store. Use Redis for multi-instance deployments, or SQLite for a single-instance/single-node deployment that needs tokens to survive a restart.

// Redis — shared across instances
auth: {
  mode: 'local',
  tokenStorage: {
    redis: {
      host: process.env.REDIS_HOST!,
      port: parseInt(process.env.REDIS_PORT || '6379'),
      password: process.env.REDIS_PASSWORD,
      tls: true,
    },
  },
}

// SQLite — single-instance persistence (not shared across nodes)
auth: {
  mode: 'local',
  tokenStorage: {
    sqlite: {
      path: process.env.AUTH_DB_PATH ?? './data/auth.sqlite',
      encryption: { secret: process.env.AUTH_DB_SECRET! },
    },
  },
}

SQLite persists tokens on the local disk of one node — it is not a shared store. For more than one instance behind a load balancer, use Redis so every instance reads the same authorization/refresh/session state.

Provide Persistent Signing Keys

Auto-generated keys are lost on restart. Provide stable keys.

auth: {
  local: {
    signKey: JSON.parse(process.env.JWT_SIGNING_KEY),
  },
}

Enable Refresh Token Flow

For local and remote modes, opt into automatic token refresh.

auth: {
  refresh: {
    enabled: true,
    skewSeconds: 60, // refresh tokens this many seconds before expiry
  },
}

In remote mode, token TTLs are controlled by the upstream identity provider — FrontMCP does not mint its own access/refresh tokens. In local mode, FrontMCP acts as the authorization server and mints its own tokens (signed with local.signKey).

Enable HTTPS

All production traffic must use TLS. Configure your reverse proxy or load balancer.

Set Expected Audience

Validate the audience (aud) claim. In transparent mode set expectedAudience. In local and remote mode the tokens FrontMCP issues always name this server’s resource URL as aud and name this server as iss, and are refused anywhere else, even by a server with the same JWT_SECRET; pin FRONTMCP_PUBLIC_URL so that URL doesn’t come from the Host header. Setting expectedAudience there too makes the server accept only tokens issued for the listed resource URLs, whatever URL the request arrived at.

auth: {
  mode: 'transparent', // also valid for mode: 'local' | 'remote'
  expectedAudience: 'https://api.yourservice.com',
}

Security Requirements

Required

HTTPS only - Never expose auth endpoints over HTTP in production

Persistent token storage - Redis with TLS for multi-instance deployments

Stable signing keys - Provide keys via environment or secrets manager

PKCE enforcement - OAuth 2.1 requires PKCE (S256 only)

Refresh token rotation - Always rotate refresh tokens on use

Audience validation - Validate the aud claim via expectedAudience in transparent mode; local and remote tokens are bound to this server’s resource URL automatically, or to the expectedAudience you list

Pinned public URL - Set FRONTMCP_PUBLIC_URL to a fixed origin. The issuer / resource / OAuth-discovery URLs — and the expected audience of a token — are otherwise derived from request headers. X-Forwarded-Host/X-Forwarded-Proto are ignored by default; only enable them with FRONTMCP_TRUST_PROXY=1 behind a proxy that strips client-supplied forwarded headers. The Web fetch handler (createFetchHandler, Workers, Deno, Bun) takes the address from the request URL the runtime hands it, never from a Host header that disagrees with it.

Require registered clients - Keep auth.requireRegisteredClients at its default (true, local/remote) so every OAuth client must be registered (DCR / pre-registered) or use a CIMD client-id URL. This enforces exact redirect_uri matching and prevents auth-code interception via an unregistered client’s attacker-chosen redirect_uri. In production, remote mode admits only CIMD clients (it has no pre-registered clients and DCR is off); see MCP client registration.

Grant only the scopes you mean to - List your scopes in auth.allowedScopes (local/remote); a client that asks for anything else doesn’t get it.

Confidential clients - Clients registered with client_secret_basic/client_secret_post are authenticated with a constant-time secret check on both the code-exchange and refresh grants.

Rate limiting - Protect token endpoints from brute force

Monitoring - Alert on auth failures, unusual patterns

Key rotation - Rotate signing keys periodically (30-90 days)

Scope minimization - Request only necessary scopes

Consent UI - Let users see what they’re authorizing

Configuration Reference

Minimum Production Configuration

import { FrontMcp } from '@frontmcp/sdk';

@FrontMcp({
  info: { name: 'ProductionServer', version: '1.0.0' },
  auth: {
    mode: 'local',
    // Persistent storage
    tokenStorage: {
      redis: {
        host: process.env.REDIS_HOST!,
        port: parseInt(process.env.REDIS_PORT || '6379'),
        password: process.env.REDIS_PASSWORD,
        tls: true,
        keyPrefix: 'auth:',
      },
    },

    // Stable keys
    local: {
      signKey: JSON.parse(process.env.JWT_SIGNING_KEY!),
    },

    // Token refresh settings
    refresh: {
      enabled: true,
      skewSeconds: 60,
    },

    // Security
    consent: { enabled: true },
  },
})
export class Server {}

Environment Variables

# Required for Redis
REDIS_HOST=redis.example.com
REDIS_PORT=6379
REDIS_PASSWORD=your-redis-password

# Required for token signing
JWT_SIGNING_KEY='{"kty":"RSA","kid":"prod-key-1",...}'

# Pin the canonical public origin (issuer / resource / discovery / audience are
# derived from it instead of request headers). Strongly recommended.
FRONTMCP_PUBLIC_URL=https://mcp.example.com

# Only when behind a reverse proxy that STRIPS client-supplied X-Forwarded-*
# headers and sets its own — otherwise these headers are ignored (secure default).
# Prefer FRONTMCP_PUBLIC_URL over trusting the proxy.
# FRONTMCP_TRUST_PROXY=1

# For remote/transparent mode
IDP_PROVIDER_URL=https://auth.example.com
IDP_CLIENT_ID=your-client-id
IDP_CLIENT_SECRET=your-client-secret
IDP_EXPECTED_AUDIENCE=https://api.yourservice.com

Token Lifetime Guidelines

Environment	Access Token	Refresh Token	Rationale
Development	1 hour	7 days	Developer convenience
Staging	30 min	7 days	Balance testing/security
Production	15 min	7-30 days	Security with usability
High Security	5 min	1 day	Minimize exposure window

Shorter access tokens improve security but increase refresh frequency. Monitor your refresh token endpoint load.

Key Management

Generating Production Keys

# Generate RS256 key pair
openssl genrsa -out private.pem 2048
openssl rsa -in private.pem -pubout -out public.pem

# Convert to JWK format (use a tool like step-cli)
step crypto jwk create --kty RSA --use sig --alg RS256 \
  public.jwk private.jwk

Key Rotation Strategy

Configuration for Key Rotation

The local block accepts a single signKey (and optional jwks containing previous keys for validation during rollover). Rotation is performed by deploying a new server build with an updated signKey while keeping the old key in jwks until in-flight tokens expire.

auth: {
  local: {
    // Private key used to sign new tokens
    signKey: currentPrivateJwk,
    // Public JWKS — clients/relying parties use this to validate tokens.
    // Include the previous public key during rollover so old (still-valid)
    // tokens continue to verify until they expire. NEVER put private key
    // material in jwks.
    jwks: { keys: [currentPublicJwk, previousPublicJwk] },
    issuer: 'https://your-server.example.com',
  },
}

Redis Configuration

Secure Redis Connection

tokenStorage: {
  redis: {
    host: 'redis.example.com',
    port: 6379,
    password: process.env.REDIS_PASSWORD,
    tls: true,
    keyPrefix: 'frontmcp:auth:',
  },
}

Redis Data Stored

Key Pattern	Data	TTL
`{prefix}pending:{id}`	Pending authorization	10 min
`{prefix}code:{code}`	Authorization code	60 sec
`{prefix}refresh:{token}`	Refresh token	7-30 days
`{prefix}session:{id}`	Session data	Configurable
`{prefix}vault:{session}`	Token vault	Session TTL

Monitoring & Alerting

Key Metrics to Monitor

Metric	Alert Threshold	Description
Auth failures/min	> 100	Possible brute force
Token refresh rate	> 10x normal	Possible token theft
JWKS fetch errors	Any	IdP connectivity issue
Redis connection errors	Any	Storage unavailable
Token issuance latency	> 500ms	Performance degradation

Logging Configuration

import { FrontMcp, LogLevel } from '@frontmcp/sdk';

@FrontMcp({
  info: { name: 'Server', version: '1.0.0' },
  logging: {
    level: LogLevel.Info,
  },
  // Redaction is an OBSERVABILITY concern — `logging` has no `redact` field.
  // Configure `redactFields` under observability.logging to strip secrets from
  // structured logs (requires the @frontmcp/observability integration).
  observability: {
    logging: {
      redactFields: ['access_token', 'refresh_token', 'client_secret'],
    },
  },
})
export class Server {}

Common Production Issues

Tokens invalid after deployment

Cause: Auto-generated keys changed after restart.Solution: Provide persistent signing keys via environment variable:

local: {
  signKey: JSON.parse(process.env.JWT_SIGNING_KEY!),
}

Session not found errors across instances

Cause: Using in-memory storage with multiple instances.Solution: Configure shared Redis storage:

tokenStorage: {
  redis: {
    host: process.env.REDIS_HOST!,
    port: parseInt(process.env.REDIS_PORT || '6379'),
    password: process.env.REDIS_PASSWORD,
    tls: true,
  },
}

Also check MCP_SESSION_SECRET: it must be the same on every instance. A session id minted under a different secret is answered with HTTP 404 (-32000) and the client re-initializes — in every auth mode, including public, where the id is the caller’s only credential. The same happens once, by design, right after you rotate the secret.

A 2026-07-28 tool asks its first question again

Cause: requestState is signed with VAULT_SECRET, else JWT_SECRET, else a random per-process key. With the per-process key, a round answered on another instance (or after a restart) fails verification (mcp-20260728: rejected requestState, reason: 'bad-signature', with a hint naming VAULT_SECRET) and the exchange restarts.Solution: Set VAULT_SECRET (or JWT_SECRET) to the same value on every instance. In production, a server with redis or transport.persistence but neither secret warns about this at startup.

JWKS fetch fails intermittently

Cause: Network issues or IdP rate limiting.Solution:

Increase JWKS cache TTL
Consider inline JWKS for critical IdPs
Add retry logic with exponential backoff

High latency on token endpoint

Cause: Redis connection issues or key generation overhead.Solution:

Use Redis connection pooling
Pre-generate signing keys (don’t generate on-demand)
Monitor Redis latency

Security Hardening

Disable Insecure Options

auth: {
  mode: 'local',

  // Production settings
  allowDefaultPublic: false,   // No anonymous access

  // Use local mode login page or remote IdP
  // Never use the demo login page in production
}

For remote mode, DCR is configured under providerConfig:

auth: {
  mode: 'remote',
  provider: 'https://auth.example.com',
  clientId: process.env.IDP_CLIENT_ID!,
  clientSecret: process.env.IDP_CLIENT_SECRET!,
  providerConfig: {
    dcrEnabled: false,  // Disable DCR in production; pre-register clients
  },
}

HTTP Security Headers

Configure your reverse proxy to add security headers:

# Example nginx configuration
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-Frame-Options "DENY" always;
add_header Content-Security-Policy "default-src 'self'" always;

Rate Limiting

FrontMCP includes a built-in session rate limiter with a sliding window algorithm:

Setting	Default	Description
Window	60 seconds (`windowMs: 60000`)	Sliding window duration
Max requests	100 (`maxRequests`)	Maximum requests per window per key
Cleanup interval	60000 ms (`cleanupIntervalMs`, set `0` to disable)	Auto-cleanup of expired entries

The rate limiter tracks requests per key (typically client IP) and provides:

wouldAllow(key) — pre-check without consuming quota
getStats() — monitoring statistics

For external rate limiting on the token endpoint:

# Rate limit token endpoint
location /oauth/token {
    limit_req zone=token_limit burst=10 nodelay;
    proxy_pass http://backend;
}

Deployment Patterns

Single Instance
Multi-Instance
Stateless

// Simple deployment - in-memory works but not recommended
auth: {
  tokenStorage: 'memory', // Data lost on restart
}

In-memory storage loses all sessions on restart. Users must re-authenticate.

// Required for horizontal scaling
auth: {
  tokenStorage: {
    redis: {
      host: process.env.REDIS_HOST!,
      port: parseInt(process.env.REDIS_PORT || '6379'),
      password: process.env.REDIS_PASSWORD,
      tls: true,
    },
  },
}

All instances must share the same Redis and signing keys.

Machine ID: Set the MACHINE_ID environment variable to the same value on all instances. Without it, sessions encrypted on one instance cannot be decrypted on another. See Machine ID.

// No shared state needed - tokens contain all info
auth: {
  local: {
    signKey: JSON.parse(process.env.JWT_SIGNING_KEY!),
  },
}

Simpler architecture but larger tokens, no silent refresh.

Quick Reference

OAuth 2.1 Compliance Checklist

PKCE required for all clients (S256 only)

Refresh token rotation enabled

No implicit grant flow

Authorization codes single-use

Redirect URI exact match

State parameter required

Pre-Production Verification

# Test token endpoint
curl -X POST https://your-server/oauth/token \
  -d "grant_type=authorization_code" \
  -d "code=test-code" \
  -d "client_id=your-client" \
  -d "code_verifier=verifier"

# Verify JWKS endpoint
curl https://your-server/.well-known/jwks.json

# Check server metadata
curl https://your-server/.well-known/oauth-authorization-server

Next Steps

Authorization Modes

Choose the right mode for your deployment

Tokens & Sessions

Configure token lifetimes and storage

Local OAuth

Built-in OAuth server setup

Remote OAuth

External IdP integration

​Pre-Deployment Checklist

​Security Requirements

​Required

​Recommended

​Configuration Reference

​Minimum Production Configuration

​Environment Variables

​Token Lifetime Guidelines

​Key Management

​Generating Production Keys

​Key Rotation Strategy

​Configuration for Key Rotation

​Redis Configuration

​Secure Redis Connection

​Redis Data Stored

​Monitoring & Alerting

​Key Metrics to Monitor

​Logging Configuration

​Common Production Issues

​Security Hardening

​Disable Insecure Options

​HTTP Security Headers

​Rate Limiting

​Deployment Patterns

​Quick Reference

​OAuth 2.1 Compliance Checklist

​Pre-Production Verification

​Next Steps

Authorization Modes

Tokens & Sessions

Local OAuth

Remote OAuth

Pre-Deployment Checklist

Security Requirements

Required

Recommended

Configuration Reference

Minimum Production Configuration

Environment Variables

Token Lifetime Guidelines

Key Management

Generating Production Keys

Key Rotation Strategy

Configuration for Key Rotation

Redis Configuration

Secure Redis Connection

Redis Data Stored

Monitoring & Alerting

Key Metrics to Monitor

Logging Configuration

Common Production Issues

Security Hardening

Disable Insecure Options

HTTP Security Headers

Rate Limiting

Deployment Patterns

Quick Reference

OAuth 2.1 Compliance Checklist

Pre-Production Verification

Next Steps