Runtime Modes

FrontMCP supports three integration modes depending on how you want to deploy and run your MCP server. Choose the mode that best fits your architecture.

Overview

Mode	Use Case	Transport	Entry Point
SDK Mode	Embed in agent code	In-process	`connect()`, `connectOpenAI()`, etc.
Server Mode	Standalone HTTP server	HTTP (SSE, Streamable)	`@FrontMcp` with `http.port`
Handler Mode	Serverless functions	HTTP (stateless)	`createHandler()` or `FRONTMCP_SERVERLESS=1`

SDK Mode (Embedded)

Use SDK mode when your agent code directly calls FrontMCP tools without HTTP. This is ideal for:

Vercel AI or OpenAI SDK integrations
In-process agent frameworks
Testing and local development

Entry Points

Function	Platform	Tool Format
`connect()`	Auto-detect	Based on clientInfo
`connectOpenAI()`	OpenAI	`[{ type: 'function', function: { name, parameters } }]`
`connectClaude()`	Anthropic	`[{ name, input_schema }]`
`connectVercelAI()`	Vercel AI	`{ [name]: { parameters } }`

Benefits

Zero network overhead — tools execute in-process
Automatic format conversion — tools are formatted for your LLM platform
Simple auth injection — pass JWT tokens directly via authToken option
Singleton scope — config objects are cached for efficient reuse

Example: OpenAI Integration

import { connectOpenAI } from '@frontmcp/sdk';
import OpenAI from 'openai';

// Your FrontMCP server config (same as @FrontMcp decorator)
const serverConfig = {
  info: { name: 'My Tools', version: '1.0.0' },
  apps: [MyApp],
};

// Connect with auth token
const client = await connectOpenAI(serverConfig, {
  authToken: 'user-jwt-token',
  session: { id: 'session-123' },
});

// Tools are already in OpenAI format!
const tools = await client.listTools();

const openai = new OpenAI();
const response = await openai.chat.completions.create({
  model: 'gpt-4-turbo',
  tools,
  messages: [{ role: 'user', content: 'What is the weather?' }],
});

// Call tool if model requested it
if (response.choices[0].message.tool_calls) {
  const toolCall = response.choices[0].message.tool_calls[0];
  const result = await client.callTool(
    toolCall.function.name,
    JSON.parse(toolCall.function.arguments)
  );
}

await client.close();

Example: Vercel AI SDK

import { connectVercelAI } from '@frontmcp/sdk';
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

const client = await connectVercelAI(serverConfig, {
  authToken: 'user-jwt',
});

const tools = await client.listTools();  // Vercel AI SDK format

const { text } = await generateText({
  model: openai('gpt-4-turbo'),
  tools,
  prompt: 'What is the weather in NYC?',
});

await client.close();

Example: Anthropic Claude

import { connectClaude } from '@frontmcp/sdk';
import Anthropic from '@anthropic-ai/sdk';

const client = await connectClaude(serverConfig, { authToken: 'token' });
const tools = await client.listTools();  // Claude format

const anthropic = new Anthropic();
const response = await anthropic.messages.create({
  model: 'claude-3-opus-20240229',
  tools,
  messages: [{ role: 'user', content: 'What is the weather?' }],
});

await client.close();

Server Mode (HTTP)

Use Server mode when you need a standalone MCP server that clients connect to over HTTP. This is ideal for:

Claude Desktop and other MCP clients
Shared server for multiple clients
Production deployments with persistent connections

Configuration

import 'reflect-metadata';
import { FrontMcp, LogLevel } from '@frontmcp/sdk';
import MyApp from './my.app';

@FrontMcp({
  info: { name: 'My Server', version: '1.0.0' },
  apps: [MyApp],
  http: { port: 3001 },
  transport: { protocol: 'legacy' },
  logging: { level: LogLevel.Info },
})
export default class Server {}

Transport Protocols

Server mode supports multiple transport protocols:

Protocol	Description	Use Case
`legacy`	SSE + Streamable + Legacy SSE	Maximum compatibility (default)
`modern`	SSE + Streamable HTTP	Newer MCP clients
`stateless-api`	No sessions, request/response	Simple API access
`full`	All protocols enabled	Maximum flexibility

@FrontMcp({
  transport: { protocol: 'legacy' },  // Default - backwards compatible
})

@FrontMcp({
  transport: { protocol: 'modern' },  // SSE + Streamable HTTP
})

@FrontMcp({
  transport: {
    protocol: {
      sse: true,
      streamable: true,
      json: true,
      stateless: false,
      legacy: true,
      strictSession: false,
    },
  },
})

Session Storage

For production, configure Redis for session persistence:

@FrontMcp({
  info: { name: 'My Server', version: '1.0.0' },
  apps: [MyApp],
  http: { port: 3001 },
  redis: {
    host: 'redis.example.com',
    port: 6379,
    keyPrefix: 'mcp:',
  },
  transport: {

    persistence: { defaultTtlMs: 3600000 },
  },
})
export default class Server {}

Running the Server

# Development with hot-reload
npm run dev

# Production
npm run build
npm run start

Handler Mode (Serverless)

Use Handler mode when deploying to serverless platforms like Vercel, AWS Lambda, or Cloudflare Workers. This mode:

Does not start an HTTP server
Exports a request handler for the platform
Requires distributed storage (Redis, Vercel KV)

Configuration

Handler mode is triggered by setting FRONTMCP_SERVERLESS=1 in your entry point wrapper:

// Your FrontMCP server
@FrontMcp({
  info: { name: 'Serverless', version: '1.0.0' },
  apps: [MyApp],
  transport: { protocol: 'stateless-api' },
  redis: { provider: 'vercel-kv' },
})
export default class Handler {}

The build emits a serverless-setup.js that sets FRONTMCP_SERVERLESS=1 (loaded first) plus an index.js entry that requires your compiled module and exposes the handler. The Vercel and Lambda adapters compile to CommonJS and bundle to handler.cjs via rspack:

// Generated dist/index.js (Vercel — 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;

Quick Start

Vercel
AWS Lambda
Cloudflare

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

# Or build existing project
frontmcp build --target vercel

# Deploy
vercel deploy

# Create project with Lambda target
npx frontmcp create my-app --target lambda

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

# Build and deploy
frontmcp build --target lambda
cd ci && sam build && sam deploy

# Create project with Cloudflare target
npx frontmcp create my-app --target cloudflare

# Build and deploy
frontmcp build --target cloudflare
wrangler deploy

Storage Requirements

Serverless environments require distributed storage. In-memory storage does not work reliably since each invocation may run on a different instance.

Vercel KV
Upstash (REST)
Redis

@FrontMcp({
  redis: {
    provider: 'vercel-kv',
    // Uses KV_REST_API_URL and KV_REST_API_TOKEN from env
  },
})

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

@FrontMcp({
  redis: {
    provider: 'vercel-kv',
    url: process.env.UPSTASH_REDIS_REST_URL,
    token: process.env.UPSTASH_REDIS_REST_TOKEN,
  },
})

@FrontMcp({
  redis: {
    host: process.env.REDIS_HOST,
    port: 6379,
    password: process.env.REDIS_PASSWORD,
  },
})

Comparison Table

Feature	SDK Mode	Server Mode	Handler Mode
Network	In-process	HTTP	HTTP (stateless)
Use Case	Embedded agents	Standalone server	Serverless platforms
Session	In-memory	Configurable	Distributed required
Entry Point	`connect()`, `connectOpenAI()`, etc.	`@FrontMcp` with `http.port`	`createHandler()` or `FRONTMCP_SERVERLESS=1`
Scaling	Single process	Horizontal	Auto-scaling
Auth	Token injection	OAuth/JWT	OAuth/JWT
Cold Start	None	None	Platform-dependent

Decision Guide

When to use SDK Mode

Choose SDK mode when:

Your agent code calls FrontMCP tools directly
You’re using Vercel AI SDK or OpenAI SDK
You want zero network overhead
You need automatic tool format conversion
You’re building an in-process agent

Not recommended when:

External clients need to connect to your server
You need Claude Desktop compatibility

When to use Server Mode

Choose Server mode when:

MCP clients connect over the network (Claude Desktop, etc.)
You need SSE or Streamable HTTP transport
You want a long-running server process
Multiple clients share the same server

Not recommended when:

You’re deploying to serverless platforms
Your agent code runs in the same process

When to use Handler Mode

Choose Handler mode when:

Deploying to Vercel, AWS Lambda, or Cloudflare Workers
You want auto-scaling without managing servers
You need serverless cost efficiency

Not recommended when:

You need persistent WebSocket connections
Cold start latency is unacceptable
In-memory session state is required

Local Dev Server

Run and test your FrontMCP server locally

Production Build

Build and optimize for production deployment

Serverless Deployment

Detailed guide for Vercel, Lambda, and Cloudflare

Redis Setup

Configure Redis for session persistence

Get Started

Concepts

Build

Deploy

Plugins

Adapters

Extensibility

Testing

React SDK

Guides

Overview

SDK Mode (Embedded)

Entry Points

Benefits

Example: OpenAI Integration

Example: Vercel AI SDK

Example: Anthropic Claude

Server Mode (HTTP)

Configuration

Transport Protocols

Session Storage

Running the Server

Handler Mode (Serverless)

Configuration

Quick Start

Storage Requirements

Comparison Table

Decision Guide

Local Dev Server

Production Build

Serverless Deployment

Redis Setup

​Overview

​SDK Mode (Embedded)

​Entry Points

​Benefits

​Example: OpenAI Integration

​Example: Vercel AI SDK

​Example: Anthropic Claude

​Server Mode (HTTP)

​Configuration

​Transport Protocols

​Session Storage

​Running the Server

​Handler Mode (Serverless)

​Configuration

​Quick Start

​Storage Requirements

​Comparison Table

​Decision Guide

​Related Documentation

Local Dev Server

Production Build

Serverless Deployment

Redis Setup

Overview

SDK Mode (Embedded)

Entry Points

Benefits

Example: OpenAI Integration

Example: Vercel AI SDK

Example: Anthropic Claude

Server Mode (HTTP)

Configuration

Transport Protocols

Session Storage

Running the Server

Handler Mode (Serverless)

Configuration

Quick Start

Storage Requirements

Comparison Table

Decision Guide

Related Documentation