@frontmcp/skills 1.0.0-beta.13 → 1.0.0-beta.14

package/catalog/frontmcp-production-readiness/examples/production-vercel/stateless-serverless-design.md

@@ -0,0 +1,91 @@
+---
+name: stateless-serverless-design
+reference: production-vercel
+level: advanced
+description: 'Shows a fully stateless server design that works on Vercel edge runtime with no Node.js-only APIs, using `@frontmcp/utils` for cross-platform crypto.'
+tags: [production, vercel, serverless, node, stateless, design]
+features:
+  - 'Using `@frontmcp/utils` (`sha256Hex`, `randomUUID`) instead of `node:crypto` for edge compatibility'
+  - 'Fully stateless design with no in-memory state between invocations'
+  - 'Using `this.fetch()` instead of Node.js `http`/`https` modules'
+  - 'No file system access (serverless is ephemeral)'
+---
+
+# Stateless Serverless Design with Edge Compatibility
+
+Shows a fully stateless server design that works on Vercel edge runtime with no Node.js-only APIs, using `@frontmcp/utils` for cross-platform crypto.
+
+## Code
+
+```typescript
+// src/tools/edge-safe-tool.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+// Use @frontmcp/utils for cross-platform crypto — not node:crypto
+import { sha256Hex, randomUUID } from '@frontmcp/utils';
+
+@Tool({
+  name: 'process_request',
+  description: 'Process a request in an edge-safe, stateless manner',
+  inputSchema: {
+    data: z.string().min(1).describe('Request data'),
+  },
+  outputSchema: {
+    requestId: z.string(),
+    hash: z.string(),
+    processed: z.boolean(),
+  },
+})
+export class ProcessRequestTool extends ToolContext {
+  async execute(input: { data: string }) {
+    // Cross-platform crypto — works on edge runtime
+    const requestId = randomUUID();
+    const hash = sha256Hex(input.data);
+
+    // No file system access — serverless is ephemeral
+    // No in-memory state — each invocation is independent
+    // Use this.fetch() for external calls (not node http/https)
+    const response = await this.fetch('https://api.example.com/process', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ requestId, hash, data: input.data }),
+    });
+
+    const result = await response.json();
+    return { requestId, hash, processed: result.ok };
+  }
+}
+```
+
+```typescript
+// src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { EdgeApp } from './edge.app';
+
+@FrontMcp({
+  info: { name: 'edge-server', version: '1.0.0' },
+  apps: [EdgeApp],
+
+  // Vercel KV for all shared state
+  redis: { provider: 'vercel-kv' },
+
+  // CORS restricted to production domain
+  cors: {
+    origin: ['https://app.example.com'],
+  },
+
+  // Stateless: no file system, no SQLite, no in-memory sessions
+})
+export default class EdgeServer {}
+```
+
+## What This Demonstrates
+
+- Using `@frontmcp/utils` (`sha256Hex`, `randomUUID`) instead of `node:crypto` for edge compatibility
+- Fully stateless design with no in-memory state between invocations
+- Using `this.fetch()` instead of Node.js `http`/`https` modules
+- No file system access (serverless is ephemeral)
+
+## Related
+
+- See `production-vercel` for the full edge runtime and scaling checklist

package/catalog/frontmcp-production-readiness/examples/production-vercel/vercel-edge-config.md

