Installation

Before you start

You need Node.js 24 or later and npm 10 or later (pnpm and yarn work too). FrontMCP is developed and tested on Node 24. Check your versions:

node --version
npm --version

Creating a new server

npx frontmcp create my-mcp-server
cd my-mcp-server
npm install
npm run dev

create asks a few questions:

• Deployment target: Node.js (Docker), Vercel, AWS Lambda or Cloudflare Workers
• Redis: Docker Compose, an existing Redis, or none (Docker target only)
• GitHub Actions: whether to add CI/CD workflows

Pass --yes to accept the defaults, or answer up front with flags such as --target cloudflare or --pm pnpm.

create doesn't install anything, so run npm install (or your package manager) before npm run dev. Your server is now running at http://localhost:3000/mcp, and http://localhost:3000/health answers {"status":"ok", …}. The project looks like this (Docker target):

That's the same server you built at the end of the Quick Start.

Adding FrontMCP to an existing project

npm install @frontmcp/sdk reflect-metadata
npm install -D frontmcp @types/node@^24
npx frontmcp init

init updates tsconfig.json with the decorator settings FrontMCP needs:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

Then import reflect-metadata once, at the very top of your entry file, before anything from FrontMCP:

import "reflect-metadata";
import { FrontMcp } from "@frontmcp/sdk";

Running and testing your server

Your project comes with these scripts:

To test the server the way a client sees it, keep npm run dev running and start the Inspector in a second terminal:

npm run inspect

It opens at http://localhost:6274. Enter http://localhost:3000/mcp as the server URL, click Connect, pick the add tool, and call it with { "a": 2, "b": 3 }. You'll get 5 back, just as in the Playground.

Connecting a client

FrontMCP speaks MCP's Streamable HTTP transport, so any MCP client that supports it can connect to http://localhost:3000/mcp. That includes Claude Desktop, Claude Code and Cursor.

Starting a monorepo

For several servers that share code, scaffold an Nx workspace:

npx frontmcp create my-platform --nx --pm pnpm

It creates apps/, libs/ and servers/ folders, plus generators for new apps, tools and servers. To add the plugin to a workspace you already have, run nx add @frontmcp/nx: it installs FrontMCP and makes the build and test targets cacheable. The Nx plugin reference has the details.

Troubleshooting

The server won't start

Check that you're on Node 24 or later, that nothing else is using port 3000, and that the console shows no TypeScript errors. Then run npm run doctor.

My tools don't appear

1. Make sure the tool is listed in its app's tools array, and the app is listed in @FrontMcp({ apps }).
2. Make sure tsconfig.json has experimentalDecorators and emitDecoratorMetadata set to true.
3. Make sure import "reflect-metadata" is the first line of main.ts.

"skill storage needs the optional peer dependency 'vectoriadb'"

You're on FrontMCP 1.8, which lists vectoriadb as an optional peer dependency but loads it at startup, so an install without dev dependencies, like a production Docker image, can't start. Since 1.9.1, @frontmcp/sdk depends on vectoriadb (and vectoriadb on tslib), and a production install starts. Upgrade, or on 1.8 add both to your dependencies:

npm install vectoriadb tslib

The Inspector can't connect

Check that http://localhost:3000/health responds, and that you entered http://, not https://.