frontmcp-setup

name	frontmcp-setup
description	Use when starting, scaffolding, or organizing a FrontMCP project. Covers creating a new project (CLI scaffold or manual) for Node, Vercel, and other targets; standalone versus Nx-monorepo layout, naming conventions, generators, and dependency rules; composing multiple @App classes, ESM packages, and remote MCP servers into one server; provisioning session and storage backends (Redis, Vercel KV, SQLite with WAL and optional encryption); generating deployment-target-aware README files; and searching, installing, and managing the FrontMCP skill catalog for AI agents (Claude Code, Codex). Triggers: create a new project, how do I start, scaffold, project layout, folder structure, Nx monorepo, add Redis, set up SQLite or a database, compose apps, create a new app, manage skills.
tags	["router","setup","scaffold","project","nx","redis","sqlite","structure","guide"]
category	setup
targets	["all"]
bundle	["recommended","minimal","full"]
priority	10
visibility	both
license	Apache-2.0
metadata	{"docs":"https://docs.agentfront.dev/frontmcp/getting-started/quickstart"}

FrontMCP Setup Router

Entry point for project setup and scaffolding. This skill helps you find the right setup guide based on your project needs — from initial scaffolding to storage backends, project structure, and multi-app composition.

When to Use This Skill

Must Use

• Starting a new FrontMCP project from scratch and need to choose between standalone vs Nx monorepo
• Setting up storage backends (Redis, SQLite) for session or state management
• Organizing an existing project and need canonical directory layout guidance

Recommended

• Onboarding to the FrontMCP project structure and naming conventions
• Setting up multi-app composition within a single server
• Understanding the skills system and how to browse, install, and manage skills

Skip When

• You need to build specific components like tools or resources (see frontmcp-development)
• You need to configure transport, auth, or throttling (see frontmcp-config)
• You need to deploy or build for a target platform (see frontmcp-deployment)

Decision: Use this skill when you need to CREATE or ORGANIZE a project. Use other routers when you need to build, configure, deploy, or test.

Prerequisites

• Node.js 24+ and npm/yarn installed
• frontmcp CLI available globally (npm install -g frontmcp)

Steps

1. Use the Scenario Routing Table below to find the right setup guide for your task
2. Scaffold your project with frontmcp create (standalone) or frontmcp create --nx (monorepo)
3. Configure storage and project structure per the relevant reference files
4. Follow the Recommended Reading Order for a complete setup walkthrough

Scenario Routing Table

Scenario	Reference	Description
Scaffold a new project with frontmcp create	references/setup-project.md	CLI scaffolder (flags: --target, --redis, --skills <bundle>, --cicd, --nx, --pm)
Organize a standalone (non-Nx) project	references/project-structure-standalone.md	File layout, naming conventions (<name>.<type>.ts), folder hierarchy
Organize an Nx monorepo	references/project-structure-nx.md	apps/, libs/, servers/ layout, generators, dependency rules
Set up Redis for production storage	references/setup-redis.md	Docker Redis, Vercel KV, pub/sub for distributed subscriptions (single-server uses in-memory)
Set up SQLite for local development	references/setup-sqlite.md	WAL mode, migration helpers, encryption
Compose multiple apps into one server	references/multi-app-composition.md	@FrontMcp with multiple @App classes, cross-app providers
Use Nx build, test, and CI commands	references/nx-workflow.md	nx build, nx test, nx run-many, caching, affected commands
Browse, install, and manage skills	references/frontmcp-skills-usage.md	CLI commands (search, list, install, read, export, publish), bundles, categories, bulk install
Generate or update project README.md	references/readme-guide.md	Deployment-target-aware README for npm, CLI, Docker, serverless

Recommended Reading Order

1. references/setup-project.md — Start here for any new project
2. references/project-structure-standalone.md or references/project-structure-nx.md — Choose your layout
3. references/setup-redis.md or references/setup-sqlite.md — Add storage if needed
4. references/multi-app-composition.md — Scale to multiple apps (when needed)
5. references/nx-workflow.md — Nx-specific build and CI commands (if using Nx)
6. references/frontmcp-skills-usage.md — Learn the skills system
7. references/readme-guide.md — Generate README for your deployment target

Cross-Cutting Patterns

Pattern	Rule
Project type	Standalone for single-app projects; Nx for multi-app or team projects
File naming	<name>.<type>.ts (e.g., fetch-weather.tool.ts) everywhere
Test naming	.spec.ts extension (not .test.ts)
Entry point	main.ts must export default the @FrontMcp class
Storage choice	Redis for production/serverless; SQLite for local dev/CLI; memory for tests only
App boundaries	Each @App is a self-contained module; shared logic goes in providers

Common Patterns

Pattern	Correct	Incorrect	Why
Project scaffolding	frontmcp create or frontmcp create --nx	Manual setup from scratch	CLI sets up correct structure, dependencies, and config files
Entry point	export default class MyServer in main.ts	Named export or no default export	FrontMCP loads the default export at startup
Storage in production	Redis or platform-native (Vercel KV, DynamoDB)	Memory store or SQLite	Memory is lost on restart; SQLite doesn't work on serverless
Multi-app composition	Separate @App classes composed in @FrontMcp	One giant @App with all components	Separate apps enable independent testing and modular architecture
File organization	Feature folders for 10+ components	Flat tools/ directory with dozens of files	Feature folders make domain boundaries visible

