Serverless Deployment

Deploy your FrontMCP server to serverless platforms like Vercel, AWS Lambda, and Cloudflare Workers.

Supported Platforms

Platform	Status	Module Format	Config File
Vercel	Stable	CommonJS	`vercel.json`
AWS Lambda	Stable	CommonJS	`ci/template.yaml` (SAM)
Cloudflare Workers	Experimental	CommonJS	`wrangler.toml`

Quick Start

New project? Use frontmcp create with the --target flag to scaffold a serverless-ready project:

# Vercel project
npx frontmcp create my-app --target vercel

# AWS Lambda project (generates SAM template)
npx frontmcp create my-app --target lambda

# Cloudflare Workers project
npx frontmcp create my-app --target cloudflare

This generates the platform config files (vercel.json, ci/template.yaml, or wrangler.toml) automatically.

Vercel
AWS Lambda
Cloudflare

# Build for Vercel
frontmcp build --target vercel

# Deploy
vercel deploy

# Install required dependency
npm install @codegenie/serverless-express

# Build for Lambda
frontmcp build --target lambda

# Deploy with your preferred tool (SAM, CDK, Serverless Framework)

# Build for Cloudflare Workers
frontmcp build --target cloudflare

# Deploy
wrangler deploy

Vercel

Vercel is a popular platform for deploying serverless functions with excellent DX.

For persistent session storage on Vercel, see Vercel KV Setup for an edge-compatible alternative to Redis.

Setup

Build your project:
frontmcp build --target vercel

This generates:

dist/
  main.js              # Your compiled server
  index.js             # Vercel handler wrapper
vercel.json            # Vercel configuration
.vercel/output/        # Build Output API structure
  config.json          # Routes all requests to index function
  functions/
    index.func/
      .vc-config.json  # Node.js 24 runtime config
      handler.cjs      # Bundled handler

Deploy:
vercel deploy

Generated vercel.json

{
  "version": 2,
  "buildCommand": "yarn frontmcp build --target vercel",
  "installCommand": "yarn install"
}

The buildCommand runs the vercel target through your package manager, detected from the lockfile:

Lockfile	`buildCommand`	`installCommand`
`package-lock.json` or none	`npx frontmcp build --target vercel`	`npm install`
`yarn.lock`	`yarn frontmcp build --target vercel`	`yarn install`
`pnpm-lock.yaml`	`pnpm exec frontmcp build --target vercel`	`pnpm install`
`bun.lock` / `bun.lockb`	`bunx frontmcp build --target vercel`	`bun install`

frontmcp create --target vercel writes the same file (with a $schema line).

The vercel target deploys a Node.js handler using Vercel’s Build Output API, not Vercel Edge Runtime. You can customize this file after generation — the build command will not overwrite existing config files.

Do not point buildCommand at your build script (npm run build). That script runs frontmcp build, which builds the deployments in your frontmcp.config (typically node) and never writes .vercel/output, so Vercel has nothing to deploy. Config files generated before 1.8.6 used <pm> run build; change them to the command in the table above.

How It Works

The generated serverless-setup.js + index.js wrapper:

serverless-setup.js sets FRONTMCP_SERVERLESS=1 (must be required first, before any decorators run)
index.js requires your compiled main.js (which runs the @FrontMcp decorator) and re-exports an async handler that retrieves the Express app
The Vercel adapter compiles to CommonJS and bundles everything into a single handler.cjs via rspack — that bundle is what Vercel actually runs

// Generated dist/index.js (simplified)
require('./serverless-setup.js'); // sets FRONTMCP_SERVERLESS=1
require('./main.js');             // runs the @FrontMcp decorator
const { getServerlessHandlerAsync } = require('@frontmcp/sdk');

let handlerPromise = null;
module.exports = async function handler(req, res) {
  if (!handlerPromise) handlerPromise = getServerlessHandlerAsync();
  const app = await handlerPromise;
  return app(req, res);
};
module.exports.default = module.exports;

AWS Lambda

Deploy to AWS Lambda using the Serverless Express adapter.

Prerequisites

Install the required dependency:

npm install @codegenie/serverless-express

Setup

Projects created with frontmcp create --target lambda include a SAM template at ci/template.yaml and a deploy script:

npm run deploy  # Runs: cd ci && sam build && sam deploy

Build your project:
frontmcp build --target lambda

This generates:

dist/
  main.js      # Your compiled server
  index.js     # Lambda handler wrapper

Deploy using your preferred AWS deployment tool.

Example SAM Template

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31

Resources:
  FrontMcpFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: dist/index.handler
      Runtime: nodejs24.x
      Timeout: 30
      MemorySize: 256
      Events:
        Api:
          Type: Api
          Properties:
            Path: /{proxy+}
            Method: ANY

Example serverless.yml

service: frontmcp-server

provider:
  name: aws
  runtime: nodejs24.x
  stage: ${opt:stage, 'dev'}

functions:
  api:
    handler: dist/index.handler
    events:
      - http:
          path: /{proxy+}
          method: ANY

