Skip to main content
Run your FrontMCP server locally with hot-reload and verify it with the FrontMCP Inspector (zero setup).

​
Prerequisites

  • Node.js ≥ 22
  • npm ≥ 10 (pnpm/yarn also supported)

​
Quick start

​
Option A — New project

Creates a folder and scaffolds everything for you. 
npx frontmcp create my-app

​
Option B — Existing project

Install and initialize in your current repo: 
npm i -D frontmcp @types/node@^20
npx frontmcp init
init adds the required scripts and updates tsconfig.json automatically.

​
Package scripts

After create or init, your package.json will include: 
{
  "scripts": {
    "dev": "frontmcp dev",
    "build": "frontmcp build",
    "inspect": "frontmcp inspector",
    "doctor": "frontmcp doctor"
  }
}
  • frontmcp dev — run in watch mode with type-checks
  • frontmcp build — compile to ./dist (override with --out-dir)
  • frontmcp inspector — launches @modelcontextprotocol/inspector with zero setup
  • frontmcp doctor — verifies Node/npm versions and project configuration
init writes this for you, but if you prefer to manage it manually:
tsconfig.json
{
  "compilerOptions": {
    "target": "es2021",
    "module": "esnext",
    "lib": ["es2021"],
    "moduleResolution": "bundler",
    "rootDir": "src",
    "outDir": "dist",
    "strict": true,
    "esModuleInterop": true,
    "resolveJsonModule": true,
    "skipLibCheck": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "sourceMap": true
  },
  "include": ["src/**/*.ts"],
  "exclude": ["**/*.test.ts", "**/__tests__/**"]
}

​
Minimal app

You can import from @frontmcp/sdk directly; no extra install needed.
src/main.ts 
import 'reflect-metadata';
import { FrontMcp, LogLevel } from '@frontmcp/sdk';
import HelloApp from './hello.app';

@FrontMcp({
  info: { name: 'Hello MCP', version: '0.1.0' },
  apps: [HelloApp],
  http: { port: Number(process.env.PORT) || 3000 },
  logging: { level: LogLevel.Info }
})
export default class Server {}
src/hello.app.ts 
import { App } from '@frontmcp/sdk';
import Greet from './tools/greet.tool';

@App({ id: 'hello', name: 'Hello', tools: [Greet] })
export default class HelloApp {}
src/tools/greet.tool.ts 
import { tool } from '@frontmcp/sdk';
import { z } from 'zod';

export default tool({
  name: 'greet',
  description: 'Greets a user by name',
  // New style: pass Zod fields directly (no z.object wrapper)
  inputSchema: { name: z.string() }
})(({ name }) => `Hello, ${name}!`);

​
Run the dev server

npm run dev
Your server will start (default http://localhost:3000). The console will print the MCP endpoint.

​
Inspect locally (zero setup)

Launch the FrontMCP Inspector to exercise tools and messages in a friendly UI: 
npm run inspect
  • This runs npx @modelcontextprotocol/inspector behind the scenes.
  • Point it at your local server URL printed by dev (e.g., http://localhost:3000).
  • Try calling greet and watch responses stream back in real time.

​
Troubleshooting

  • Check configuration
npm run doctor
Ensures Node/npm versions, entry detection, and tsconfig.json are correct.
  • Entry detection The CLI looks for package.json.main; if missing, it falls back to src/main.ts. If no entry is found, it will tell you how to create one.
  • Type errors in dev The dev command performs async type-checks while watching your files, so you’ll see issues immediately without stopping the server.