Quickstart

Build and run your first MCP server with FrontMCP. This quickstart gets you from zero to a working server in under 5 minutes.

Prerequisites

Node.js: Version 24+ (Active LTS)
- FrontMCP is developed and tested on Node.js 24
npm ≥ 10 (or pnpm/yarn)

Standard
Nx Monorepo

Create a new project

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

The create command is interactive by default. It will ask you about:

Deployment target: Node.js (Docker), Vercel, AWS Lambda, or Cloudflare Workers
Redis setup: Docker Compose, existing Redis, or none (Docker target only)
GitHub Actions: Enable CI/CD workflows

Use --yes (or -y) to skip prompts and use defaults.

The CLI creates a complete project structure with:

✅ TypeScript configured
✅ Sample server, app, and tool
✅ Development scripts ready
✅ Hot-reload enabled
✅ Deployment configuration for your target platform
✅ GitHub Actions CI/CD (optional)
✅ Git repository initialized with initial commit

Your server is now running at http://localhost:3000!

Add to Existing Project

If you already have a Node.js project, install FrontMCP:

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

The init command:

Adds FrontMCP scripts to package.json
Updates tsconfig.json with required settings
Creates a minimal server if none exists

Project Structure

After creating your project, you’ll have:

Docker (default)
Vercel
Lambda
Cloudflare

my-mcp-server/
├── ci/
│   ├── Dockerfile
│   ├── docker-compose.yml
│   └── .env.docker
├── .github/workflows/    # If CI/CD enabled
│   ├── ci.yml
│   ├── e2e.yml
│   └── deploy.yml
├── src/
│   ├── main.ts
│   ├── hello.app.ts
│   └── tools/
│       └── greet.tool.ts
├── package.json
└── tsconfig.json

my-mcp-server/
├── vercel.json
├── src/
│   ├── main.ts
│   ├── hello.app.ts
│   └── tools/
│       └── greet.tool.ts
├── package.json
└── tsconfig.json

my-mcp-server/
├── ci/
│   └── template.yaml    # AWS SAM template
├── src/
│   ├── main.ts
│   ├── hello.app.ts
│   └── tools/
│       └── greet.tool.ts
├── package.json
└── tsconfig.json

my-mcp-server/
├── wrangler.toml
├── src/
│   ├── main.ts
│   ├── hello.app.ts
│   └── tools/
│       └── greet.tool.ts
├── package.json
└── tsconfig.json

Available Commands

Your project includes these scripts:

npm run dev
# Starts server with hot-reload and type-checking

Create the workspace

npx frontmcp create my-platform --nx
cd my-platform

This scaffolds the full monorepo structure with a sample app, including apps/, libs/, and servers/ directories.

Build your first app

Generate an app

nx g @frontmcp/nx:app crm

Creates apps/crm/ with a main entry point, app class, and sample tool.

Add a tool

nx g @frontmcp/nx:tool fetch-contacts --project crm

Creates apps/crm/src/tools/fetch-contacts.tool.ts — edit the execute() method to add your logic.

Generate a shared library

nx g @frontmcp/nx:lib shared-utils

Creates libs/shared-utils/ — use it for code shared across apps.

Generate a server

nx g @frontmcp/nx:server production --apps crm --deploymentTarget node

Creates servers/production/ with a Dockerfile, docker-compose.yml, and an entry point that composes the CRM app.

Start development

nx dev crm

Starts the CRM app in development mode with hot-reload.

Build and test

nx build production
nx test crm

Compiles the production server and runs tests.

Your monorepo is ready! Add more apps, tools, and libraries as your platform grows.

Project Structure

After completing the steps above, your workspace looks like this:

my-platform/
├── apps/
│   └── crm/
│       ├── src/
│       │   ├── main.ts
│       │   ├── crm.app.ts
│       │   └── tools/
│       │       ├── hello.tool.ts
│       │       └── fetch-contacts.tool.ts
│       ├── project.json
│       └── tsconfig.json
├── libs/
│   └── shared-utils/
│       ├── src/
│       │   ├── shared-utils.ts
│       │   └── index.ts
│       └── project.json
├── servers/
│   └── production/
│       ├── src/main.ts
│       ├── Dockerfile
│       ├── docker-compose.yml
│       └── project.json
├── nx.json
├── tsconfig.base.json
└── package.json