@@ -0,0 +1,78 @@
+---
+name: vercel-edge-config
+reference: production-vercel
+level: basic
+description: 'Shows how to configure a FrontMCP server for Vercel deployment with Vercel KV for session storage and correct route configuration.'
+tags: [production, vercel-kv, vercel, session, serverless, edge]
+features:
+  - 'Correct `vercel.json` with function routes, memory limits, and max duration'
+  - "Using Vercel KV (`provider: 'vercel-kv'`) for session storage instead of in-memory"
+  - 'Setting CORS origins dynamically using `VERCEL_URL`'
+  - 'Serverless function entry point via `createVercelHandler`'
+---
+
+# Vercel Configuration with Edge-Compatible Storage
+
+Shows how to configure a FrontMCP server for Vercel deployment with Vercel KV for session storage and correct route configuration.
+
+## Code
+
+```jsonc
+// vercel.json
+{
+  "version": 2,
+  "builds": [{ "src": "api/**/*.ts", "use": "@vercel/node" }],
+  "routes": [{ "src": "/mcp/(.*)", "dest": "/api/mcp" }],
+  "functions": {
+    "api/mcp.ts": {
+      "memory": 256,
+      "maxDuration": 30,
+    },
+  },
+}
+```
+
+```typescript
+// src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { MyApp } from './my.app';
+
+@FrontMcp({
+  info: { name: 'vercel-mcp', version: '1.0.0' },
+  apps: [MyApp],
+
+  // Vercel KV for session storage (not in-memory, not Redis directly)
+  redis: {
+    provider: 'vercel-kv', // Uses Vercel KV (Redis-compatible, managed)
+  },
+
+  // CORS: use VERCEL_URL or custom domain
+  cors: {
+    origin: [
+      process.env.VERCEL_URL ? `https://${process.env.VERCEL_URL}` : 'http://localhost:3000',
+      'https://app.example.com',
+    ],
+  },
+})
+export default class VercelMcpServer {}
+```
+
+```typescript
+// api/mcp.ts — Vercel serverless function entry point
+import Server from '../src/main';
+
+// Export the server class directly — FrontMCP handles
+// the Vercel serverless function lifecycle automatically.
+export default Server;
+```
+
+## What This Demonstrates
+
+- Correct `vercel.json` with function routes, memory limits, and max duration
+- Using Vercel KV (`provider: 'vercel-kv'`) for session storage instead of in-memory
+- Setting CORS origins dynamically using `VERCEL_URL`
+- Serverless function entry point via `createVercelHandler`
+
+## Related
+
+- See `production-vercel` for the full Vercel deployment checklist

package/catalog/frontmcp-production-readiness/references/common-checklist.md

@@ -154,3 +154,13 @@ These checks apply to ALL deployment targets. Run them first, then proceed to yo
 | Synchronous file I/O      | Use async operations from `@frontmcp/utils` |
 | Hardcoded secrets         | Use environment variables                   |
 | Unbounded caching         | Set TTL on all caches                       |
+
+## Examples
+
+| Example                                                                              | Level        | Description                                                                                                                |
+| ------------------------------------------------------------------------------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------- |
+| [`caching-and-performance`](../examples/common-checklist/caching-and-performance.md) | Advanced     | Shows how to configure caching with TTL, optimize responses, and manage memory with proper provider lifecycle cleanup.     |
+| [`observability-setup`](../examples/common-checklist/observability-setup.md)         | Intermediate | Shows how to configure structured logging, error handling with MCP error codes, and monitoring integration for production. |
+| [`security-hardening`](../examples/common-checklist/security-hardening.md)           | Basic        | Shows how to configure authentication, CORS, input validation, and rate limiting for a production FrontMCP server.         |
+
+> See all examples in [`examples/common-checklist/`](../examples/common-checklist/)

package/catalog/frontmcp-production-readiness/references/production-browser.md

@@ -44,3 +44,13 @@ Target-specific checklist for publishing FrontMCP as a browser-compatible SDK.
 - [ ] Code splitting is used for large optional features
 - [ ] No synchronous operations that block the main thread
 - [ ] WebSocket/SSE connections handle reconnection gracefully
+
+## Examples
+
+| Example                                                                                  | Level        | Description                                                                                                                                                |
+| ---------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`browser-bundle-config`](../examples/production-browser/browser-bundle-config.md)       | Basic        | Shows how to configure package.json for browser-compatible SDK distribution with ESM/CJS/UMD entry points, TypeScript declarations, and CDN support.       |
+| [`cross-platform-crypto`](../examples/production-browser/cross-platform-crypto.md)       | Intermediate | Shows how to use `@frontmcp/utils` for cross-platform crypto operations that work in both browser and Node.js, and how to avoid Node.js-only APIs.         |
+| [`security-and-performance`](../examples/production-browser/security-and-performance.md) | Advanced     | Shows how to ensure no secrets are bundled in browser code, configure CSP headers on the server, optimize bundle size, and avoid blocking the main thread. |
+
+> See all examples in [`examples/production-browser/`](../examples/production-browser/)

package/catalog/frontmcp-production-readiness/references/production-cli-binary.md

@@ -60,3 +60,12 @@ Checklist for publishing FrontMCP as a one-shot CLI binary — runs a command, p
 - [ ] No secrets logged to stderr
 - [ ] No hardcoded paths (use `os.homedir()`, `os.tmpdir()`)
 - [ ] No writes to unexpected locations
+
+## Examples
+
+| Example                                                                                                 | Level        | Description                                                                                                                                  |
+| ------------------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`binary-build-config`](../examples/production-cli-binary/binary-build-config.md)                       | Basic        | Shows how to configure a FrontMCP CLI binary with correct package.json `bin` field, shebang, stdio transport, and npm distribution settings. |
+| [`stdio-transport-error-handling`](../examples/production-cli-binary/stdio-transport-error-handling.md) | Intermediate | Shows how to handle stdin/stdout transport correctly, implement proper exit codes, and handle edge cases like EOF and broken pipes.          |
+
+> See all examples in [`examples/production-cli-binary/`](../examples/production-cli-binary/)

package/catalog/frontmcp-production-readiness/references/production-cli-daemon.md

@@ -59,3 +59,13 @@ Checklist for deploying FrontMCP as a long-running local MCP server managed by t
 - [ ] No network exposure (socket-only, not TCP)
 - [ ] Secrets stored in config file with `600` permissions
 - [ ] Config stored in `~/.config/<app>/` or XDG directories
+
+## Examples
+
+| Example                                                                                       | Level        | Description                                                                                                                                                                                   |
+| --------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`daemon-socket-config`](../examples/production-cli-daemon/daemon-socket-config.md)           | Basic        | Shows how to configure a FrontMCP server as a long-running local daemon with Unix socket transport, process management, and SQLite storage.                                                   |
+| [`graceful-shutdown-cleanup`](../examples/production-cli-daemon/graceful-shutdown-cleanup.md) | Intermediate | Shows how to implement graceful shutdown for a daemon process, including completing in-flight requests, closing database connections, removing the socket file, and cleaning up the PID file. |
+| [`security-and-permissions`](../examples/production-cli-daemon/security-and-permissions.md)   | Advanced     | Shows how to secure a local daemon with restrictive socket permissions, XDG-compliant config storage, and file-based secret management.                                                       |
+
+> See all examples in [`examples/production-cli-daemon/`](../examples/production-cli-daemon/)

package/catalog/frontmcp-production-readiness/references/production-cloudflare.md

@@ -50,3 +50,13 @@ Target-specific checklist for deploying FrontMCP to Cloudflare Workers.
 - [ ] Secrets set via `wrangler secret put`
 - [ ] Deploy with `wrangler deploy` (not manual upload)
 - [ ] Tail logs: `wrangler tail` for production debugging
+
+## Examples
+
+| Example                                                                                           | Level        | Description                                                                                                                                               |
+| ------------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`durable-objects-state`](../examples/production-cloudflare/durable-objects-state.md)             | Advanced     | Shows how to use Cloudflare Durable Objects for stateful coordination alongside the stateless Workers runtime, with KV for cache and R2 for blob storage. |
+| [`workers-runtime-constraints`](../examples/production-cloudflare/workers-runtime-constraints.md) | Intermediate | Shows how to write tools that are compatible with the Cloudflare Workers runtime: no Node.js APIs, no eval, only async I/O, and using Web APIs.           |
+| [`wrangler-config`](../examples/production-cloudflare/wrangler-config.md)                         | Basic        | Shows how to configure `wrangler.toml` with correct routes, KV bindings for session storage, and secret management for a FrontMCP Cloudflare Worker.      |
+
+> See all examples in [`examples/production-cloudflare/`](../examples/production-cloudflare/)

package/catalog/frontmcp-production-readiness/references/production-lambda.md

@@ -51,3 +51,13 @@ Target-specific checklist for deploying FrontMCP to AWS Lambda.
 - [ ] Staging and production stages are separate
 - [ ] API Gateway stages are configured correctly
 - [ ] CloudWatch alarms are set for errors and throttling
+
+## Examples
+
+| Example                                                                                       | Level        | Description                                                                                                                                                                              |
+| --------------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`cold-start-connection-reuse`](../examples/production-lambda/cold-start-connection-reuse.md) | Intermediate | Shows how to minimize Lambda cold starts with lazy initialization, tree-shaking, and the connection reuse pattern for external services.                                                 |
+| [`sam-template`](../examples/production-lambda/sam-template.md)                               | Basic        | Shows a complete SAM/CloudFormation template for deploying a FrontMCP server to AWS Lambda with API Gateway routing, DynamoDB for session storage, and proper environment configuration. |
+| [`scaling-and-monitoring`](../examples/production-lambda/scaling-and-monitoring.md)           | Advanced     | Shows how to configure concurrency limits, dead letter queues, provisioned concurrency, and CloudWatch alarms for a production Lambda deployment.                                        |
+
+> See all examples in [`examples/production-lambda/`](../examples/production-lambda/)

package/catalog/frontmcp-production-readiness/references/production-node-sdk.md

@@ -64,3 +64,13 @@ const result = await client.callTool('my_tool', { input: 'value' });
 await client.close();
 await server.dispose();
 ```
