@frontmcp/skills 1.3.0 → 1.4.0

package/catalog/frontmcp-config/examples/configure-auth/remote-oauth-with-vault.md

@@ -2,17 +2,26 @@
 name: remote-oauth-with-vault
 reference: configure-auth
 level: intermediate
-description: 'Configure a FrontMCP server with remote OAuth 2.1 authentication and use the credential vault to call downstream APIs on behalf of the authenticated user.'
-tags: [config, oauth, auth, remote, vault]
+description: 'Configure a FrontMCP server with local OAuth orchestration of an upstream provider and read the downstream provider token in a tool via this.orchestration.getToken.'
+tags: [config, oauth, auth, orchestration, providers]
 features:
-  - "Configuring `mode: 'remote'` for full OAuth 2.1 authorization flow"
-  - 'Loading `clientId` from environment variables instead of hardcoding'
-  - "Using `this.authProviders.headers('github')` to get pre-formatted auth headers for downstream API calls"
+  - 'Declaring an upstream provider in top-level `auth.providers` so FrontMCP orchestrates its OAuth flow'
+  - 'Loading `clientId`/`clientSecret` from environment variables instead of hardcoding'
+  - "Reading the downstream provider token in a tool via `this.orchestration.getToken('github')`"
 ---
 
-# Remote OAuth Mode with Credential Vault
+# Local OAuth Orchestration with a Downstream Provider Token
 
-Configure a FrontMCP server with remote OAuth 2.1 authentication and use the credential vault to call downstream APIs on behalf of the authenticated user.
+Configure a FrontMCP server with local OAuth orchestration of an upstream provider and read the downstream provider token in a tool via this.orchestration.getToken.
+
+> **Two distinct subsystems — do not conflate them.** `this.orchestration` reads
+> tokens for providers declared in top-level `auth.providers` (the local-mode
+> multi-provider OAuth orchestrator). `this.authProviders` is a _separate_
+> downstream-OAuth-provider accessor whose providers are registered via
+> `@App`/`@Tool({ authProviders: [...] })`. Neither is the per-session credential
+> vault — that is `this.credentials` (see `local-credential-vault`). This example
+> uses the orchestrator, so the provider MUST be declared in `auth.providers` or
+> `getToken('github')` has nothing to return.
 
 ## Code
 