Common Commands

Command	Description
`nx dev <app>`	Start an app with hot-reload
`nx build <project>`	Build an app or server
`nx test <project>`	Run tests
`nx inspector <app>`	Launch MCP Inspector
`nx graph`	Visualize dependency graph
`nx affected -t test`	Test only affected projects
`nx run-many -t build`	Build all projects

Server Configuration

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: 3000 },
  logging: { level: LogLevel.INFO },
})
export default class Server {}

The @FrontMcp decorator configures your server. It requires info, apps, and optional http and logging settings.

App Definition

src/hello.app.ts

import { App } from '@frontmcp/sdk';
import GreetTool from './tools/greet.tool';

@App({
  id: 'hello',
  name: 'Hello App',
  tools: [GreetTool],
})
export default class HelloApp {}

Apps organize related tools, plugins, and providers. Each app can have its own authentication and configuration.

Your First Tool

Class-based (Recommended)
Function-based

src/tools/greet.tool.ts

import { Tool, ToolContext } from '@frontmcp/sdk';
import { z } from '@frontmcp/sdk';

@Tool({
  name: 'greet',
  description: 'Greets a user by name',
  inputSchema: { name: z.string() },
})
export default class GreetTool extends ToolContext {
  async execute(input: { name: string }) {
    return `Hello, ${input.name}!`;
  }
}

src/tools/greet.tool.ts

import { tool } from '@frontmcp/sdk';
import { z } from '@frontmcp/sdk';

export default tool({
  name: 'greet',
  description: 'Greets a user by name',
  inputSchema: { name: z.string() },
})(async (input) => {
  return `Hello, ${input.name}!`;
});

Use class-based tools when you need access to providers, logging, or auth context. Use function-based tools for simple stateless operations.

Test Your Server

Start the server

npm run dev

You should see:

[INFO] Server listening on http://localhost:3000
[INFO] Registered 1 tool: greet

Launch the Inspector

Open a new terminal and run:

npm run inspect

This opens the MCP Inspector at http://localhost:6274

Connect to your server

In the Inspector: 1. Enter server URL: http://localhost:3000 2. Click “Connect” 3. You should see your greet tool listed

Call your tool

Select the greet tool
Enter input: { "name": "Ada" }
Click “Call Tool”
You should see: "Hello, Ada!"

Congratulations! You’ve built and tested your first MCP server!

What’s Next?

Choosing how to run FrontMCP? See Runtime Modes for a comparison of SDK, Server, and Serverless options.

Add Tools

Learn how to create more powerful tools with validation, providers, and context

OpenAPI Adapter

Auto-generate tools from your REST API’s OpenAPI spec

Add Caching

Improve performance with transparent caching

Authentication

Secure your server with OAuth (local or remote)

Plugins

Add cross-cutting features like logging, metrics, and rate limiting

Deploy

Build and deploy your server to production

Common Commands Reference

Command	Description
`npx frontmcp create <name>`	Create a new FrontMCP project (interactive)
`npx frontmcp create <name> --yes`	Create with defaults (non-interactive)
`npx frontmcp create <name> --nx`	Create an Nx monorepo
`npx frontmcp init`	Add FrontMCP to existing project
`npm run dev`	Start with hot-reload
`npm run build`	Compile to production
`npm run inspect`	Open MCP Inspector
`npm run doctor`	Verify setup

Create Command Flags

Flag	Description
`--yes, -y`	Use defaults (non-interactive mode)
`--target <type>`	Deployment target: `node`, `vercel`, `lambda`, `cloudflare`
`--redis <setup>`	Redis setup: `docker`, `existing`, `none`
`--cicd / --no-cicd`	Enable/disable GitHub Actions CI/CD
`--pm <manager>`	Package manager: `npm`, `yarn`, `pnpm`
`--nx`	Scaffold an Nx monorepo instead of standalone project