+
+## Examples
+
+| Example                                                                               | Level        | Description                                                                                                                                                                       |
+| ------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`basic-sdk-lifecycle`](../examples/production-node-sdk/basic-sdk-lifecycle.md)       | Basic        | Shows the complete lifecycle of a FrontMCP SDK package used as an embedded client: initialization, tool invocation, and proper cleanup.                                           |
+| [`multi-instance-cleanup`](../examples/production-node-sdk/multi-instance-cleanup.md) | Advanced     | Shows how multiple SDK instances can coexist without conflicts, and how to implement proper cleanup to prevent memory leaks from event listeners, timers, and provider resources. |
+| [`package-json-config`](../examples/production-node-sdk/package-json-config.md)       | Intermediate | Shows the correct package.json configuration for publishing a FrontMCP SDK package with CJS + ESM entry points, peer dependencies, and proper file inclusions.                    |
+
+> See all examples in [`examples/production-node-sdk/`](../examples/production-node-sdk/)

package/catalog/frontmcp-production-readiness/references/production-node-server.md

@@ -59,3 +59,13 @@ Target-specific checklist for deploying FrontMCP as a long-running Node.js serve
 - [ ] Env vars are validated at startup (fail fast on missing config)
 - [ ] Port binding uses `process.env.PORT`
 - [ ] No dev dependencies installed in production image
