agentfront/frontmcp-config

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:

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>/:

configure-auth-modes

| Example | Level | Description | | --------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------- | | local-self-signed-tokens | Intermediate | Configure a server that signs its own JWT tokens with consent and incremental auth enabled. | | remote-enterprise-oauth | Advanced | Proxy auth to one mandatory upstream IdP, mint a FrontMCP session, read the upstream token. | | transparent-jwt-validation | Basic | Validate externally-issued JWTs without managing token lifecycle on the server. |

configure-auth

| Example | Level | Description | | --------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | multi-app-auth | 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 | Basic | Set up a FrontMCP server with public (unauthenticated) access and anonymous scopes. | | remote-oauth-with-vault | 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 | Basic | Request user confirmation before executing a destructive action. | | distributed-elicitation-redis | Intermediate | Configure elicitation with Redis storage for multi-instance production deployments. |

configure-http

| Example | Level | Description | | ----------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------ | | cors-restricted-origins | Basic | Configure CORS to allow only specific frontend origins with credentials. | | entry-path-reverse-proxy | Intermediate | Mount the MCP server under a URL prefix for reverse proxy or multi-service setups. | | unix-socket-local | 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 | Intermediate | Use unique key prefixes when multiple FrontMCP servers share one Redis instance. | | redis-session-store | Basic | Configure Redis-backed session storage for production deployments. | | vercel-kv-session | Intermediate | Configure Vercel KV for session storage in serverless Vercel deployments. |

configure-throttle-guard-config

| Example | Level | Description | | -------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------ | | full-guard-config | Advanced | Complete GuardConfig using every available field for maximum protection. | | minimal-guard-config | Basic | Enable throttle with just a global rate limit and default timeout. |

configure-throttle

| Example | Level | Description | | ------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------- | | distributed-redis-throttle | Advanced | Configure Redis-backed rate limiting for multi-instance deployments behind a load balancer. | | per-tool-rate-limit | Intermediate | Override server defaults with per-tool rate limits and concurrency caps. | | server-level-rate-limit | Basic | Configure global rate limits and IP filtering at the server level. |

configure-transport-protocol-presets

| Example | Level | Description | | --------------------------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------- | | legacy-preset-nodejs | Basic | Use the default legacy preset for maximum compatibility with all MCP clients. | | stateless-api-serverless | Intermediate | Use the stateless-api preset for Vercel, Lambda, or Cloudflare Workers. |

configure-transport

| Example | Level | Description | | -------------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------- | | custom-protocol-flags | Advanced | Override individual protocol flags instead of using a preset for fine-grained control. | | distributed-sessions-redis | Intermediate | Configure transport with Redis persistence for multi-instance load-balanced deployments. | | stateless-serverless | Basic | Configure stateless transport for Vercel, Lambda, or Cloudflare deployments. |

configure-deployment-targets

| Example | Level | Description | | ----------------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------- | | multi-target-with-security | Intermediate | Configure a FrontMCP project with node + distributed targets, CSP headers, and HSTS | | distributed-ha-config | Advanced | Configure a distributed deployment target with HA settings for heartbeat, session takeover, and Redis-backed session persistence | | json-schema-ide-support | Basic | Use frontmcp.config.json with JSON Schema for VS Code and WebStorm autocomplete |

configure-security-headers

| Example | Level | Description | | --------------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------- | | csp-report-only | Basic | Test CSP policies in report-only mode to identify violations before enforcement | | full-production-headers | 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
• Related skills: configure-transport, configure-http, configure-throttle, configure-elicitation, configure-auth, configure-session, setup-redis, setup-sqlite