# Installation

> Create a FrontMCP server on your machine, run it with hot reload, and connect a client.

Source: https://frontmcp.dev/learn/installation

The Playground is the quickest way to learn FrontMCP. To build a real server, create a project on your machine. It takes one command.

**You will learn**
- How to create a new FrontMCP project
- How to add FrontMCP to a project you already have
- How to run your server and test it with the MCP Inspector
- How to fix the most common setup problems

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

```bash
node --version
npm --version
```

## Creating a new server

```bash
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):

*[Illustration: The new project in a file explorer: my-mcp-server with ci/ (Dockerfile, docker-compose.yml), src/ with main.ts marked @FrontMcp, calc.app.ts marked @App, and tools/add.tool.ts marked @Tool, then package.json and tsconfig.json. Beside it, the same three files as nested boxes: the @FrontMcp server in main.ts contains the @App in calc.app.ts, which contains the @Tool add in add.tool.ts.]*
That's the same server you built at the end of the [Quick Start](https://frontmcp.dev/learn#grouping-capabilities-into-an-app-and-a-server).

## Adding FrontMCP to an existing project

```bash
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:

```json tsconfig.json
{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}
```

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

```ts src/main.ts
import "reflect-metadata";
import { FrontMcp } from "@frontmcp/sdk";
```

## Running and testing your server

Your project comes with these scripts:

| Command | What it does |
| --- | --- |
| `npm run dev` | Starts the server with hot reload and type checking |
| `npm run build` | Compiles a production build to `./dist` |
| `npm run inspect` | Opens the MCP Inspector |
| `npm run doctor` | Checks your Node and npm versions and your config |

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

```bash
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:

```bash
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](https://frontmcp.dev/reference/nx#installing-it) 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:

```bash
npm install vectoriadb tslib
```

### The Inspector can't connect

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