+
+## Examples
+
+| Example                                                                                | Level        | Description                                                                                                                                         |
+| -------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`docker-multi-stage`](../examples/production-node-server/docker-multi-stage.md)       | Basic        | Shows a production-ready Dockerfile with multi-stage build, non-root user, and container health check for a FrontMCP Node.js server.                |
+| [`graceful-shutdown`](../examples/production-node-server/graceful-shutdown.md)         | Intermediate | Shows how to implement graceful shutdown with SIGTERM handling, in-flight request draining, and health check status transitions.                    |
+| [`redis-session-scaling`](../examples/production-node-server/redis-session-scaling.md) | Advanced     | Shows how to configure Redis-backed session storage, connection pooling, and stateless server design for horizontal scaling behind a load balancer. |
+
+> See all examples in [`examples/production-node-server/`](../examples/production-node-server/)

package/catalog/frontmcp-production-readiness/references/production-vercel.md

@@ -50,3 +50,13 @@ Target-specific checklist for deploying FrontMCP to Vercel serverless or edge fu
 - [ ] Environment variables are set in Vercel project settings
 - [ ] Preview deployments test the full MCP flow
 - [ ] Production deployment uses `npx vercel --prod`
+
+## Examples
+
+| Example                                                                                       | Level        | Description                                                                                                                                           |
+| --------------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`cold-start-optimization`](../examples/production-vercel/cold-start-optimization.md)         | Intermediate | Shows how to minimize cold start time by lazy-loading dependencies, avoiding heavy initialization at module scope, and caching expensive operations.  |
+| [`stateless-serverless-design`](../examples/production-vercel/stateless-serverless-design.md) | Advanced     | Shows a fully stateless server design that works on Vercel edge runtime with no Node.js-only APIs, using `@frontmcp/utils` for cross-platform crypto. |
+| [`vercel-edge-config`](../examples/production-vercel/vercel-edge-config.md)                   | Basic        | Shows how to configure a FrontMCP server for Vercel deployment with Vercel KV for session storage and correct route configuration.                    |
+
+> See all examples in [`examples/production-vercel/`](../examples/production-vercel/)

