frontmcp

The FrontMCP command-line tool. It creates a project, runs it with hot reload, tests it, and builds it for Node, a single executable, Vercel, AWS Lambda, Cloudflare Workers or an MCP Bundle (.mcpb). It also runs servers in the background, installs MCP apps, and installs FrontMCP's skills for coding agents.

FrontMCP is a TypeScript framework for building Model Context Protocol (MCP) servers: you write tools, resources and prompts as decorated classes with @frontmcp/sdk, and this package is the tooling around them.

Quick start

npx frontmcp create my-app
cd my-app
npm install
npm run dev

create asks for a deployment target, a Redis setup and CI workflows (--yes takes the defaults), and doesn't install packages. npm run dev runs frontmcp dev, and the server answers at http://localhost:3000/mcp. Point the MCP Inspector (npm run inspect) or any MCP client at it, then follow Learn on frontmcp.dev.

Install

npm install -D frontmcp   # in a project (frontmcp create adds it for you)
npm install -g frontmcp   # or globally
npx frontmcp <command>    # or without installing

Requires Node.js 24 or later. To add FrontMCP to a project you already have, see Installation.

Commands

Development

| Command | Description | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------ | | frontmcp create [name] | Scaffold a new FrontMCP project (interactive when name is omitted) | | frontmcp init | Create or fix a tsconfig.json with the decorator settings FrontMCP needs | | frontmcp doctor | Check the Node and npm versions and the tsconfig.json | | frontmcp dev | Run the server with hot reload (tsx --watch) and a type check in the background | | frontmcp dev --stdio | Run dev as a stdio bridge, for an MCP client that starts the server itself | | frontmcp build | Build every deployment in frontmcp.config, or the node target without a config | | frontmcp build --target <target> | Build one target: node, cli, sdk, browser, vercel, lambda, cloudflare, distributed or mcpb | | frontmcp test [patterns...] | Run E2E tests with an injected Jest configuration | | frontmcp inspector | Launch the MCP Inspector |

Process Manager

| Command | Description | | ---------------------------------- | ------------------------------------------------------------ | | frontmcp start <name> | Start a named MCP server with supervisor | | frontmcp stop <name> | Stop a managed server (graceful by default) | | frontmcp restart <name> | Restart a managed server | | frontmcp status [name] | Show process status (detail if name given, table if omitted) | | frontmcp list | List all managed processes | | frontmcp logs <name> | Tail log output for a managed server | | frontmcp socket <entry> | Serve a local MCP server on a Unix socket | | frontmcp service <action> [name] | Install/uninstall systemd/launchd service |

Package Manager

| Command | Description | | --------------------------- | ----------------------------------------------- | | frontmcp install <source> | Install an MCP app from npm, local path, or git | | frontmcp uninstall <name> | Remove an installed MCP app | | frontmcp configure <name> | Re-run setup questionnaire for an installed app |

Skills

Skills teach a coding agent, such as Claude Code or Codex, how to build with FrontMCP. The catalog ships in @frontmcp/skills.

| Command | Description | | ----------------------------------------------- | ---------------------------------------------------------------------------------------- | | frontmcp skills search <query> | Search the catalog | | frontmcp skills list | List the skills in the catalog | | frontmcp skills install [name] | Install skills into .claude/skills or .codex/skills (--all, --tag, --category) | | frontmcp skills read <nameOrPath> [reference] | Print a skill, one of its references, or a file in its folder | | frontmcp skills export | Turn a catalog skill into a Cursor, Windsurf or Copilot rule file | | frontmcp skills publish <name> | Publish a skill to Smithery or Glama |

MCP Clients

| Command | Description | | ------------------------------------ | ------------------------------------------------------------------------------------------------- | | frontmcp eject-mcp-config <client> | Print an MCP config snippet for claude-code, claude-desktop, cursor, windsurf or vscode | | frontmcp plugin install | Install this server as a Claude Code plugin (--claude) or a Codex MCP server (--codex) | | frontmcp plugin status | Show what plugin install installed, per provider | | frontmcp plugin uninstall | Remove what plugin install wrote |

MCP Bundles (MCPB)

| Command | Description | | ------------------------------- | ---------------------------------------------------------------------- | | frontmcp build --target mcpb | Package the server into a .mcpb archive (MCPB v0.3 spec) | | frontmcp mcpb validate <path> | Verify an existing .mcpb archive against the MCPB v0.3 specification |

