@frontmcp/skills 1.2.1 → 1.4.0

package/catalog/frontmcp-config/examples/configure-auth/local-secure-store.md

@@ -0,0 +1,138 @@
+---
+name: local-secure-store
+reference: configure-auth
+level: intermediate
+description: 'Configure the general session secure-secret store (this.secureStore) with a pluggable backing (memory / sqlite / redis / custom OS-keychain) and read/write user-typed secrets from a tool.'
+tags: [config, auth, local, secure-store, secrets, this-secure-store, keychain]
+features:
+  - 'Selecting the secure-store backing via `auth.secureStore` (memory / sqlite / redis / custom backend) plus a namespace `scope`'
+  - 'Reading/writing arbitrary user-typed secrets from a tool via `this.secureStore.set/get/list/delete` (JSON-serialized, scoped to the session/subject)'
+  - 'Backing the store with an OS keychain by supplying a `SecureStoreBackend` — no native dependency is bundled by the framework'
+  - 'Understanding scope: `user` (keyed by sub, default), `session` (keyed by sessionId), `global` (server-wide)'
+---
+
+# Local Mode with the Session Secure-Secret Store (`this.secureStore`)
+
+Configure the general session secure-secret store (this.secureStore) with a pluggable backing (memory / sqlite / redis / custom OS-keychain) and read/write user-typed secrets from a tool.
+
+The store is distinct from `this.credentials` (which is OAuth-credential-centric):
+use `this.secureStore` for arbitrary secrets like an API key a tool prompts for.
+The built-in backings encrypt at rest with AES-256-GCM, and an OS keychain can be
+plugged in without the framework bundling any native dependency.
+
+## Code
+
+```typescript
+// src/server.ts
+import { App, FrontMcp, Tool, ToolContext, z, type SecureStoreConfig } from '@frontmcp/sdk';
+
+@Tool({
+  name: 'set_api_key',
+  description: 'Store a user-typed API key in the session secure store',
+  inputSchema: { apiKey: z.string() },
+  outputSchema: { saved: z.boolean(), keys: z.array(z.string()) },
+})
+class SetApiKeyTool extends ToolContext {
+  async execute(input: { apiKey: string }) {
+    // Values are JSON-serialized and encrypted at rest (built-in backings),
+    // scoped to the current `sub` (user scope, the default).
+    await this.secureStore.set('stg.api-key', input.apiKey);
+    const keys = await this.secureStore.list();
+    return { saved: true, keys };
+  }
+}
+
+@Tool({
+  name: 'read_api_key',
+  description: 'Read the stored API key (presence only — never returns the raw secret)',
+  inputSchema: {},
+  outputSchema: { present: z.boolean() },
+})
+class ReadApiKeyTool extends ToolContext {
+  async execute() {
+    const apiKey = await this.secureStore.get<string>('stg.api-key');
+    // Never return the raw secret to the model — only presence.
+    return { present: apiKey !== undefined };
+  }
+}
+
+@App({ name: 'Secrets', tools: [SetApiKeyTool, ReadApiKeyTool] })
+class SecretsApp {}
+
+// Pick the backing per deployment. Default ('memory') is encrypted in-process.
+const secureStore: SecureStoreConfig = {
+  sqlite: { path: './.frontmcp/secrets.sqlite' }, // survives restart
+  scope: 'user', // 'user' (default) | 'session' | 'global'
+};
+
+@FrontMcp({
+  info: { name: 'secure-store-demo', version: '0.1.0' },
+  apps: [SecretsApp],
+  auth: {
+    mode: 'local',
+    secureStore,
+    login: {
+      title: 'Sign in',
+      fields: { apiKey: { type: 'password', label: 'API Key', required: true } },
+      subject: { fromField: 'apiKey', strategy: 'per-account' },
+    },
+    authenticate: async (input) => {
+      if (!input.fields['apiKey']) return { ok: false, message: 'API key required', retryField: 'apiKey' };
+      return { ok: true };
+    },
+  },
+})
+export default class Server {}
+```
+
+## What This Demonstrates
+
+- Selecting the secure-store backing via `auth.secureStore` (memory / sqlite / redis / custom backend) plus a namespace `scope`
+- Reading/writing arbitrary user-typed secrets from a tool via `this.secureStore.set/get/list/delete` (JSON-serialized, scoped to the session/subject)
+- Backing the store with an OS keychain by supplying a `SecureStoreBackend` — no native dependency is bundled by the framework
+- Understanding scope: `user` (keyed by sub, default), `session` (keyed by sessionId), `global` (server-wide)
+
+## Optional: back the store with an OS keychain (pluggable, not bundled)
+
+FrontMCP does **not** ship `keytar`/`wincred`/`libsecret`. Supply an object
+implementing `SecureStoreBackend` and the framework uses it as-is (no framework
+crypto — an OS keychain is encrypted by the OS):
+
+```typescript
+import type { SecureStoreBackend } from '@frontmcp/sdk';
+
+// import keytar from 'keytar'; // YOU add the native peer-dep
+
+const keychainBackend: SecureStoreBackend = {
+  async get(namespace, key) {
+    return (await keytar.getPassword(`frontmcp:${namespace}`, key)) ?? null;
+  },
+  async set(namespace, key, value /*, ttlMs */) {
+    await keytar.setPassword(`frontmcp:${namespace}`, key, value); // ttlMs ignored
+  },
+  async delete(namespace, key) {
+    return keytar.deletePassword(`frontmcp:${namespace}`, key);
+  },
+  async list(/* namespace */) {
+    const creds = await keytar.findCredentials('frontmcp');
+    return creds.map((c) => c.account);
+  },
+};
+
+// auth: { mode: 'local', secureStore: { backend: keychainBackend, scope: 'global' } }
+```
+
+## Notes
+
+- **Backings**: `'memory'` (default, encrypted in-process), `{ sqlite: { path } }`,
+  `{ redis: { ... } }`, or `{ backend }` (custom). The persistent built-ins reuse
+  the same `StorageAdapter`/`VaultEncryption` as `tokenStorage`; when the backing
+  matches `tokenStorage` the same connection is shared.
+- **Scope**: `user` keys by `sub` (anonymous requests read empty / skip writes),
+  `session` keys by `sessionId`, `global` shares one server-wide namespace. The
+  identity is hashed into the namespace — never stored raw.
+- **API**: `get<T>(key)`, `set<T>(key, value, { ttlMs? })`, `delete(key)`,
+  `list()`. Object configs also accept `ttlMs` and `encryption.pepper`
+  (overrides `VAULT_SECRET ?? JWT_SECRET`).
+- **Never return raw secrets to the model** — expose presence/redacted previews
+  only, as `read_api_key` does above.

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