package/catalog/frontmcp-setup/examples/frontmcp-skills-usage/bundle-presets-scaffolding.md

@@ -0,0 +1,61 @@
+---
+name: bundle-presets-scaffolding
+reference: frontmcp-skills-usage
+level: intermediate
+description: 'Use `--skills` flag during project creation to install a skill bundle preset.'
+tags: [setup, skills, usage, bundle, presets, scaffolding]
+features:
+  - '`--skills` flag accepts `recommended`, `minimal`, `full`, or `none` presets'
+  - 'Static installs are snapshots; re-run `install` to update to the latest catalog version'
+  - 'Hybrid approach: install core skills statically, search the rest on demand'
+  - 'Fewer static installs reduce token usage in AI agent context'
+---
+
+# Bundle Presets During Scaffolding
+
+Use `--skills` flag during project creation to install a skill bundle preset.
+
+## Code
+
+```bash
+# Recommended bundle (core skills for the deployment target)
+npx frontmcp create my-app --skills recommended --yes
+
+# Minimal bundle (just project setup + create-tool)
+npx frontmcp create my-app --skills minimal --yes
+
+# Full bundle (all skills)
+npx frontmcp create my-app --skills full --yes
+
+# No skills
+npx frontmcp create my-app --skills none --yes
+```
+
+```bash
+# After scaffolding, update installed skills to the latest version
+frontmcp skills install frontmcp-development --provider claude
+frontmcp skills install frontmcp-config --provider claude
+```
+
+```bash
+# Recommended hybrid strategy:
+# 1. Install 2-4 core skills statically for daily use
+frontmcp skills install frontmcp-setup --provider claude
+frontmcp skills install frontmcp-development --provider claude
+
+# 2. Search everything else on demand (saves tokens)
+frontmcp skills search "deploy to vercel"
+frontmcp skills search "rate limiting"
+frontmcp skills read frontmcp-deployment
+```
+
+## What This Demonstrates
+
+- `--skills` flag accepts `recommended`, `minimal`, `full`, or `none` presets
+- Static installs are snapshots; re-run `install` to update to the latest catalog version
+- Hybrid approach: install core skills statically, search the rest on demand
+- Fewer static installs reduce token usage in AI agent context
+
+## Related
+
+- See `frontmcp-skills-usage` for the full skill catalog, provider directories, and CLI command reference

package/catalog/frontmcp-setup/examples/frontmcp-skills-usage/install-and-search-skills.md