MCP Registry

Publish the server to the MCP Registry. The CLI speaks the Registry's API itself: no mcp-publisher binary is needed.

| Command | Description | | ------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | frontmcp registry keygen | Create the Ed25519 key that proves your domain; print MCP_REGISTRY_PUBLIC_KEY and the DNS record | | frontmcp registry publish --dry-run | Build server.json, validate it, and print it alone on stdout (diagnostics go to stderr) | | frontmcp registry publish | Validate, log in (HTTP proof by default), and publish this version | | frontmcp registry status <status> | Mark one version (--server-version) or every version (--all-versions) active, deprecated, or deleted |

server.json comes from @FrontMcp({ info, registry }) (name, description, title, version, website, icons), package.json (description and repository fallbacks, the npm package), and the registry block of frontmcp.config:

export default defineConfig({
  name: 'weather',
  deployments: [{ target: 'node' }],
  registry: {
    url: 'https://mcp.example.com/mcp', // remotes[0]; --url overrides it
    packages: ['npm'], // list package.json's name and version; needs "mcpName" in package.json
    registryUrl: 'https://staging.registry.modelcontextprotocol.io', // --registry overrides it
  },
});

Options Reference

General

| Flag | Description | | --------------------- | ------------------------------------------------------------------------- | | -V, --version | Print version | | -h, --help | Print help | | -c, --config <path> | Use this frontmcp.config file instead of searching for one | | --list-commands | List every command, built-in and project-defined |

Dev

| Flag | Description | Default | | --------------------------- | -------------------------------------------------------------- | ------------------- | | -e, --entry <path> | Entry file path | auto-detected | | -p, --port <port> | Port to listen on | 3000 | | --auto-port | If the port is busy, use the next free one | false | | --show-conflict | When the port is busy, print the process holding it | false | | --stdio | Run as a stdio bridge for an MCP client | false | | --serve | With --stdio, talk to the server over a pipe instead of HTTP | false | | --log-file <path> | Bridge log file | .frontmcp/dev.log | | --buffer-size <n> | Requests held while the server reloads | 8 | | --reload-deadline-ms <ms> | How long to wait for a reload | 30000 |

Build

| Flag | Description | Default | | ----------------------- | ---------------------------------------------------------------------------------- | ------------- | | -t, --target <target> | One target (see Commands); without it, every configured deployment | — | | -o, --out-dir <dir> | Output directory; each target writes to <dir>/<target>/ | dist | | -e, --entry <path> | Entry file path | auto-detected | | --js | cli target: a JavaScript bundle instead of a single executable | false | | --sea | mcpb target: add a single-executable binary for this platform | false | | --merge-from <dir> | mcpb target: add single-executable binaries built on other platforms | — | | --icon <path> | mcpb target: the icon to put in the archive | — | | --no-deterministic | mcpb target: don't make the archive reproducible | — | | --stage-only | mcpb target: keep the staging folder and skip the zip | false | | --no-clean | Keep what's already in the output folder | — |

Start

| Flag | Description | Default | | --------------------- | ----------------------------- | ------- | | -e, --entry <path> | Entry file for the server | — | | -p, --port <N> | Port number | — | | -s, --socket <path> | Unix socket path | — | | --db <path> | SQLite database path | — | | --max-restarts <N> | Maximum auto-restart attempts | 5 |

Stop

| Flag | Description | | ------------- | --------------------------------------- | | -f, --force | Force kill (SIGKILL instead of SIGTERM) |

Logs

| Flag | Description | Default | | ----------------- | ---------------------------------- | ------- | | -F, --follow | Follow log output (like tail -f) | false | | -n, --lines <N> | Number of lines to show | 50 |

Socket

| Flag | Description | Default | | --------------------- | ------------------------------------------- | -------------------------------- | | -s, --socket <path> | Unix socket path | ~/.frontmcp/sockets/{app}.sock | | --db <path> | SQLite database path for persistence | — | | -b, --background | Run as background daemon (detached process) | false |

Install

| Flag | Description | | ------------------ | ---------------------------------------------- | | --registry <url> | npm registry URL for private packages | | -y, --yes | Silent mode (use defaults, skip questionnaire) | | -p, --port <N> | Override default port |

Create