@@ -32,12 +41,14 @@ import { App, FrontMcp, Tool, ToolContext, z } from '@frontmcp/sdk';
 })
 class CreateGithubIssueTool extends ToolContext {
   async execute(input: { repo: string; title: string; body: string }) {
-    // Access downstream credentials via the authProviders context extension
-    const headers = await this.authProviders.headers('github');
+    // Read the orchestrated GitHub token (declared in auth.providers below).
+    // Throws if GitHub is not linked for this session; use tryGetToken() for a
+    // null-on-missing variant. The raw token is never exposed to the LLM.
+    const token = await this.orchestration.getToken('github');
 
     const response = await fetch(`https://api.github.com/repos/${input.repo}/issues`, {
       method: 'POST',
-      headers: { ...headers, 'Content-Type': 'application/json' },
+      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
       body: JSON.stringify({ title: input.title, body: input.body }),
     });
     const issue = await response.json();
@@ -45,31 +56,42 @@ class CreateGithubIssueTool extends ToolContext {
   }
 }
 
-@App({
-  name: 'dev-tools',
-  auth: {
-    mode: 'remote',
-    provider: 'https://auth.example.com',
-    clientId: process.env['OAUTH_CLIENT_ID'] ?? 'mcp-client-id',
-  },
-  tools: [CreateGithubIssueTool],
-})
+@App({ name: 'dev-tools', tools: [CreateGithubIssueTool] })
 class DevToolsApp {}
 
 @FrontMcp({
   info: { name: 'dev-tools-server', version: '1.0.0' },
   apps: [DevToolsApp],
+  // Server-level auth so it applies to every app (no `splitByApp` needed).
+  auth: {
+    mode: 'local',
+    // Declare the upstream provider FrontMCP should orchestrate. FrontMCP
+    // federates it at /oauth/authorize, stores its tokens encrypted
+    // server-side, and exposes them via this.orchestration.getToken('github').
+    providers: [
+      {
+        id: 'github',
+        authorizeUrl: 'https://github.com/login/oauth/authorize',
+        tokenUrl: 'https://github.com/login/oauth/access_token',
+        clientId: process.env['GITHUB_CLIENT_ID']!,
+        clientSecret: process.env['GITHUB_CLIENT_SECRET'],
+        scopes: ['repo'],
+      },
+    ],
+    federatedAuth: { minProviders: 1, requiredProviders: ['github'] },
+  },
 })
 class Server {}
 ```
 
 ## What This Demonstrates
 
-- Configuring `mode: 'remote'` for full OAuth 2.1 authorization flow
-- Loading `clientId` from environment variables instead of hardcoding
-- Using `this.authProviders.headers('github')` to get pre-formatted auth headers for downstream API calls
+- Declaring an upstream provider in top-level `auth.providers` so FrontMCP orchestrates its OAuth flow
+- Loading `clientId`/`clientSecret` from environment variables instead of hardcoding
+- Reading the downstream provider token in a tool via `this.orchestration.getToken('github')`
 
 ## Related
 
-- See `configure-auth` for credential vault API (`get`, `headers`, `has`, `refresh`)
+- See `configure-auth` for the multi-provider orchestration config and the `this.orchestration` API (`getToken`, `tryGetToken`, `isAuthenticated`)
+- See `local-credential-vault` for the separate per-session vault (`this.credentials`)
 - See `configure-session` for setting up Redis-based session storage in production

package/catalog/frontmcp-config/examples/configure-auth-modes/local-behind-tunnel.md

@@ -0,0 +1,73 @@
+---
+name: local-behind-tunnel
+reference: configure-auth-modes
+level: intermediate
+description: 'Expose a local-mode server through a tunnel or TLS proxy by aligning the token issuer with the public URL clients actually reach.'
+tags: [config, auth, local, tunnel, proxy, issuer, auth-modes]
+features:
+  - 'Relying on request-host-derived OAuth discovery, which works behind a tunnel or under an http.entryPath without extra config'
+  - 'Setting `local.issuer` to a full public HTTPS URL so the token `iss` matches what clients reach through the proxy'
+  - 'Knowing `FRONTMCP_PUBLIC_HOST` overrides only the discovery host (scheme/port still come from the HTTP config or local.issuer)'
+---
+
+# Local Mode Behind a Tunnel
+
+Expose a local-mode server through a tunnel or TLS proxy by aligning the token issuer with the public URL clients actually reach.
+
+## Code
+
+```typescript
+// src/server.ts
+// OAuth discovery (.well-known/*) is derived from the incoming request host at
+// runtime and advertises /oauth/* at the root, so it works behind a tunnel or
+// reverse proxy with no extra config. `local.issuer` only aligns the boot-time
+// `iss` claim with the public HTTPS URL clients reach.
+//
+// `FRONTMCP_PUBLIC_HOST=mcp.example.com` would set only the discovery HOST
+// (scheme stays http, port stays the HTTP port) — use `local.issuer` when you
+// need a different scheme/port, as below.
+import { App, FrontMcp, Tool, ToolContext, z } from '@frontmcp/sdk';
+
+@Tool({
+  name: 'ping',
+  description: 'Ping the server',
+  inputSchema: {},
+  outputSchema: { pong: z.boolean() },
+})
+class PingTool extends ToolContext {
+  async execute() {
+    return { pong: true };
+  }
+}
+
+@App({
+  name: 'tunneled-api',
+  auth: {
+    mode: 'local',
+    local: {
+      // Public URL exposed by the tunnel / TLS proxy.
+      issuer: 'https://mcp.example.com',
+    },
+    tokenStorage: { sqlite: { path: './data/auth.sqlite' } },
+  },
+  tools: [PingTool],
+})
+class TunneledApi {}
+
+@FrontMcp({
+  info: { name: 'tunneled-server', version: '1.0.0' },
+  apps: [TunneledApi],
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Relying on request-host-derived OAuth discovery, which works behind a tunnel or under an http.entryPath without extra config
+- Setting `local.issuer` to a full public HTTPS URL so the token `iss` matches what clients reach through the proxy
+- Knowing `FRONTMCP_PUBLIC_HOST` overrides only the discovery host (scheme/port still come from the HTTP config or local.issuer)
+
+## Related
+
+- See `configure-auth-modes` for a comparison of all auth modes
+- See `local-self-signed-tokens` for token persistence options

package/catalog/frontmcp-config/examples/configure-auth-modes/local-consent-enforcement.md

@@ -0,0 +1,87 @@
+---
+name: local-consent-enforcement
+reference: configure-auth-modes
+level: intermediate
+description: 'Enable consent in local mode to render a tool-selection screen at login and enforce the chosen tools at call time, keeping essential tools always available via excludedTools.'
+tags: [config, auth, local, consent, tool-authorization, auth-modes]
+features:
+  - 'Setting `consent.enabled` so login renders a tool-selection screen and the chosen tools are enforced on every tools/call'
+  - 'Listing `excludedTools` so essential tools are never offered and are always available'
+  - 'Honoring `requireSelection` / `defaultSelectedTools` to require a non-empty selection and pre-check tools'
+  - 'Pinning `rememberConsent: false` to re-show the screen on every login (the default `true` reuses a prior per-(user, client) selection and only re-prompts when a NEW tool appears)'
+---
+
+# Local Consent Enforcement
+
+Enable consent in local mode to render a tool-selection screen at login and enforce the chosen tools at call time, keeping essential tools always available via excludedTools.
+
+## Code
+
+```typescript
+// src/server.ts
+import { App, FrontMcp, Tool, ToolContext, z } from '@frontmcp/sdk';
+
+@Tool({
+  name: 'health',
+  description: 'Health check',
+  inputSchema: {},
+  outputSchema: { ok: z.boolean() },
+})
+class HealthTool extends ToolContext {
+  async execute() {
+    return { ok: true };
+  }
+}
+
+@Tool({
+  name: 'delete_account',
+  description: 'Delete a user account',
+  inputSchema: { userId: z.string() },
+  outputSchema: { deleted: z.boolean() },
+})
+class DeleteAccountTool extends ToolContext {
+  async execute(input: { userId: string }) {
+    return { deleted: true };
+  }
+}
+
+@App({
+  name: 'admin-api',
+  auth: {
+    mode: 'local',
+    consent: {
+      enabled: true,
+      requireSelection: true, // reject an empty submit (default)
+      // Re-show the screen on every login so the user must explicitly opt into
+      // delete_account each time. `rememberConsent` defaults to `true` (reuse a
+      // prior per-(user, client) selection); pin it `false` for an opt-in-every-time
+      // screen like this one.
+      rememberConsent: false,
+      // `health` is never offered on the consent screen and is always callable.
+      excludedTools: ['health'],
+      // Pre-check nothing dangerous: the user must explicitly opt into delete_account.
+      defaultSelectedTools: [],
+    },
+  },
+  tools: [HealthTool, DeleteAccountTool],
+})
+class AdminApi {}
+
+@FrontMcp({
+  info: { name: 'consent-server', version: '1.0.0' },
+  apps: [AdminApi],
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Setting `consent.enabled` so login renders a tool-selection screen and the chosen tools are enforced on every tools/call
+- Listing `excludedTools` so essential tools are never offered and are always available
+- Honoring `requireSelection` / `defaultSelectedTools` to require a non-empty selection and pre-check tools
+- Pinning `rememberConsent: false` to re-show the screen on every login (the default `true` reuses a prior per-(user, client) selection and only re-prompts when a NEW tool appears)
+
+## Related
+
+- See `configure-auth-modes` for a comparison of all auth modes
+- See `local-self-signed-tokens` for persisting tokens across restarts

package/catalog/frontmcp-config/examples/configure-auth-modes/local-dcr-control.md

@@ -0,0 +1,67 @@
+---
+name: local-dcr-control
+reference: configure-auth-modes
+level: intermediate
+description: 'Lock down the built-in Dynamic Client Registration endpoint with the auth.dcr control surface: disable open registration, allowlist redirect URIs and client ids, and seed a pre-registered trusted client.'
+tags: [config, auth, local, dcr, dynamic-client-registration, security, auth-modes]
+features:
+  - 'Setting `dcr.enabled: false` so `POST /oauth/register` returns 404 and `registration_endpoint` is dropped from AS metadata'
+  - 'Constraining `dcr.allowedRedirectUris` (exact or `*` glob) so unlisted redirect URIs are rejected at both register and authorize'
+  - 'Constraining `dcr.allowedClientIds` so only known client ids may use `/oauth/authorize`'
+  - 'Seeding `dcr.clients` so a trusted client is accepted without any DCR round-trip'
+---
+
+# Lock Down Dynamic Client Registration
+
+Lock down the built-in Dynamic Client Registration endpoint with the auth.dcr control surface: disable open registration, allowlist redirect URIs and client ids, and seed a pre-registered trusted client.
+
+## Code
+
+```typescript
+// src/server.ts
+// JWT_SECRET still signs the HS256 tokens — set a stable value.
+import { FrontMcp } from '@frontmcp/sdk';
+
+@FrontMcp({
+  info: { name: 'internal-api', version: '1.0.0' },
+  auth: {
+    mode: 'local',
+    dcr: {
+      // Close open self-registration entirely (regardless of NODE_ENV).
+      // /oauth/register now responds 404 and AS metadata omits registration_endpoint.
+      enabled: false,
+      // Only these redirect URIs are ever accepted (exact match or simple `*` glob),
+      // enforced at BOTH /oauth/register and /oauth/authorize.
+      allowedRedirectUris: ['https://app.example.com/callback', 'http://localhost:*/callback'],
+      // Only these client ids may use /oauth/authorize.
+      allowedClientIds: ['dashboard'],
+      // Seed the trusted client so authorize accepts it WITHOUT a DCR round-trip.
+      clients: [
+        {
+          clientId: 'dashboard',
+          redirectUris: ['https://app.example.com/callback'],
+          clientName: 'Internal Dashboard',
+        },
+      ],
+    },
+  },
+})
+class Server {}
+```
+
+To keep DCR open but authenticated instead of closed, drop `enabled: false` and set
+`initialAccessToken` — then `POST /oauth/register` requires an
+`Authorization: Bearer <token>` header that matches it (constant-time compared), and
+requests without it get `401 invalid_token`.
+
+## What This Demonstrates
+
+- Setting `dcr.enabled: false` so `POST /oauth/register` returns 404 and `registration_endpoint` is dropped from AS metadata
+- Constraining `dcr.allowedRedirectUris` (exact or `*` glob) so unlisted redirect URIs are rejected at both register and authorize
+- Constraining `dcr.allowedClientIds` so only known client ids may use `/oauth/authorize`
+- Seeding `dcr.clients` so a trusted client is accepted without any DCR round-trip
+
+## Related
+
+- See `configure-auth-modes` for the full local-mode option reference, including the `dcr` block
+- See `local-single-operator` for the smallest single-operator local-mode configuration

package/catalog/frontmcp-config/examples/configure-auth-modes/local-minimal.md

@@ -0,0 +1,62 @@
+---
+name: local-minimal
+reference: configure-auth-modes
+level: basic
+description: 'Stand up the built-in local OAuth 2.1 server with the minimum configuration: HS256 signing via JWT_SECRET and in-memory token storage.'
+tags: [config, auth, local, hs256, auth-modes, modes]
+features:
+  - "Using `mode: 'local'` with no other auth options to run the built-in OAuth 2.1 server"
+  - 'Relying on `JWT_SECRET` for HS256 token signing (symmetric secret, no key pair)'
+  - 'Accepting the default in-memory `tokenStorage` for local development (state is lost on restart)'
+---
+
+# Minimal Local Mode
+
+Stand up the built-in local OAuth 2.1 server with the minimum configuration: HS256 signing via JWT_SECRET and in-memory token storage.
+
+## Code
+
+```typescript
+// src/server.ts
+// Set JWT_SECRET in the environment, e.g. `export JWT_SECRET=$(openssl rand -hex 32)`.
+// If unset, FrontMCP uses a random per-process secret and tokens are invalidated on restart.
+import { App, FrontMcp, Tool, ToolContext, z } from '@frontmcp/sdk';
+
+@Tool({
+  name: 'whoami',
+  description: 'Return the authenticated subject',
+  inputSchema: {},
+  outputSchema: { sub: z.string() },
+})
+class WhoAmITool extends ToolContext {
+  async execute() {
+    return { sub: String(this.auth.claims['sub'] ?? 'unknown') };
+  }
+}
+
+@App({
+  name: 'internal-api',
+  auth: {
+    mode: 'local',
+  },
+  tools: [WhoAmITool],
+})
+class InternalApi {}
+
+@FrontMcp({
+  info: { name: 'local-minimal', version: '1.0.0' },
+  apps: [InternalApi],
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Using `mode: 'local'` with no other auth options to run the built-in OAuth 2.1 server
+- Relying on `JWT_SECRET` for HS256 token signing (symmetric secret, no key pair)
+- Accepting the default in-memory `tokenStorage` for local development (state is lost on restart)
+
+## Related
+
+- See `configure-auth-modes` for a comparison of all auth modes
+- See `local-self-signed-tokens` for persisting tokens with SQLite or Redis

package/catalog/frontmcp-config/examples/configure-auth-modes/local-multi-provider-orchestration.md

@@ -0,0 +1,93 @@
+---
+name: local-multi-provider-orchestration
+reference: configure-auth-modes
+level: advanced
+description: 'Orchestrate multiple upstream OAuth providers (GitHub + Slack) in local mode, gate the JWT until they are linked, and read downstream tokens in tools via this.orchestration.'
+tags: [config, auth, local, orchestration, federated, providers, multi-provider, auth-modes]
+features:
+  - 'Declaring an `auth.providers` array so FrontMCP federates GitHub + Slack at /oauth/authorize and stores their tokens encrypted server-side'
+  - 'Using `authorizeUrl`/`tokenUrl` aliases and letting the per-provider callback URL be auto-computed as ${issuer}/oauth/provider/${id}/callback'
+  - 'Gating JWT issuance with `federatedAuth.minProviders` / `requiredProviders` so no token is minted until the linked-provider threshold is met'
+  - 'Reading downstream provider tokens in a tool via `this.orchestration.getToken(id)` / `tryGetToken(id)` without exposing them to the LLM'
+---
+
+# Multi-Provider Orchestration (Local Mode)
+
+Orchestrate multiple upstream OAuth providers (GitHub + Slack) in local mode, gate the JWT until they are linked, and read downstream tokens in tools via this.orchestration.
+
+## Code
+
+```typescript
+// src/server.ts
+// JWT_SECRET signs the HS256 tokens — set a stable value.
+import { App, FrontMcp, Tool, ToolContext, z } from '@frontmcp/sdk';
+
+@Tool({
+  name: 'github_repos',
+  description: 'List the operator GitHub repositories using the linked upstream token',
+  inputSchema: {},
+  outputSchema: { repos: z.array(z.string()) },
+})
+class GitHubReposTool extends ToolContext {
+  async execute() {
+    // `this.orchestration` is bound for authenticated orchestrated requests.
+    const token = await this.orchestration.getToken('github'); // throws if not linked
+    const res = await fetch('https://api.github.com/user/repos', {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    const repos = (await res.json()) as Array<{ full_name: string }>;
+    return { repos: repos.map((r) => r.full_name) };
+  }
+}
+
+@App({
+  name: 'orchestrated-api',
+  auth: {
+    mode: 'local',
+    // Declare the upstream providers to orchestrate. `authorizeUrl`/`tokenUrl`
+    // are accepted aliases for `authorizationEndpoint`/`tokenEndpoint`.
+    providers: [
+      {
+        id: 'github',
+        authorizeUrl: 'https://github.com/login/oauth/authorize',
+        tokenUrl: 'https://github.com/login/oauth/access_token',
+        clientId: process.env.GITHUB_CLIENT_ID!,
+        clientSecret: process.env.GITHUB_CLIENT_SECRET,
+        scopes: ['read:user', 'repo'],
+      },
+      {
+        id: 'slack',
+        authorizeUrl: 'https://slack.com/oauth/v2/authorize',
+        tokenUrl: 'https://slack.com/api/oauth.v2.access',
+        clientId: process.env.SLACK_CLIENT_ID!,
+        clientSecret: process.env.SLACK_CLIENT_SECRET,
+        scopes: ['users:read'],
+      },
+    ],
+    // No JWT is minted until GitHub (required) is linked.
+    federatedAuth: { minProviders: 1, requiredProviders: ['github'] },
+    tokenStorage: { sqlite: { path: './data/auth.sqlite' } },
+  },
+  tools: [GitHubReposTool],
+})
+class OrchestratedApi {}
+
+@FrontMcp({
+  info: { name: 'orchestrated-server', version: '1.0.0' },
+  apps: [OrchestratedApi],
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Declaring an `auth.providers` array so FrontMCP federates GitHub + Slack at /oauth/authorize and stores their tokens encrypted server-side
+- Using `authorizeUrl`/`tokenUrl` aliases and letting the per-provider callback URL be auto-computed as ${issuer}/oauth/provider/${id}/callback
+- Gating JWT issuance with `federatedAuth.minProviders` / `requiredProviders` so no token is minted until the linked-provider threshold is met
+- Reading downstream provider tokens in a tool via `this.orchestration.getToken(id)` / `tryGetToken(id)` without exposing them to the LLM
+
+## Related
+
+- See `configure-auth` → "Multi-provider orchestration" for the full provider schema and the `this.orchestration` API
+- See `configure-auth-modes` for a comparison of all auth modes
+- See `local-single-operator` for the no-provider single-operator local setup

package/catalog/frontmcp-config/examples/configure-auth-modes/local-self-signed-tokens.md

@@ -2,24 +2,26 @@
 name: local-self-signed-tokens
 reference: configure-auth-modes
 level: intermediate
-description: 'Configure a server that signs its own JWT tokens with consent and incremental auth enabled.'
-tags: [config, auth, redis, local, auth-modes, modes]
+description: 'Configure a local-mode server that signs its own HS256 JWTs and persists auth state across restarts with SQLite or Redis.'
+tags: [config, auth, local, sqlite, redis, auth-modes, modes]
 features:
-  - "Using `mode: 'local'` so the server signs its own JWTs"
+  - "Using `mode: 'local'` so the server signs its own HS256 JWTs (symmetric `JWT_SECRET`, no key pair)"
   - 'Setting `local.issuer` and `expectedAudience` to control token claims'
-  - 'Enabling `consent` for explicit user authorization flow'
-  - 'Enabling `incrementalAuth` to request additional scopes progressively'
-  - 'Using Redis for token storage in production'
+  - 'Persisting authorization codes and refresh tokens with `tokenStorage: { sqlite: { path } }` so they survive restart'
+  - 'Switching the same `tokenStorage` to `{ redis }` for multi-instance deployments'
+  - 'Enabling `consent` so login renders a tool-selection screen and the chosen tools are enforced at call time'
 ---
 
 # Local Self-Signed Tokens
 
-Configure a server that signs its own JWT tokens with consent and incremental auth enabled.
+Configure a local-mode server that signs its own HS256 JWTs and persists auth state across restarts with SQLite or Redis.
 
 ## Code
 
 ```typescript
 // src/server.ts
+// Set a stable JWT_SECRET (e.g. `openssl rand -hex 32`) so HS256-signed
+// tokens survive restart. If unset, a random per-process secret is used.
 import { App, FrontMcp, Tool, ToolContext, z } from '@frontmcp/sdk';
 
 @Tool({
@@ -39,12 +41,13 @@ class ManageUsersTool extends ToolContext {
   auth: {
     mode: 'local',
     local: {
-      issuer: 'my-internal-server',
+      issuer: 'https://mcp.internal.example.com',
     },
     expectedAudience: 'internal-api',
-    tokenStorage: { redis: { host: process.env['REDIS_HOST'] ?? 'localhost', port: 6379 } },
+    // Single-node persistence (survives restart, no Redis required).
+    // For multiple instances, swap for: { redis: { host: ..., port: 6379 } }
+    tokenStorage: { sqlite: { path: './data/auth.sqlite' } },
     consent: { enabled: true },
-    incrementalAuth: { enabled: true },
   },
   tools: [ManageUsersTool],
 })
@@ -53,24 +56,19 @@ class InternalApi {}
 @FrontMcp({
   info: { name: 'local-auth-server', version: '1.0.0' },
   apps: [InternalApi],
-  redis: {
-    provider: 'redis',
-    host: process.env['REDIS_HOST'] ?? 'localhost',
-    port: 6379,
-  },
 })
 class Server {}
 ```
 
 ## What This Demonstrates
 
-- Using `mode: 'local'` so the server signs its own JWTs
+- Using `mode: 'local'` so the server signs its own HS256 JWTs (symmetric `JWT_SECRET`, no key pair)
 - Setting `local.issuer` and `expectedAudience` to control token claims
-- Enabling `consent` for explicit user authorization flow
-- Enabling `incrementalAuth` to request additional scopes progressively
-- Using Redis for token storage in production
+- Persisting authorization codes and refresh tokens with `tokenStorage: { sqlite: { path } }` so they survive restart
+- Switching the same `tokenStorage` to `{ redis }` for multi-instance deployments
+- Enabling `consent` so login renders a tool-selection screen and the chosen tools are enforced at call time
 
 ## Related
 
 - See `configure-auth-modes` for a comparison of all auth modes
-- See `configure-session` for session storage configuration
+- See `configure-session` for transport/session storage configuration

package/catalog/frontmcp-config/examples/configure-auth-modes/local-single-operator.md

@@ -0,0 +1,66 @@
+---
+name: local-single-operator
+reference: configure-auth-modes
+level: basic
+description: 'Run local mode for a single operator (e.g. Claude Code) by skipping the email prompt and minting a stable anonymous subject.'
+tags: [config, auth, local, single-operator, claude-code, auth-modes]
+features:
+  - 'Setting `requireEmail: false` so the login callback mints a code without prompting for an email'
+  - 'Setting `anonymousSubject` so the single operator gets a stable `sub` across logins'
+  - 'Persisting tokens with SQLite so the operator stays logged in across restarts'
+---
+
+# Single-Operator Local Mode
+
+Run local mode for a single operator (e.g. Claude Code) by skipping the email prompt and minting a stable anonymous subject.
+
+## Code
+
+```typescript
+// src/server.ts
+// JWT_SECRET still signs the HS256 tokens — set a stable value.
+import { App, FrontMcp, Tool, ToolContext, z } from '@frontmcp/sdk';
+
+@Tool({
+  name: 'list_notes',
+  description: 'List the operator notes',
+  inputSchema: {},
+  outputSchema: { notes: z.array(z.string()) },
+})
+class ListNotesTool extends ToolContext {
+  async execute() {
+    return { notes: [] };
+  }
+}
+
+@App({
+  name: 'operator-api',
+  auth: {
+    mode: 'local',
+    // Single operator: do not prompt for an email at /oauth/callback.
+    requireEmail: false,
+    // Stable subject minted when no email is supplied (this is the default value).
+    anonymousSubject: 'local-operator',
+    tokenStorage: { sqlite: { path: './data/auth.sqlite' } },
+  },
+  tools: [ListNotesTool],
+})
+class OperatorApi {}
+
+@FrontMcp({
+  info: { name: 'single-operator-server', version: '1.0.0' },
+  apps: [OperatorApi],
+})
+class Server {}
+```
+
+## What This Demonstrates
+
+- Setting `requireEmail: false` so the login callback mints a code without prompting for an email
+- Setting `anonymousSubject` so the single operator gets a stable `sub` across logins
+- Persisting tokens with SQLite so the operator stays logged in across restarts
+
+## Related
+
+- See `configure-auth-modes` for a comparison of all auth modes
+- See `local-minimal` for the smallest local-mode configuration