@@ -0,0 +1,83 @@
+---
+name: install-and-search-skills
+reference: frontmcp-skills-usage
+level: basic
+description: 'Install skills statically for Claude Code and use dynamic CLI search for on-demand discovery.'
+tags: [setup, cli, anthropic, skills, usage, install]
+features:
+  - '`frontmcp skills list` and `search` for discovering available skills'
+  - '`frontmcp skills read` for viewing skill content and references on demand'
+  - '`frontmcp skills install --provider claude` for static installation to `.claude/skills/`'
+  - 'Installed skills are auto-loaded by Claude Code in its system prompt context'
+---
+
+# Install and Search Skills
+
+Install skills statically for Claude Code and use dynamic CLI search for on-demand discovery.
+
+## Code
+
+```bash
+# List all available skills
+frontmcp skills list
+
+# List skills by category
+frontmcp skills list --category development
+frontmcp skills list --category deployment
+frontmcp skills list --category config
+
+# Search skills by keywords
+frontmcp skills search "authentication oauth"
+frontmcp skills search "deploy vercel"
+frontmcp skills search "plugin hooks" --tag middleware --limit 5
+
+# Read a skill's full content
+frontmcp skills read frontmcp-development
+
+# List references for a skill
+frontmcp skills read frontmcp-development --refs
+
+# Read a specific reference
+frontmcp skills read frontmcp-development create-tool
+```
+
+```bash
+# Install core skills for Claude Code
+frontmcp skills install frontmcp-setup --provider claude
+frontmcp skills install frontmcp-development --provider claude
+frontmcp skills install frontmcp-config --provider claude
+
+# Install for Codex
+frontmcp skills install frontmcp-development --provider codex
+
+# Install to a custom directory
+frontmcp skills install frontmcp-guides --dir ./my-skills
+```
+
+After installation, the directory structure:
+
+```text
+my-project/
+  .claude/
+    skills/
+      frontmcp-setup/
+        SKILL.md
+        references/
+      frontmcp-development/
+        SKILL.md
+        references/
+      frontmcp-config/
+        SKILL.md
+        references/
+```
+
+## What This Demonstrates
+
+- `frontmcp skills list` and `search` for discovering available skills
+- `frontmcp skills read` for viewing skill content and references on demand
+- `frontmcp skills install --provider claude` for static installation to `.claude/skills/`
+- Installed skills are auto-loaded by Claude Code in its system prompt context
+
+## Related
+
+- See `frontmcp-skills-usage` for static vs dynamic comparison, bundle presets, and token optimization

package/catalog/frontmcp-setup/examples/multi-app-composition/local-apps-with-shared-tools.md

@@ -0,0 +1,87 @@
+---
+name: local-apps-with-shared-tools
+reference: multi-app-composition
+level: basic
+description: 'Compose multiple local `@App` classes into a server with shared tools available to all apps.'
+tags: [setup, multi-app, local, multi, app, composition]
+features:
+  - 'Multiple `@App` classes with unique `id` fields for tool namespacing (`billing:charge`, `inventory:check_stock`)'
+  - 'Server-level `tools` array for shared tools available to all apps without namespace prefix'
+  - 'Each app is self-contained with its own tools array'
+  - 'The `id` field on `@App` controls the namespace prefix for tool names'
+---
+
+# Local Apps with Shared Tools
+
+Compose multiple local `@App` classes into a server with shared tools available to all apps.
+
+## Code
+
+```typescript
+// src/apps/billing.app.ts
+import { App } from '@frontmcp/sdk';
+import { ChargeTool } from '../tools/charge.tool';
+import { RefundTool } from '../tools/refund.tool';
+
+@App({
+  id: 'billing',
+  name: 'Billing',
+  tools: [ChargeTool, RefundTool],
+})
+export class BillingApp {}
+```
+
+```typescript
+// src/apps/inventory.app.ts
+import { App } from '@frontmcp/sdk';
+import { CheckStockTool } from '../tools/check-stock.tool';
+
+@App({
+  id: 'inventory',
+  name: 'Inventory',
+  tools: [CheckStockTool],
+})
+export class InventoryApp {}
+```
+
+```typescript
+// src/tools/health-check.tool.ts
+import { Tool, ToolContext } from '@frontmcp/sdk';
+
+@Tool({
+  name: 'health_check',
+  description: 'Check server health',
+})
+export default class HealthCheckTool extends ToolContext {
+  async execute() {
+    return { content: [{ type: 'text', text: 'OK' }] };
+  }
+}
+```
+
+```typescript
+// src/main.ts
+import 'reflect-metadata';
+import { FrontMcp } from '@frontmcp/sdk';
+import { BillingApp } from './apps/billing.app';
+import { InventoryApp } from './apps/inventory.app';
+import HealthCheckTool from './tools/health-check.tool';
+
+@FrontMcp({
+  info: { name: 'gateway', version: '1.0.0' },
+  apps: [BillingApp, InventoryApp],
+  tools: [HealthCheckTool],
+})
+export default class Server {}
+```
+
+## What This Demonstrates
+
+- Multiple `@App` classes with unique `id` fields for tool namespacing (`billing:charge`, `inventory:check_stock`)
+- Server-level `tools` array for shared tools available to all apps without namespace prefix
+- Each app is self-contained with its own tools array
+- The `id` field on `@App` controls the namespace prefix for tool names
+
+## Related
+
+- See `multi-app-composition` for ESM apps, remote apps, scope isolation, and per-app auth

