--- name: frontmcp-config description: 'Use when you want to configure auth, set up CORS, add rate limiting, throttle requests, manage sessions, choose transport, set HTTP options, add authentication, configure JWT, or set up OAuth. The skill for server CONFIGURATION.' tags: [router, config, transport, http, auth, session, redis, sqlite, throttle, guide] category: config targets: [all] bundle: [recommended, full] priority: 10 visibility: both license: Apache-2.0 metadata: docs: https://docs.agentfront.dev/frontmcp/fundamentals/overview --- # FrontMCP Configuration Router Entry point for configuring FrontMCP servers. This skill helps you find the right configuration reference (under `references/`) based on what aspect of your server you need to set up. ## When to Use This Skill ### Must Use - Setting up a new server and need to understand which configuration options exist - Deciding between authentication modes, transport protocols, or storage backends - Planning server configuration across transport, auth, throttling, and storage ### Recommended - Looking up which reference covers a specific config option (CORS, rate limits, session TTL, etc.) - Understanding how configuration layers work (server-level vs app-level vs tool-level) - Reviewing the full configuration surface area before production deployment ### Skip When - You already know which config area to change (go directly to `configure-transport`, `configure-auth`, etc.) - You need to build components, not configure the server (see `frontmcp-development`) - You need to deploy, not configure (see `frontmcp-deployment`) > **Decision:** Use this skill when you need to figure out WHAT to configure. Open the matching reference under `references/` directly when you already know. ## Prerequisites - A FrontMCP project scaffolded with `frontmcp create` (see `frontmcp-setup`) - Node.js 24+ and npm/yarn installed ## Steps 1. Identify the configuration area you need using the Scenario Routing Table below 2. Navigate to the specific configuration reference (e.g., `references/configure-transport.md`, `references/configure-auth.md`) for detailed instructions 3. Apply the configuration in your `@FrontMcp` or `@App` decorator 4. Verify using the Verification Checklist at the end of this skill ## Scenario Routing Table | Scenario | Reference | Description | | -------------------------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------- | | Choose between SSE, Streamable HTTP, or stdio | `configure-transport` | Transport protocol selection with distributed session options | | Set up CORS, port, base path, or request limits | `configure-http` | HTTP server options for Streamable HTTP and SSE transports | | Add rate limiting, concurrency, or IP filtering | `configure-throttle` | Server-level and per-tool throttle configuration | | Enable tools to ask users for input | `configure-elicitation` | Elicitation schemas, stores, and multi-step flows | | Set up authentication (public, transparent, local, remote) | `configure-auth` | OAuth flows, credential vault, multi-app auth | | Configure session storage backends | `configure-session` | Memory, Redis, Vercel KV, and custom session stores | | Add Redis for production storage | `setup-redis` | Docker Redis, Vercel KV, pub/sub for distributed subscriptions | | Add SQLite for local development | `setup-sqlite` | SQLite with WAL mode, migration helpers | | Understand auth mode details (public/transparent/local/remote) | `configure-auth-modes` | Authentication mode details (public, transparent, local, remote) | | Fine-tune guard configuration for throttling | `configure-throttle-guard-config` | Advanced guard configuration for throttling | | Use transport protocol presets | `configure-transport-protocol-presets` | Transport protocol preset configurations | | Configure multi-target deployments and frontmcp.config.ts | `configure-deployment-targets` | Typed config with defineConfig(), 9 deployment targets, JSON schema | | Add CSP, HSTS, X-Frame-Options, and other security headers | `configure-security-headers` | CSP directives, report-only mode, HSTS preload, custom headers | | Configure skills HTTP, instructions injection, or audit log | `configure-skills-http` | Full `skillsConfig` reference: auth, cache, instructions, audit log | | Split apps into separate scopes (`splitByApp`) | `decorators-guide` | Per-app scope and basePath isolation on `@FrontMcp` | | Enable widget-to-host communication (ext-apps) | `decorators-guide` | `extApps` host capabilities, session validation, widget comms | | Enable background jobs and workflows | `decorators-guide` | `jobs: { enabled: true, store? }` on `@FrontMcp` | | Configure pagination for list operations | `decorators-guide` | `pagination` defaults for `tools/list` endpoint | | Configure npm/ESM package loader for remote apps | `decorators-guide` | `loader` config for `App.esm()` / `App.remote()` resolution | ## Configuration Layers FrontMCP configuration cascades through three layers: ```text Server (@FrontMcp) ← Global defaults └── App (@App) ← App-level overrides └── Tool (@Tool) ← Per-tool overrides ``` | Setting | Server (`@FrontMcp`) | App (`@App`) | Tool (`@Tool`) | | --------------------- | -------------------------------- | --------------------- | ------------------------------------------- | | Transport | Yes | No | No | | HTTP (CORS, port) | Yes | No | No | | Throttle (rate limit) | Yes (`throttle` global defaults) | No | Yes (`rateLimit`, `concurrency`, `timeout`) | | Auth mode | Yes | Yes (override) | No | | Auth providers | No | Yes (`authProviders`) | Yes (`authProviders`) | | Session store | Yes | No | No | | Elicitation | Yes (enable: `elicitation`) | No | Yes (usage: `this.elicit()`) | | ExtApps | Yes | No | No | | Jobs / Workflows | Yes (`jobs: { enabled }`) | No | No | | Pagination | Yes | No | No | | SplitByApp | Yes | No | No | ## Cross-Cutting Patterns | Pattern | Rule | | ------------------- | ------------------------------------------------------------------------------------------------- | | Auth + session | Auth mode determines session requirements: `remote` needs Redis/KV; `public` can use memory | | Transport + storage | Stateless transports (serverless) require distributed storage; stateful (Node) can use in-process | | Throttle scope | Server-level throttle applies to all tools; per-tool throttle overrides for specific tools | | Environment config | Use environment variables for all secrets (API keys, Redis URLs, OAuth credentials) | | Config validation | FrontMCP validates config at startup; invalid config throws before the server starts | ## Common Patterns | Pattern | Correct | Incorrect | Why | | -------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | | Auth mode for dev | `auth: { mode: 'public' }` or `auth: { mode: 'transparent', provider: '...' }` locally | `auth: { mode: 'remote', ... }` with real OAuth in dev | Remote auth requires a running OAuth provider; public/transparent are simpler for local dev | | Session store | Redis for production, memory for development | Memory for production | Memory sessions are lost on restart and don't work across serverless invocations | | Rate limit placement | Server-level for global limits, per-tool for expensive operations | Only server-level | Some tools are cheap (list) and some are expensive (generate); per-tool limits prevent abuse of expensive tools | | CORS config | Explicit allowed origins in production | `cors: { origin: '*' }` in production | Wildcard CORS allows any origin to call your server | | Config secrets | `process.env.REDIS_URL` via environment variable | Hardcoded `redis://localhost:6379` in source | Hardcoded secrets leak to git and break in different environments | ## Verification Checklist ### Transport and HTTP - [ ] Transport protocol configured and server starts without errors - [ ] CORS allows expected origins (test with browser or curl) - [ ] Port and base path accessible from client ### Authentication - [ ] Auth mode set appropriately for the environment (public/transparent for dev, remote for prod) - [ ] OAuth credentials stored in environment variables, not source code - [ ] Session store configured with appropriate backend (memory for dev, Redis for prod) ### Throttle and Security - [ ] Global rate limit configured to prevent abuse - [ ] Expensive tools have per-tool throttle overrides - [ ] IP allow/deny lists configured if needed ### Storage - [ ] Redis or SQLite configured and connectable - [ ] Storage persists across server restarts (not memory in production) ## Troubleshooting | Problem | Cause | Solution | | --------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | | Server fails to start with config error | Invalid or missing required config field | Check the error message; FrontMCP validates config at startup and reports the specific invalid field | | CORS blocked in browser | Missing or incorrect CORS origin config | Add the client's origin to `http.cors.origin`; see `configure-http` | | Rate limit too aggressive | Global limit applied to all tools | Add per-tool overrides for cheap tools with higher limits; see `configure-throttle` | | Sessions lost on serverless | Using memory session store on stateless platform | Switch to Redis or Vercel KV; see `configure-session` | | Auth callback fails | OAuth redirect URI mismatch | Ensure the redirect URI registered with your OAuth provider matches the server's `/oauth/callback` endpoint; see `configure-auth` | ## Examples Each reference has matching examples under [`examples//`](./examples/): ### `configure-auth-modes` | Example | Level | Description | | --------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------- | | [`local-self-signed-tokens`](./examples/configure-auth-modes/local-self-signed-tokens.md) | Intermediate | Configure a server that signs its own JWT tokens with consent and incremental auth enabled. | | [`remote-enterprise-oauth`](./examples/configure-auth-modes/remote-enterprise-oauth.md) | Advanced | Delegate authentication to an external OAuth orchestrator with Redis-backed token storage. | | [`transparent-jwt-validation`](./examples/configure-auth-modes/transparent-jwt-validation.md) | Basic | Validate externally-issued JWTs without managing token lifecycle on the server. | ### `configure-auth` | Example | Level | Description | | --------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`multi-app-auth`](./examples/configure-auth/multi-app-auth.md) | Advanced | Configure a single FrontMCP server with multiple apps, each using a different auth mode -- public for open endpoints and remote for admin endpoints. | | [`public-mode-setup`](./examples/configure-auth/public-mode-setup.md) | Basic | Set up a FrontMCP server with public (unauthenticated) access and anonymous scopes. | | [`remote-oauth-with-vault`](./examples/configure-auth/remote-oauth-with-vault.md) | Intermediate | 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-elicitation` | Example | Level | Description | | ---------------------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------- | | [`basic-confirmation-gate`](./examples/configure-elicitation/basic-confirmation-gate.md) | Basic | Request user confirmation before executing a destructive action. | | [`distributed-elicitation-redis`](./examples/configure-elicitation/distributed-elicitation-redis.md) | Intermediate | Configure elicitation with Redis storage for multi-instance production deployments. | ### `configure-http` | Example | Level | Description | | ----------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------ | | [`cors-restricted-origins`](./examples/configure-http/cors-restricted-origins.md) | Basic | Configure CORS to allow only specific frontend origins with credentials. | | [`entry-path-reverse-proxy`](./examples/configure-http/entry-path-reverse-proxy.md) | Intermediate | Mount the MCP server under a URL prefix for reverse proxy or multi-service setups. | | [`unix-socket-local`](./examples/configure-http/unix-socket-local.md) | Intermediate | Bind the server to a unix socket instead of a TCP port for local-only communication. | ### `configure-session` | Example | Level | Description | | ------------------------------------------------------------------------------------ | ------------ | -------------------------------------------------------------------------------- | | [`multi-server-key-prefix`](./examples/configure-session/multi-server-key-prefix.md) | Intermediate | Use unique key prefixes when multiple FrontMCP servers share one Redis instance. | | [`redis-session-store`](./examples/configure-session/redis-session-store.md) | Basic | Configure Redis-backed session storage for production deployments. | | [`vercel-kv-session`](./examples/configure-session/vercel-kv-session.md) | Intermediate | Configure Vercel KV for session storage in serverless Vercel deployments. | ### `configure-throttle-guard-config` | Example | Level | Description | | -------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------ | | [`full-guard-config`](./examples/configure-throttle-guard-config/full-guard-config.md) | Advanced | Complete GuardConfig using every available field for maximum protection. | | [`minimal-guard-config`](./examples/configure-throttle-guard-config/minimal-guard-config.md) | Basic | Enable throttle with just a global rate limit and default timeout. | ### `configure-throttle` | Example | Level | Description | | ------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------- | | [`distributed-redis-throttle`](./examples/configure-throttle/distributed-redis-throttle.md) | Advanced | Configure Redis-backed rate limiting for multi-instance deployments behind a load balancer. | | [`per-tool-rate-limit`](./examples/configure-throttle/per-tool-rate-limit.md) | Intermediate | Override server defaults with per-tool rate limits and concurrency caps. | | [`server-level-rate-limit`](./examples/configure-throttle/server-level-rate-limit.md) | Basic | Configure global rate limits and IP filtering at the server level. | ### `configure-transport-protocol-presets` | Example | Level | Description | | --------------------------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------- | | [`legacy-preset-nodejs`](./examples/configure-transport-protocol-presets/legacy-preset-nodejs.md) | Basic | Use the default legacy preset for maximum compatibility with all MCP clients. | | [`stateless-api-serverless`](./examples/configure-transport-protocol-presets/stateless-api-serverless.md) | Intermediate | Use the stateless-api preset for Vercel, Lambda, or Cloudflare Workers. | ### `configure-transport` | Example | Level | Description | | -------------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------- | | [`custom-protocol-flags`](./examples/configure-transport/custom-protocol-flags.md) | Advanced | Override individual protocol flags instead of using a preset for fine-grained control. | | [`distributed-sessions-redis`](./examples/configure-transport/distributed-sessions-redis.md) | Intermediate | Configure transport with Redis persistence for multi-instance load-balanced deployments. | | [`stateless-serverless`](./examples/configure-transport/stateless-serverless.md) | Basic | Configure stateless transport for Vercel, Lambda, or Cloudflare deployments. | ### `configure-deployment-targets` | Example | Level | Description | | ----------------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------- | | [`multi-target-with-security`](./examples/configure-deployment-targets/multi-target-with-security.md) | Intermediate | Configure a FrontMCP project with node + distributed targets, CSP headers, and HSTS | | [`distributed-ha-config`](./examples/configure-deployment-targets/distributed-ha-config.md) | Advanced | Configure a distributed deployment target with HA settings for heartbeat, session takeover, and Redis-backed session persistence | | [`json-schema-ide-support`](./examples/configure-deployment-targets/json-schema-ide-support.md) | Basic | Use frontmcp.config.json with JSON Schema for VS Code and WebStorm autocomplete | ### `configure-security-headers` | Example | Level | Description | | --------------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------- | | [`csp-report-only`](./examples/configure-security-headers/csp-report-only.md) | Basic | Test CSP policies in report-only mode to identify violations before enforcement | | [`full-production-headers`](./examples/configure-security-headers/full-production-headers.md) | Intermediate | Complete security headers configuration for production with CSP enforcement, HSTS preload, and clickjacking protection | ## Accessing This Skill Skills are distributed as plain SKILL.md files plus a sibling `references/` and `examples/` tree, so consumers can pick whichever access mode fits: | Mode | How it works | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Filesystem** | Read `libs/skills/catalog/frontmcp-config/` directly from a clone of the catalog repo, or from a published `@frontmcp/skills` install. SKILL.md is the entry point. | | **`frontmcp` CLI** | `frontmcp skills list`, `frontmcp skills read frontmcp-config`, `frontmcp skills read frontmcp-config:references/.md`, `frontmcp skills install frontmcp-config` — no server required. | | **MCP `skill://`** | When a developer mounts this skill into their own FrontMCP server (`@FrontMcp({ skills: [...] })`), the SDK exposes it via SEP-2640 resources: `skill://frontmcp-config/SKILL.md`, `skill://frontmcp-config/references/{file}.md`, etc. The server’s `skill://index.json` returns the SEP-2640 discovery document for everything mounted on it. | The catalog itself is **not** an MCP server. The `skill://` URIs only resolve when a server has been configured to host this skill. ## Reference - [FrontMCP Overview](https://docs.agentfront.dev/frontmcp/fundamentals/overview) - Related skills: `configure-transport`, `configure-http`, `configure-throttle`, `configure-elicitation`, `configure-auth`, `configure-session`, `setup-redis`, `setup-sqlite`