Module Format

Lambda, Vercel, and Cloudflare Workers builds emit CommonJS (dist/index.js), so the bundle works without "type": "module" in package.json. If your handler must be ESM, you can use the import() form to load the bundle from an .mjs wrapper.

Cold Start Optimization

Lambda cold starts can add latency to the first request. Consider:

Provisioned Concurrency: Keep instances warm
Smaller bundle size: Use tree-shaking and minimize dependencies
ARM64 architecture: Often faster cold starts than x86

Cloudflare Workers (Experimental)

Cloudflare Workers support is experimental. The Express-to-Workers adapter has limitations with streaming, certain middleware, and some response methods.For production Cloudflare deployments, consider using Hono or native Workers APIs.

Projects created with frontmcp create --target cloudflare include a wrangler.toml and a deploy script:

npm run deploy  # Runs: wrangler deploy

Limitations

Basic request/response handling only
No streaming support
Limited Express middleware compatibility
Missing some response methods (redirect(), type(), etc.)

Setup

Build your project:
frontmcp build --target cloudflare

This generates:

dist/
  main.js      # Your compiled server
  index.js     # Cloudflare handler wrapper
wrangler.toml  # Wrangler configuration

Deploy:
wrangler deploy

Generated wrangler.toml

name = "frontmcp-worker"
main = "dist/cloudflare/index.js"
compatibility_date = "2024-09-23"
# Required — the worker entry require()s @frontmcp/sdk + Express (Node builtins).
# Without nodejs_compat the Worker fails to boot. The build always emits it.
compatibility_flags = ["nodejs_compat"]

Storage Considerations

Serverless environments require distributed storage since each invocation may run on a different instance.

Recommended Storage by Platform

Platform	Recommended Storage	Notes
Vercel	Vercel KV or Upstash	Edge-compatible REST APIs
AWS Lambda	ElastiCache Redis or Upstash	VPC-accessible
Cloudflare	Cloudflare KV or Upstash	Workers KV for simple cases

Storage Configuration

Vercel KV
Upstash (REST)
Redis

@FrontMcp({
  info: { name: 'My Server', version: '1.0.0' },
  redis: {
    provider: 'vercel-kv',
    // Uses KV_REST_API_URL and KV_REST_API_TOKEN from env
  },
})

Vercel KV has no pub/sub, so background tasks and elicitation cannot use it. The server still starts: tasks are skipped with a [tasks] startup warning unless you set tasks: { enabled: true } (which keeps the error), and elicitation throws ElicitationNotSupportedError only when its store actually resolves to Vercel KV. Give either feature its own backend (tasks: { redis }, or a Redis-backed elicitation) to use it on Vercel.

Upstash exposes a Vercel-KV-compatible REST API. Use the vercel-kv provider with the Upstash REST URL/token to use it from any platform:

@FrontMcp({
  info: { name: 'My Server', version: '1.0.0' },
  redis: {
    provider: 'vercel-kv',
    url: process.env.UPSTASH_REDIS_REST_URL,
    token: process.env.UPSTASH_REDIS_REST_TOKEN,
  },
})

@FrontMcp({
  info: { name: 'My Server', version: '1.0.0' },
  redis: {
    host: process.env.REDIS_HOST,
    port: 6379,
    password: process.env.REDIS_PASSWORD,
  },
})

Plugin Storage

Plugins like RememberPlugin and CachePlugin can use type: 'global-store' to automatically use the FrontMcp-level storage configuration:

RememberPlugin.init({
  type: 'global-store', // Uses redis config from @FrontMcp
  defaultTTL: 3600,
});

In-memory storage does not work reliably in serverless environments. Each invocation may create a new instance with empty memory. Always use a distributed storage backend.

How Serverless Mode Works

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Build Time                               │
├─────────────────────────────────────────────────────────────┤
│  frontmcp build --target vercel                            │
│       │                                                      │
│       ├── Compiles TypeScript with --module commonjs        │
│       ├── Generates platform-specific index.js wrapper      │
│       ├── Bundles entry + deps with rspack → handler.cjs    │
│       └── Creates platform config (vercel.json, etc.)       │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                     Runtime                                  │
├─────────────────────────────────────────────────────────────┤
│  1. Platform invokes index.js                               │
│  2. index.js sets FRONTMCP_SERVERLESS=1                     │
│  3. index.js requires main.js                               │
│  4. @FrontMcp decorator detects serverless mode             │
│  5. Decorator calls createHandler() instead of bootstrap()  │
│  6. Express app stored globally via setServerlessHandler()  │
│  7. index.js calls getServerlessHandlerAsync()              │
│  8. Requests are forwarded to the Express app               │
└─────────────────────────────────────────────────────────────┘

Environment Variable

The FRONTMCP_SERVERLESS=1 environment variable triggers serverless mode:

// In the @FrontMcp decorator
const isServerless = process.env.FRONTMCP_SERVERLESS === '1';