Verification Checklist

Project Structure

• main.ts exists with export default of @FrontMcp class
• At least one @App class registered in the server
• Files follow <name>.<type>.ts naming convention
• Test files use .spec.ts extension

Storage

• Storage backend chosen and configured (Redis/SQLite/memory)
• Connection string in environment variables, not hardcoded
• Storage accessible from the server process

Build and Dev

• frontmcp dev starts successfully with file watching
• frontmcp build --target <target> completes without errors
• Tests pass with frontmcp test or nx test

Troubleshooting

Problem	Cause	Solution
frontmcp create fails	Missing Node.js 24+ or npm/yarn	Install Node.js 24+ and ensure npm/yarn is available
Server fails to start	main.ts missing default export	Add export default MyServerClass to main.ts
Redis connection refused	Redis not running or wrong URL	Start Redis (docker compose up redis) or fix REDIS_URL env var
Nx generator not found	@frontmcp/nx not installed	Run npm install -D @frontmcp/nx
Skills not loading	Skills placed in wrong directory	Catalog skills go in top-level skills/, app skills in src/skills/

Examples

Each reference has matching examples under examples/<reference>/:

frontmcp-skills-usage

Example	Level	Description
bundle-presets-scaffolding	Intermediate	Use --skills flag during project creation to install a skill bundle preset.
install-and-search-skills	Basic	Install skills statically for Claude Code and use dynamic CLI search for on-demand discovery.

multi-app-composition

Example	Level	Description
local-apps-with-shared-tools	Basic	Compose multiple local @App classes into a server with shared tools available to all apps.
per-app-auth-and-isolation	Advanced	Configure mixed authentication modes and scope isolation for different apps in a single server.
remote-and-esm-apps	Intermediate	Compose local, ESM (npm package), and remote (external MCP server) apps into a single gateway.

nx-workflow

Example	Level	Description
build-test-affected	Intermediate	Use Nx commands for efficient building, testing, and CI with affected-only execution.
multi-server-deployment	Advanced	Generate multiple servers in an Nx workspace, each composing different apps for different deployment targets.
scaffold-and-generate	Basic	Initialize an Nx workspace and use generators to scaffold an app with tools, resources, and a server.

project-structure-nx

Example	Level	Description
nx-generator-scaffolding	Basic	Use @frontmcp/nx generators to scaffold tools, resources, and providers within an app, with automatic barrel export updates.
nx-workspace-with-apps	Basic	Scaffold an Nx monorepo with two apps and a server that composes them into a single gateway.
shared-library-usage	Intermediate	Create a shared library in an Nx monorepo and use it from multiple apps to avoid cross-app imports.

project-structure-standalone

Example	Level	Description
dev-workflow-commands	Basic	Run the standard development workflow for a standalone FrontMCP project: dev server, build, and tests.
feature-folder-organization	Intermediate	Organize a growing standalone project into domain-specific feature folders instead of flat type-based directories.
minimal-standalone-layout	Basic	Set up the canonical file structure for a standalone FrontMCP project with one app, one tool, and the required entry point.

readme-guide

Example	Level	Description
node-server-readme	Basic	Generate a README for a FrontMCP server deployed as a Docker/Node.js service with tools and resources.
vercel-deployment-readme	Intermediate	Generate a README for a FrontMCP server deployed to Vercel with Vercel KV storage.

setup-project

Example	Level	Description
basic-node-server	Basic	Scaffold a minimal FrontMCP server with one app and one tool, running on Node.js with HTTP transport.
cli-scaffold-with-flags	Basic	Use the frontmcp create CLI to scaffold a complete project non-interactively with explicit flags for deployment target, Redis, and package manager.
vercel-serverless-server	Intermediate	Configure a FrontMCP server for Vercel deployment with Vercel KV storage and modern transport protocol.

setup-redis

Example	Level	Description
docker-redis-local-dev	Basic	Provision Redis with Docker Compose and connect a FrontMCP server for local session storage.
hybrid-vercel-kv-with-pubsub	Advanced	Use Vercel KV for session storage and a separate Redis instance for pub/sub resource subscriptions in distributed multi-instance deployments.
vercel-kv-serverless	Intermediate	Configure a FrontMCP server with Vercel KV as the session store for serverless deployment.

setup-sqlite

Example	Level	Description
basic-sqlite-setup	Basic	Configure a FrontMCP server with SQLite for local session storage with WAL mode enabled.
encrypted-sqlite-storage	Intermediate	Enable AES-256-GCM at-rest encryption for sensitive session data stored in SQLite.
unix-socket-daemon	Advanced	Configure a FrontMCP daemon that listens on a unix socket and uses SQLite for persistent storage.

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-setup/ 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-setup, frontmcp skills read frontmcp-setup:references/<file>.md, frontmcp skills install frontmcp-setup — 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-setup/SKILL.md, skill://frontmcp-setup/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

• Getting Started
• Domain routers: frontmcp-development, frontmcp-deployment, frontmcp-testing, frontmcp-config, frontmcp-guides