| Flag | Description | Default | | -------------------- | ------------------------------------------------------------ | ------------- | | -y, --yes | Use defaults (non-interactive mode) | false | | --target <target> | Deployment target: node, vercel, lambda, cloudflare | node | | --redis <setup> | Redis setup: docker, existing, none (node target only) | docker | | --pm <pm> | Package manager: npm, yarn, pnpm | detected | | --cicd / --no-cicd | Enable/disable GitHub Actions CI/CD | true | | --nx | Scaffold an Nx monorepo instead of standalone project | false | | --skills <bundle> | Skills to install: recommended, minimal, full, none | recommended |

Test

| Flag | Description | Default | | -------------------- | -------------------------------------------- | ------- | | -i, --runInBand | Run tests sequentially (recommended for E2E) | false | | -w, --watch | Run tests in watch mode | false | | -v, --verbose | Show verbose test output | false | | -t, --timeout <ms> | Set test timeout | 60000 | | --no-env | Don't load .env or .env.local | — | | -c, --coverage | Collect test coverage | false |

Registry

| Flag | Commands | Description | | ---------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------- | | -o, --out <file> | keygen | Key file (default ~/.frontmcp/keys/mcp-registry.key, written with mode 0600) | | --force | keygen | Replace an existing key file | | --auth <method> | publish, status | http (default), dns, or github-oidc (GitHub Actions, io.github.* names) | | --domain <domain> | publish, status | Domain that serves the proof (default: the name's namespace reversed) | | --key-file <path> | publish, status | Private key, hex seed or PEM (default: env MCP_REGISTRY_PRIVATE_KEY, else ~/.frontmcp/keys/mcp-registry.key) | | --registry <url> | publish, status | Registry base URL, HTTPS or http://localhost (default: registry.registryUrl, else the official Registry) | | -e, --entry <path> | publish, status | Entry file with the @FrontMcp() class | | --file <path> | publish | Publish this server.json as is | | --url <url> | publish | Streamable HTTP URL of the deployed server (remotes[0]) | | --dry-run | publish | Print server.json on stdout and the validation result on stderr; don't log in or publish | | --server-version <version> | status | The version to change | | --all-versions | status | Change every version (one of the two is required) | | --message <text> | status | Reason shown with deprecated or deleted (at most 500 characters) | | --name <name> | status | Server name (default: registry.name in @FrontMcp()) |

Examples

Project Scaffolding

npx frontmcp create                           # Interactive mode
npx frontmcp create my-mcp --yes              # Use defaults
npx frontmcp create my-mcp --target vercel    # Vercel deployment
npx frontmcp create my-mcp --nx --pm yarn     # Nx monorepo with yarn

Development Workflow

frontmcp dev                        # Start dev server with hot reload
frontmcp build --out-dir build      # Production build
frontmcp test --runInBand           # Run E2E tests sequentially
frontmcp doctor                     # Verify environment setup
frontmcp inspector                  # Launch MCP Inspector UI

Executable Builds

frontmcp build --target node        # Bundle plus a runner script; run it where node_modules is
frontmcp build --target cli         # Single executable with a subcommand per tool
frontmcp build --target cli --js    # The same CLI as a JavaScript bundle

MCP Bundles (.mcpb)

The mcpb target produces a ZIP archive that can be loaded directly into Claude Desktop (and other MCPB-aware clients) without any install step — the host app extracts the archive and starts the server via stdio.

frontmcp build --target mcpb                         # basic node bundle
frontmcp build --target mcpb --sea                   # include a SEA binary for this OS/arch
frontmcp build --target mcpb --merge-from ./ci-bins  # merge pre-built cross-platform binaries
frontmcp build --target mcpb --stage-only            # leave the staging directory for inspection
frontmcp mcpb validate dist/mcpb/myapp-1.0.0.mcpb    # verify an archive

frontmcp.config:

import { defineConfig } from 'frontmcp';

export default defineConfig({
  name: 'my-server',
  version: '1.2.3',
  deployments: [
    {
      target: 'mcpb',
      displayName: 'My Server',
      author: { name: 'Acme', email: '[email protected]' },
      license: 'Apache-2.0',
      homepage: 'https://acme.dev/my-server',
      repository: 'https://github.com/acme/my-server',
      icon: 'assets/icon.png',
      compatibility: {
        claude_desktop: '>=1.0.0',
        platforms: ['darwin', 'linux', 'win32'],
        runtimes: { node: '>=24.0.0' },
      },
      sea: { enabled: true },
    },
  ],
});

Fields not declared in the deployment fall back to the project package.json (name, version, description, author, license, homepage, repository, keywords). Every userConfig entry, and every top-level setup.steps question, becomes an MCPB user_config entry that reaches the server as an environment variable through ${user_config.KEY} substitution in mcp_config.env. The variable is the entry's env (or the step's env), else the key in UPPER_SNAKE_CASE (deskApiKey → DESK_API_KEY). The deployment's env is merged in too, and a user's answer wins over it. Conditional visibility / branching steps (showWhen, next) have no MCPB equivalent — the generator logs a warning and renders them unconditionally.