if (isServerless) {
  // Don't call listen(), store handler globally instead
  const handler = await FrontMcpInstance.createHandler(metadata);
  setServerlessHandler(handler);
} else {
  // Normal mode: start HTTP server
  FrontMcpInstance.bootstrap(metadata);
}

Bundle-time behavior of serverless builds

process.env.NODE_ENV stays a runtime lookup in the Vercel and Lambda bundles. It is not inlined as "production" at build time, so a deployment’s own NODE_ENV (and the production-only checks that read it) behave the same as on a Node server.
Optional packages the server may or may not use (@frontmcp/storage-sqlite, @frontmcp/observability, @vercel/kv, @opentelemetry/sdk-trace-base) are bundled when installed and left as a lazy require() when they are not, so a missing optional package no longer fails the build with “Module not found”. better-sqlite3 (a native addon) is always left external.

Troubleshooting

”Serverless handler not initialized”

Error: Serverless handler not initialized. Ensure @FrontMcp decorator ran and FRONTMCP_SERVERLESS=1 is set.

Causes:

The @FrontMcp decorator wasn’t executed before the handler was called
FRONTMCP_SERVERLESS=1 is not set in the entry point

Solutions:

Ensure your main.ts/main.js has the @FrontMcp decorator on a class
Verify the generated index.js sets the environment variable before importing main.js

Server answers 500 `server_misconfigured`

A configuration fault (for example a missing MCP_SESSION_SECRET or JWT_SECRET) is answered on Node, Vercel and Lambda the same way as on Workers: 500 {"error":"server_misconfigured","code":"SESSION_SECRET_REQUIRED","message":"<remedy>"}. The code is one of SESSION_SECRET_REQUIRED, JWT_SECRET_REQUIRED, JWT_SECRET_INVALID, UNENFORCED_METADATA, AUTH_CONFIGURATION_ERROR or CONFIG_INVALID; set the named variable in the platform’s environment settings and redeploy.

”Module not found: @codegenie/serverless-express”

The Lambda adapter requires an additional dependency:

npm install @codegenie/serverless-express

Cold Start Performance

First requests may be slow due to initialization. Strategies:

Platform	Solution
Lambda	Provisioned Concurrency, smaller bundles
Vercel	Edge Functions (if applicable)
Cloudflare	Workers are generally fast to cold start

TypeScript Compilation Errors

If you see module-related errors:

The adapter sets the correct module format automatically
--module commonjs for all targets (Node.js, Vercel, Lambda, Cloudflare); the Vercel and Lambda adapters then bundle to handler.cjs with rspack

Ensure your tsconfig.json doesn’t conflict. The CLI arguments override tsconfig settings.

API Reference

CLI Commands

# Build for Node.js (default, CommonJS)
frontmcp build

# Build for Vercel (CommonJS)
frontmcp build --target vercel

# Build for AWS Lambda (CommonJS)
frontmcp build --target lambda

# Build for Cloudflare Workers (CommonJS)
frontmcp build --target cloudflare

# Specify output directory
frontmcp build --target vercel --out-dir build

SDK Exports

import {
  getServerlessHandler,      // Get handler synchronously (may be null)
  getServerlessHandlerAsync, // Get handler with await (throws if not ready)
  setServerlessHandler,      // Store handler (used by decorator)
  setServerlessHandlerPromise, // Store handler promise
  setServerlessHandlerError, // Store initialization error
} from '@frontmcp/sdk';

​Supported Platforms

​Quick Start

​Vercel

​Setup

​Generated vercel.json

​How It Works

​AWS Lambda

​Prerequisites

​Setup

​Example SAM Template

​Example serverless.yml

​Module Format

​Cold Start Optimization

​Cloudflare Workers (Experimental)

​Limitations

​Setup

​Generated wrangler.toml

​Storage Considerations

​Recommended Storage by Platform

​Storage Configuration

​Plugin Storage

​How Serverless Mode Works

​Architecture

​Environment Variable

​Bundle-time behavior of serverless builds

​Troubleshooting

​”Serverless handler not initialized”

​Server answers 500 server_misconfigured

​”Module not found: @codegenie/serverless-express”

​Cold Start Performance

​TypeScript Compilation Errors

​API Reference

​CLI Commands

​SDK Exports

Supported Platforms

Quick Start

Vercel

Setup

Generated vercel.json

How It Works

AWS Lambda

Prerequisites

Setup

Example SAM Template

Example serverless.yml

Module Format

Cold Start Optimization

Cloudflare Workers (Experimental)

Limitations

Setup

Generated wrangler.toml

Storage Considerations

Recommended Storage by Platform

Storage Configuration

Plugin Storage

How Serverless Mode Works

Architecture

Environment Variable

Bundle-time behavior of serverless builds

Troubleshooting

”Serverless handler not initialized”

Server answers 500 `server_misconfigured`

”Module not found: @codegenie/serverless-express”

Cold Start Performance

TypeScript Compilation Errors

API Reference

CLI Commands

SDK Exports