Troubleshooting

Server won't start

Check:

Node.js version 24+: node --version
Port 3000 is available
No TypeScript errors: Check console output

Fix:

npm run doctor  # Verify configuration

Tools not appearing

Possible causes:

Tool not imported in app
Decorator metadata not enabled

Fix:

Verify import GreetTool from './tools/greet.tool'

Check tsconfig.json has:

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

Ensure import 'reflect-metadata' at top of main.ts

Type errors in development

Solution: The dev command performs async type-checks. Fix TypeScript errors shown in the console.

# Manual type check
npx tsc --noEmit

Inspector can't connect

Check:

Server is running: http://localhost:3000 should be accessible
Correct URL in Inspector: http://localhost:3000 (not https)
No CORS issues: Both server and inspector on localhost

Debug:

# Test server directly
curl http://localhost:3000/health

Example: Extended Greeting Tool

Here’s a more advanced version with multiple features:

import { Tool, ToolContext } from '@frontmcp/sdk';
import { z } from '@frontmcp/sdk';

@Tool({
  name: 'greet',
  description: 'Greets a user with optional formality level',
  inputSchema: {
    name: z.string().min(1, 'Name is required'),
    formality: z.enum(['casual', 'formal', 'enthusiastic']).default('casual'),
    timeOfDay: z.enum(['morning', 'afternoon', 'evening']).optional(),
  },
})
export default class GreetTool extends ToolContext {
  async execute(input: {
    name: string;
    formality: 'casual' | 'formal' | 'enthusiastic';
    timeOfDay?: 'morning' | 'afternoon' | 'evening';
  }) {
    // Access context-aware logger
    this.contextLogger.info('Greeting user', { name: input.name });

    // Access auth info (via context)
    const userId = this.context.authInfo?.user?.id;

    // Build greeting based on formality
    let greeting = '';
    switch (input.formality) {
      case 'formal':
        greeting = `Good ${input.timeOfDay || 'day'}, ${input.name}.`;
        break;
      case 'enthusiastic':
        greeting = `Hey ${input.name}! Great to see you! 🎉`;
        break;
      case 'casual':
      default:
        greeting = `Hello, ${input.name}!`;
    }

    return {
      message: greeting,
      timestamp: new Date().toISOString(),
      userId,
    };
  }
}

This example demonstrates:

✅ Input validation with Zod
✅ Default values
✅ Optional fields
✅ Accessing logger
✅ Accessing auth context
✅ Structured output

FrontMCP speaks MCP Streamable HTTP. Any MCP-capable client (Claude Desktop, custom agents, etc.) can connect and call your tools!

Get Started

FrontMCP

Features

Extensibility

Testing

React SDK

Guides

Prerequisites

Create a new project

Add to Existing Project

Project Structure

Available Commands

Create the workspace

Build your first app

Project Structure

Common Commands

Server Configuration

App Definition

Your First Tool

Test Your Server

What’s Next?

Add Tools

OpenAPI Adapter

Add Caching

Authentication

Plugins

Deploy

Common Commands Reference

Create Command Flags

Troubleshooting

Example: Extended Greeting Tool

Get Started

FrontMCP

Features

Extensibility

Testing

React SDK

Guides

Documentation Index

​Prerequisites

​Create a new project

​Add to Existing Project

​Project Structure

​Available Commands

​Create the workspace

​Build your first app

​Project Structure

​Common Commands

​Server Configuration

​App Definition

​Your First Tool

​Test Your Server

​What’s Next?

Add Tools

OpenAPI Adapter

Add Caching

Authentication

Plugins

Deploy

​Common Commands Reference

​Create Command Flags

​Troubleshooting

​Example: Extended Greeting Tool

Prerequisites

Create a new project

Add to Existing Project

Project Structure

Available Commands

Create the workspace

Build your first app

Project Structure

Common Commands

Server Configuration

App Definition

Your First Tool

Test Your Server

What’s Next?

Common Commands Reference

Create Command Flags

Troubleshooting

Example: Extended Greeting Tool