package/catalog/frontmcp-setup/examples/multi-app-composition/per-app-auth-and-isolation.md

@@ -0,0 +1,88 @@
+---
+name: per-app-auth-and-isolation
+reference: multi-app-composition
+level: advanced
+description: 'Configure mixed authentication modes and scope isolation for different apps in a single server.'
+tags: [setup, oauth, auth, multi-app, remote, multi]
+features:
+  - 'Per-app `auth` overrides the server-level auth (public vs remote OAuth per app)'
+  - '`standalone: true` fully isolates the Admin app (not visible in parent tool listing)'
+  - "`standalone: 'includeInParent'` gives Analytics its own scope but keeps tools visible"
+  - 'Per-app `plugins` (BillingAuditPlugin) are scoped to that app only'
+  - 'Server-level `plugins` (TracingPlugin, PiiRedactionPlugin) apply to all apps'
+---
+
+# Per-App Auth and Scope Isolation
+
+Configure mixed authentication modes and scope isolation for different apps in a single server.
+
+## Code
+
+```typescript
+// src/main.ts
+import 'reflect-metadata';
+import { FrontMcp, App } from '@frontmcp/sdk';
+
+// Public app - no auth required
+@App({
+  name: 'Public',
+  tools: [EchoTool, HealthTool],
+  auth: { mode: 'public' },
+})
+class PublicApp {}
+
+// Protected app with OAuth
+@App({
+  id: 'billing',
+  name: 'Billing',
+  tools: [ChargeTool, RefundTool],
+  plugins: [BillingAuditPlugin],
+  auth: {
+    mode: 'remote',
+    idpProviderUrl: 'https://auth.billing.com',
+    idpExpectedAudience: 'billing-api',
+  },
+})
+class BillingApp {}
+
+// Fully isolated admin app (standalone: true)
+@App({
+  name: 'Admin',
+  tools: [ResetTool, UserManagementTool],
+  standalone: true,
+  auth: {
+    mode: 'remote',
+    idpProviderUrl: 'https://auth.admin.com',
+  },
+})
+class AdminApp {}
+
+// Isolated but visible in parent (standalone: 'includeInParent')
+@App({
+  id: 'analytics',
+  name: 'Analytics',
+  tools: [QueryTool],
+  standalone: 'includeInParent',
+})
+class AnalyticsApp {}
+
+@FrontMcp({
+  info: { name: 'gateway', version: '1.0.0' },
+  apps: [PublicApp, BillingApp, AdminApp, AnalyticsApp],
+  plugins: [TracingPlugin, PiiRedactionPlugin],
+  auth: { mode: 'public' },
+})
+export default class Server {}
+```
+
+## What This Demonstrates
+
+- Per-app `auth` overrides the server-level auth (public vs remote OAuth per app)
+- `standalone: true` fully isolates the Admin app (not visible in parent tool listing)
+- `standalone: 'includeInParent'` gives Analytics its own scope but keeps tools visible
+- Per-app `plugins` (BillingAuditPlugin) are scoped to that app only
+- Server-level `plugins` (TracingPlugin, PiiRedactionPlugin) apply to all apps
+
+## Related
+
+- See `multi-app-composition` for ESM and remote app composition, namespacing, and shared tools