Quickstart

Build your first MCP server with FrontMCP in under 5 minutes

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:
  • Minimum: Version 22 (LTS Maintenance)
  • Recommended: Version 24 (Active LTS)
  • FrontMCP is developed and tested on Node.js 24
• npm ≥ 10 (or pnpm/yarn)

---

Option 1: Quick Start (Recommended)

Create a new project with the FrontMCP CLI:

npm

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)

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

---

Option 2: Add to Existing Project

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

npm

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)

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

Vercel

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

Lambda

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

Cloudflare

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

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)

src/tools/greet.tool.ts

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

@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}!`;
  }
}

Function-based

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',
  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.

---

Available Commands

Your project includes these scripts:

Development

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

---

Test Your Server

1. Start the server

   npm run dev
   

   You should see:

   [INFO] Server listening on http://localhost:3000
   [INFO] Registered 1 tool: greet
   
2. Launch the Inspector

   Open a new terminal and run:

   npm run inspect
   

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

3. 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

4. Call your tool

   1. Select the greet tool
   2. Enter input: { "name": "Ada" }
   3. Click “Call Tool”
   4. 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 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:

1. Node.js version 22+ (Node 24 recommended): node --version
2. Port 3000 is available
3. 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:

1. Verify import GreetTool from './tools/greet.tool'
2. Check tsconfig.json has:
   {
     "experimentalDecorators": true,
     "emitDecoratorMetadata": true
   }
   
3. 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:

1. Server is running: http://localhost:3000 should be accessible
2. Correct URL in Inspector: http://localhost:3000 (not https)
3. 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 'zod';

@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!