Cross-platform SEA binaries require a CI matrix build (Node SEA only builds for the host OS/arch in a single pass). Use --merge-from <dir> to assemble pre-built binaries organized as {mergeFromDir}/{platform}/{appName}[.exe].

Generated CLI Features

frontmcp build --target cli turns the server into a command-line program, dist/cli/<name>, whose commands come from the server's tools, resources, prompts and resource templates. Without --js it's a single executable that runs without node_modules. Its --help groups the commands:

Tool subcommands — each MCP tool becomes a kebab-case subcommand with flags generated from its input schema:

./myapp search-users --query "alice" --limit 10
./myapp send-email --to "[email protected]" --body '{"html": true}'

An object field takes a JSON string; an array field takes the flag once per value (--tags a --tags b).

Resources & Prompts:

./myapp resource list                          # List available resources
./myapp resource read "file://config.json"     # Read a resource by URI
./myapp template list                          # List resource templates
./myapp template user-profile --user-id 42     # Read a template with parameters
./myapp prompt list                            # List available prompts
./myapp prompt get greeting --name "Alice"     # Render a prompt with arguments

Auth & Sessions (only with cli.authRequired: true):

./myapp login --server https://auth.example.com   # OAuth PKCE login
./myapp logout --all                               # Clear all stored credentials
./myapp sessions list                              # List saved sessions
./myapp sessions switch production                 # Switch active session
./myapp connect --token <TOKEN>                    # Connect with a bearer token

Subscriptions:

./myapp subscribe resource "file://config.json"   # Stream resource updates
./myapp subscribe notification "db/changed"        # Stream named notifications

System:

./myapp serve --port 3000         # Start the MCP server over HTTP
./myapp serve --stdio             # Start the MCP server over stdio
./myapp daemon start              # Start as background daemon
./myapp daemon stop               # Stop the daemon
./myapp daemon status             # Show daemon status
./myapp daemon logs               # Tail daemon logs
./myapp doctor                    # Check runtime dependencies
./myapp install                   # Install to ~/.frontmcp/ (or, with -p, as an IDE plugin)
./myapp uninstall                 # Remove what install added

A server with skills also gets skills list, skills search, skills read and skills load.

Global options: --output <text|json> sets the output format (the default comes from cli.outputDefault); --verbose and --log-dir <path> control logging.

Tool name conflict resolution: if a tool name collides with a built-in command (e.g., login, serve), the tool subcommand is automatically suffixed with -tool (e.g., login-tool).

Auth token injection: when cli.authRequired is true in config, the active session's stored token is sent with every tool/resource/prompt call, and those commands refuse to run (exit 1) until login or connect --token has stored one.

frontmcp.config — cli deployment options

The cli block of a cli deployment controls the generated program:

import { defineConfig } from 'frontmcp';

export default defineConfig({
  name: 'myapp',
  version: '1.0.0',
  deployments: [
    {
      target: 'cli',
      cli: {
        description: 'My MCP CLI', // the line under "Usage:" in --help
        outputDefault: 'text', // 'text' | 'json'
        authRequired: false, // true adds login/logout/sessions/connect
        excludeTools: [], // tool names to leave out
        oauth: {
          serverUrl: 'https://auth.example.com',
          clientId: 'my-app',
          defaultScope: 'read write',
          portRange: [17830, 17850], // local callback port range
        },
      },
    },
  ],
});

Process Management

frontmcp start my-app --entry ./src/main.ts --port 3005
frontmcp status                     # Table of all processes
frontmcp status my-app              # Detail for one process
frontmcp logs my-app --follow       # Tail logs
frontmcp restart my-app
frontmcp stop my-app
frontmcp stop my-app --force        # SIGKILL
frontmcp service install my-app     # Install systemd/launchd service
frontmcp service uninstall my-app

