frontmcp-config · git:20261011.3484b44 · 2026-10-11 · sha256 c1190614fe255625
frontmcp-config git:20261011.3484b44A
Immutable. This exact content never changes and is served at /api/v1/blob/c1190614fe255625.
---
name: frontmcp-config
description: 'Use when configuring a FrontMCP server through frontmcp.config or the @FrontMcp options. Covers auth modes (public, transparent, local, remote), OAuth plus credential vault and secureStore, CORS, HTTP port / entry-path prefix / unix socket, security headers (CSP, HSTS, X-Frame-Options, X-Content-Type-Options), rate limiting / throttling / concurrency / timeout / IP filtering (GuardConfig), session storage (Redis, Vercel KV), client transport protocols (SSE, Streamable HTTP, stateless, protocol presets), elicitation, multi-target build config, and skillsConfig (HTTP catalog, caching, audit log, instruction injection). Triggers: configure auth, set up CORS, add rate limiting, throttle requests, manage sessions, choose transport, set HTTP options, configure JWT or OAuth. The skill for server CONFIGURATION.'
when_to_use: |
Trigger when creating or editing frontmcp.config.ts/js or the @FrontMcp({...})
options: configuring auth modes, OAuth + credential vault, CORS, HTTP port /
entry path / unix socket, security headers, rate limiting / throttling /
GuardConfig, session storage (Redis, Vercel KV), client transport / protocol
presets, elicitation, multi-target builds, or skillsConfig.
paths: '**/frontmcp.config.*'
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://frontmcp.dev/reference
---
# 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/<reference>/`](./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 | Proxy auth to one mandatory upstream IdP, mint a FrontMCP session, read the upstream token. |
| [`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/<file>.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://frontmcp.dev/reference)
- Related skills: `configure-transport`, `configure-http`, `configure-throttle`, `configure-elicitation`, `configure-auth`, `configure-session`, `setup-redis`, `setup-sqlite`