Skip to main content
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)
Create a new project with the FrontMCP CLI: 
npx frontmcp create my-mcp-server
cd my-mcp-server
npm run dev
The CLI creates a complete project structure with:
  • ✅ TypeScript configured
  • ✅ Sample server, app, and tool
  • ✅ Development scripts ready
  • ✅ Hot-reload enabled
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 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: 
my-mcp-server/
├── src/
│   ├── main.ts          # Server entry point
│   ├── hello.app.ts     # App definition
│   └── tools/
│       └── greet.tool.ts # Sample tool
├── 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

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

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

CommandDescription
npx frontmcp create <name>Create a new FrontMCP project
npx frontmcp initAdd FrontMCP to existing project
npm run devStart with hot-reload
npm run buildCompile to production
npm run inspectOpen MCP Inspector
npm run doctorVerify setup

​
Troubleshooting

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
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
Solution: The dev command performs async type-checks. Fix TypeScript errors shown in the console.
# Manual type check
npx tsc --noEmit
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 logger
    this.logger.info('Greeting user', { name: input.name });

    // Access auth info
    const userId = this.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!