Package Management

frontmcp install @company/my-mcp --registry https://npm.company.com
frontmcp install ./my-local-app     # Install from local path
frontmcp install github:user/repo   # Install from git
frontmcp configure my-app           # Re-run setup questionnaire
frontmcp uninstall my-app

Unix Socket

frontmcp socket ./src/main.ts --socket /tmp/my-app.sock
frontmcp socket ./src/main.ts --background --db ./data.db

Skills

frontmcp skills search "openapi"                # Find skills in the catalog
frontmcp skills install frontmcp-development    # Install one skill for Claude Code
frontmcp skills install --all --provider codex  # Install every skill for Codex

Docs

| Topic | Link | | -------------------- | ----------------------------------------- | | Installation & setup | Installation | | CLI reference | CLI Reference | | Local development | Local Dev Server | | Build targets | Build targets | | Production builds | Production Build | | frontmcp.config | Config files | | Connecting a client | MCP clients | | Skills | Skills commands | | Custom commands | Project commands |

Related Packages

• @frontmcp/sdk — the framework you write the server with
• @frontmcp/testing — the test framework frontmcp test runs
• @frontmcp/skills — the catalog behind frontmcp skills
• @frontmcp/nx — Nx generators and executors that run these commands

Contributing

Source: libs/cli. Issues and pull requests are welcome; see CONTRIBUTING.md.

Architecture

libs/cli/src/
├── core/               # CLI entry, program factory, args, help, bridge
│   ├── cli.ts          # Entry point (bin)
│   ├── program.ts      # Commander program factory
│   ├── bridge.ts       # Commander options → ParsedArgs adapter
│   ├── args.ts         # ParsedArgs type definitions
│   └── help.ts         # Custom grouped help formatter
├── commands/
│   ├── build/          # build: node, cli, sdk, browser, adapter and mcpb targets
│   │   └── exec/
│   │       ├── cli-runtime/            # Generated CLI runtime modules
│   │       │   ├── generate-cli-entry.ts   # Code-gen for Commander CLI entry
│   │       │   ├── oauth-helper.ts         # OAuth PKCE login/logout helpers
│   │       │   ├── output-formatter.ts     # Text/JSON output formatting
│   │       │   ├── credential-store.ts     # Token persistence
│   │       │   ├── session-manager.ts      # Multi-session management
│   │       │   ├── schema-extractor.ts     # MCP schema → CLI metadata
│   │       │   ├── schema-to-commander.ts  # Schema → Commander options
│   │       │   ├── cli-bundler.ts          # esbuild bundling for CLI
│   │       │   └── index.ts               # Barrel exports
│   │       ├── config.ts               # frontmcp.config.js loader
│   │       ├── manifest.ts             # Build manifest generation
│   │       └── index.ts                # Exec build orchestrator
│   ├── dev/            # dev, test, init, doctor, inspector
│   ├── eject/          # eject-mcp-config
│   ├── install/        # plugin install, uninstall, status
│   ├── mcpb/           # mcpb validate
│   ├── skills/         # skills search, list, install, read, export, publish
│   ├── pm/             # start, stop, restart, status, list, logs, service, socket
│   ├── package/        # install, uninstall, configure
│   ├── registry/       # registry keygen, publish, status (MCP Registry)
│   └── scaffold/       # create
├── shared/             # env loading, fs utils, prompts
└── index.ts            # Public API exports

Each command group has a register.ts that defines commands, flags, and descriptions using the Commander API. The bridge.ts module converts Commander's parsed options into the ParsedArgs shape used by handlers.

Adding a New Command

1. Create the handler in the appropriate commands/<group>/ directory
2. Add registration in commands/<group>/register.ts:

   program
     .command('my-command')
     .description('What it does')
     .option('-f, --flag <value>', 'Description')
     .action(async (options) => {
       const { runMyCommand } = await import('./my-command.js');
       await runMyCommand(toParsedArgs('my-command', [], options));
     });

3. The bridge in core/bridge.ts maps Commander options to ParsedArgs — add any new flags there
4. Add the command name to the appropriate group in core/help.ts

Testing

nx test cli              # Unit tests
nx run cli:test:e2e      # E2E tests

Build

nx build cli

License

Apache-2.0. See LICENSE.