1---2name: frontmcp-deployment3description: Use when deploying, building for production, packaging, or shipping a FrontMCP server. Covers build targets (node, cli SEA binary, browser, embeddable SDK, mcpb archive for Claude Desktop, serverless) and deploying to Vercel (with Vercel KV), AWS Lambda (API Gateway, SAM, CDK), Cloudflare Workers (KV, D1, Durable Objects, v1.3 skills-only), and Node (multi-stage Docker, docker-compose, PM2, nginx). Also the frontmcp.deploy.yaml manifest plus GitHub Action push-resync, MCP client integration / .mcp.json for Claude Desktop, Claude Code, Cursor, and VS Code over stdio or HTTP, and MCP protocol revisions (serving 2026-07-28 alongside 2024-11-05 through 2025-11-25). Triggers: deploy, build for production, dockerize, containerize, serverless, edge runtime, go live, ship it.4license: Apache-2.05---67# FrontMCP Deployment Router89Entry point for deploying and building FrontMCP servers. This skill helps you choose the right deployment target or build format based on your infrastructure requirements.1011## When to Use This Skill1213### Must Use1415- Choosing between deployment targets (Node vs Vercel vs Lambda vs Cloudflare) for a new project16- Deciding on a build format (server vs CLI vs browser vs SDK) for distribution17- Planning infrastructure and need to understand trade-offs between deployment options1819### Recommended2021- Comparing serverless platforms for cost, cold-start, and feature support22- Understanding which transport protocol and storage provider each target requires23- Migrating from one deployment target to another2425### Skip When2627- You already know your deployment target (go directly to `deploy-to-node`, `deploy-to-vercel`, etc.)28- You need to configure server settings, not deploy (see `frontmcp-config`)29- You need to build components, not ship them (see `frontmcp-development`)3031> **Decision:** Use this skill when you need to figure out WHERE to deploy. Open the matching reference under `references/` directly when you already know.3233## Prerequisites3435- A working FrontMCP server with at least one `@App` and one `@Tool` (see `frontmcp-development`)36- Server configuration completed (see `frontmcp-config`)37- Tests passing locally (see `frontmcp-testing`)3839## Steps40411. Review the Scenario Routing Table and Target Comparison below to choose a deployment target422. Run `frontmcp build --target <target>` to produce the build output433. Follow the specific deployment reference (e.g., `references/deploy-to-node.md`, `references/deploy-to-vercel.md`) for platform instructions444. Verify with the Post-Deployment checklist at the end of this skill4546## Scenario Routing Table4748| Scenario | Reference | Description |49| ------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |50| Long-running server on VPS, Docker, or bare metal | `deploy-to-node` | Node.js with stdio or HTTP transport, PM2/Docker for process management |51| Serverless with zero config and Vercel KV | `deploy-to-vercel` | Vercel Functions with Streamable HTTP, Vercel KV for storage |52| AWS serverless with API Gateway | `deploy-to-lambda` | Lambda + API Gateway with Streamable HTTP, DynamoDB or ElastiCache |53| Edge computing with global distribution | `deploy-to-cloudflare` | Cloudflare Workers with KV or Durable Objects for storage |54| Hosted FrontMCP (v1.3 skills-only model) | `deploy-to-cloudflare-skills-only` | Cloudflare Worker as the MCP control plane; OpenAPI is capability inventory; agent uses 4 meta-tools + AgentScript; hot-reload via GitHub Action |55| Author `frontmcp.deploy.yaml` | `deploy-manifest-yaml` | v1 schema reference: runtime, server, specs, skills, tags, classification, bindings, signing, auth, secrets, environments |56| Standalone executable binary for distribution | `build-for-cli` | Single-binary CLI with stdio transport, embedded storage |57| Run MCP in a web browser | `build-for-browser` | Browser-compatible bundle with in-memory transport |58| Embed MCP into an existing Node.js application | `build-for-sdk` | Library build for programmatic usage without standalone server |59| Write a Dockerfile for Node.js deployment | `deploy-to-node-dockerfile` | Dockerfile configuration for Node.js deployment |60| Configure Vercel-specific settings (vercel.json) | `deploy-to-vercel-config` | Vercel-specific configuration (vercel.json) |61| Connect MCP clients (Claude, Cursor, VS Code) | `mcp-client-integration` | Configure .mcp.json for stdio, HTTP, or Unix socket transport |62| Serve or consume MCP protocol `2026-07-28` | `protocol-versions` | Stateless requests, `server/discover`, mirrored headers, MRTR, tasks extension, and the `McpStatelessClient` |6364### CLI Commands for Deployment and Operations6566Beyond `frontmcp build`, the CLI provides commands for the full deployment lifecycle:6768| Command | Description |69| ---------------------------- | ----------------------------------------------------------------------------------- |70| `frontmcp build -t <target>` | Build for target: `node`, `vercel`, `lambda`, `cloudflare`, `cli`, `browser`, `sdk` |71| `frontmcp build -t cli --js` | Build CLI as JS bundle (instead of native binary via SEA) |72| `frontmcp start <name>` | Start a named MCP server with supervisor (process management) |73| `frontmcp stop <name>` | Stop managed server (`-f` for force kill) |74| `frontmcp restart <name>` | Restart managed server |75| `frontmcp status [name]` | Show process status (detail if name given, table if omitted) |76| `frontmcp list` | List all managed processes |77| `frontmcp logs <name>` | Tail log output (`-F` follow, `-n` lines) |78| `frontmcp socket <entry>` | Start Unix socket daemon for local MCP server |79| `frontmcp service <action>` | Install/uninstall systemd (Linux) or launchd (macOS) service |80| `frontmcp install <source>` | Install MCP app from npm, local path, or git |81| `frontmcp uninstall <name>` | Remove installed MCP app |82| `frontmcp configure <name>` | Re-run setup questionnaire for installed app |83| `frontmcp doctor` | Check Node.js/npm versions and tsconfig requirements |84| `frontmcp inspector` | Launch MCP Inspector for debugging |85| `frontmcp init` | Create or fix tsconfig.json for FrontMCP |8687## Target Comparison8889| Target | Transport | Storage | Cold Start | Stateful | Best For |90| ---------- | --------------------------- | --------------------- | ---------- | -------- | -------------------------------- |91| Node | stdio, SSE, Streamable HTTP | Redis, SQLite, memory | None | Yes | Full-featured production servers |92| Vercel | Streamable HTTP (stateless) | Vercel KV | ~250ms | No | Rapid deployment, hobby/startup |93| Lambda | Streamable HTTP (stateless) | DynamoDB, ElastiCache | ~500ms | No | AWS ecosystem, event-driven |94| Cloudflare | Streamable HTTP (stateless) | KV, Durable Objects | ~5ms | Limited | Edge-first, global latency |95| CLI | stdio | SQLite, memory | None | Yes | Desktop tools, local agents |96| Browser | In-process direct client | memory | None | Yes | Client-side AI, demos |97| SDK | Programmatic | Configurable | None | Yes | Embedding in existing apps |9899> **Note on storage:** Only `redis` and `vercel-kv` are SDK-native providers. DynamoDB, Cloudflare KV, D1, and Durable Objects are platform-side — wire them in your tools using the platform SDK / Workers bindings. The Cloudflare build adapter actively rejects `redis: { ... }` and `sqlite: { ... }` configs at build time because Workers has no Node TCP / fs.100>101> **Note on browser:** "In-process direct client" means an in-memory `DirectClient` created via `connect()`/`create()` from `@frontmcp/sdk`. There is no separate "in-memory transport" — the client and server share the same JS heap.102103## Cross-Cutting Patterns104105| Pattern | Rule |106| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |107| Transport selection | Stateful servers (Node, CLI) can use stdio or SSE; serverless must use Streamable HTTP (stateless) |108| Storage mapping | SDK-native: `redis` (Node, Lambda+ElastiCache, CLI), `vercel-kv` (Vercel, can also work on Cloudflare via Upstash HTTP). Platform-side (you wire it in tools): DynamoDB, Cloudflare KV/D1/DO. Cloudflare build rejects `redis`/`sqlite` configs. |109| Environment variables | Never hardcode secrets; use `.env` locally, platform secrets in production |110| Build command | All targets: `frontmcp build --target <target>` produces optimized output |111| Entry point | All targets require `export default` of the `@FrontMcp` class from `main.ts` |112113## Common Patterns114115| Pattern | Correct | Incorrect | Why |116| ------------------ | ------------------------------------------------------- | --------------------------- | ---------------------------------------------------------------------------- |117| Target selection | Choose based on infrastructure constraints | Choose based on familiarity | Each target has different transport, storage, and cold-start characteristics |118| Serverless storage | Use platform-native storage (Vercel KV, DynamoDB) | Use Redis on serverless | Platform-native storage avoids VPC/connection overhead on cold starts |119| Environment config | Platform secrets (Vercel env, AWS SSM) | `.env` files in production | Platform secrets are encrypted, rotatable, and not committed to git |120| Build verification | Run `frontmcp build --target <target>` before deploying | Deploy source code directly | Build step validates config, bundles dependencies, and optimizes output |121122## Verification Checklist123124### Pre-Deployment125126- [ ] `frontmcp build --target <target>` completes without errors127- [ ] Environment variables configured for the target platform128- [ ] Storage provider configured and accessible (Redis, KV, DynamoDB, etc.)129- [ ] Transport protocol matches target requirements (stateless for serverless)130131### Post-Deployment132133- [ ] Health check endpoint responds134- [ ] `tools/list` returns expected tools135- [ ] Tool execution works end-to-end136- [ ] Storage persistence verified (create, read, restart, read again)137138## Troubleshooting139140| Problem | Cause | Solution |141| ---------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------- |142| Cold start timeout on serverless | Bundle too large or heavy initialization | Lazy-load providers; reduce bundle with tree shaking; increase function timeout |143| Session lost between requests | Using memory storage on stateless serverless | Switch to platform-native storage (Vercel KV, DynamoDB, etc.) |144| CORS errors on browser/web clients | HTTP CORS not configured | Add CORS config via `configure-http` skill |145| Build fails with missing module | Node-only module in browser/edge build | Use conditional imports or `@frontmcp/utils` cross-platform utilities |146147## Examples148149Each reference has matching examples under [`examples/<reference>/`](./examples/):150151### `build-for-browser`152153| Example | Level | Description |154| ---------------------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------- |155| [`browser-build-with-custom-entry`](./examples/build-for-browser/browser-build-with-custom-entry.md) | Intermediate | Build a browser bundle using a dedicated client entry file that avoids Node.js-only imports. |156| [`browser-crypto-and-storage`](./examples/build-for-browser/browser-crypto-and-storage.md) | Advanced | Use `@frontmcp/utils` crypto functions (WebCrypto API) and in-memory storage in browser environments. |157| [`react-provider-setup`](./examples/build-for-browser/react-provider-setup.md) | Basic | Connect a React application to a remote FrontMCP server using `@frontmcp/react`. |158159### `build-for-cli`160161| Example | Level | Description |162| ---------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------ |163| [`cli-binary-build`](./examples/build-for-cli/cli-binary-build.md) | Basic | Build a FrontMCP server as a standalone binary using Node.js Single Executable Applications (SEA). |164| [`unix-socket-daemon`](./examples/build-for-cli/unix-socket-daemon.md) | Intermediate | Run a FrontMCP server as a local daemon accessible via Unix socket for IDE extensions and local MCP clients. |165166### `build-for-mcpb`167168| Example | Level | Description |169| --------------------------------------------------------------------- | ----- | ---------------------------------------------------------------------------------------------- |170| [`mcpb-bundle-build`](./examples/build-for-mcpb/mcpb-bundle-build.md) | Basic | Produce a .mcpb archive for Claude Desktop with metadata, tools, and install-time user_config. |171172### `build-for-sdk`173174| Example | Level | Description |175| ------------------------------------------------------------------------------ | ------------ | ---------------------------------------------------------------------------------------------------------- |176| [`connect-openai`](./examples/build-for-sdk/connect-openai.md) | Intermediate | Use `connectOpenAI()` to get tools formatted for OpenAI's function-calling API. |177| [`create-flat-config`](./examples/build-for-sdk/create-flat-config.md) | Basic | Spin up an in-memory FrontMCP server from a flat config object using `create()`. |178| [`multi-platform-connect`](./examples/build-for-sdk/multi-platform-connect.md) | Advanced | Connect the same FrontMCP server to multiple LLM platforms using platform-specific `connect*()` functions. |179180### `deploy-to-cloudflare`181182| Example | Level | Description |183| ------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------- |184| [`basic-worker-deploy`](./examples/deploy-to-cloudflare/basic-worker-deploy.md) | Basic | Deploy a FrontMCP server to Cloudflare Workers with a minimal configuration. |185| [`worker-custom-domain`](./examples/deploy-to-cloudflare/worker-custom-domain.md) | Advanced | Scaffold a FrontMCP project targeting Cloudflare, configure a custom domain, and verify the deployment. |186| [`worker-with-kv-storage`](./examples/deploy-to-cloudflare/worker-with-kv-storage.md) | Intermediate | Deploy a FrontMCP server to Cloudflare Workers with KV namespace for session and state storage. |187188### `deploy-to-lambda`189190| Example | Level | Description |191| ------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------- |192| [`cdk-deployment`](./examples/deploy-to-lambda/cdk-deployment.md) | Advanced | Deploy a FrontMCP server to AWS Lambda using CDK with provisioned concurrency and secrets management. |193| [`lambda-handler-with-cors`](./examples/deploy-to-lambda/lambda-handler-with-cors.md) | Intermediate | Create a custom Lambda handler with an explicit API Gateway definition for CORS support. |194| [`sam-template-basic`](./examples/deploy-to-lambda/sam-template-basic.md) | Basic | Deploy a FrontMCP server to AWS Lambda with API Gateway using a SAM template. |195196### `deploy-to-node-dockerfile`197198| Example | Level | Description |199| ---------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------ |200| [`basic-multistage-dockerfile`](./examples/deploy-to-node-dockerfile/basic-multistage-dockerfile.md) | Basic | A minimal multi-stage Dockerfile for building and running a FrontMCP server in production. |201| [`secure-nonroot-dockerfile`](./examples/deploy-to-node-dockerfile/secure-nonroot-dockerfile.md) | Advanced | A production Dockerfile with a non-root user, proper ownership, and security hardening. |202203### `deploy-to-node`204205| Example | Level | Description |206| ------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------- |207| [`docker-compose-with-redis`](./examples/deploy-to-node/docker-compose-with-redis.md) | Basic | Deploy a FrontMCP server with Redis using Docker Compose for production. |208| [`pm2-with-nginx`](./examples/deploy-to-node/pm2-with-nginx.md) | Intermediate | Deploy a FrontMCP server on bare metal using PM2 for process management and NGINX for TLS termination. |209| [`resource-limits`](./examples/deploy-to-node/resource-limits.md) | Advanced | Configure resource limits, health checks, and environment variables for a production FrontMCP deployment. |210211### `deploy-to-vercel-config`212213| Example | Level | Description |214| ------------------------------------------------------------------------------------------------------------------ | ------------ | -------------------------------------------------------------------------------------------------- |215| [`minimal-vercel-config`](./examples/deploy-to-vercel-config/minimal-vercel-config.md) | Basic | The minimum `vercel.json` needed to deploy a FrontMCP server to Vercel. |216| [`vercel-config-with-security-headers`](./examples/deploy-to-vercel-config/vercel-config-with-security-headers.md) | Intermediate | A complete `vercel.json` with per-route security headers for health, MCP, and all other endpoints. |217218### `deploy-to-vercel`219220| Example | Level | Description |221| ------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------- |222| [`vercel-mcp-endpoint-test`](./examples/deploy-to-vercel/vercel-mcp-endpoint-test.md) | Advanced | Verify a Vercel-deployed FrontMCP server by testing health, tool listing, and tool invocation. |223| [`vercel-with-kv`](./examples/deploy-to-vercel/vercel-with-kv.md) | Basic | Deploy a FrontMCP server to Vercel serverless functions with Vercel KV for session persistence. |224| [`vercel-with-skills-cache`](./examples/deploy-to-vercel/vercel-with-skills-cache.md) | Intermediate | Deploy a FrontMCP server to Vercel with skills enabled and KV-backed skill caching. |225226### `mcp-client-integration`227228| Example | Level | Description |229| ------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------ |230| [`stdio-npx`](./examples/mcp-client-integration/stdio-npx.md) | Basic | Publish a FrontMCP server to npm and configure MCP clients to use it with npx --stdio. |231| [`http-remote`](./examples/mcp-client-integration/http-remote.md) | Basic | Connect an MCP client to a FrontMCP server running as an HTTP server, locally or remotely. |232| [`stdio-binary-with-env`](./examples/mcp-client-integration/stdio-binary-with-env.md) | Intermediate | Configure a local FrontMCP CLI binary with environment variables and custom arguments in MCP client configs. |233234## Accessing This Skill235236Skills are distributed as plain SKILL.md files plus a sibling `references/`237and `examples/` tree, so consumers can pick whichever access mode fits:238239| Mode | How it works |240| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |241| **Filesystem** | Read `libs/skills/catalog/frontmcp-deployment/` directly from a clone of the catalog repo, or from a published `@frontmcp/skills` install. SKILL.md is the entry point. |242| **`frontmcp` CLI** | `frontmcp skills list`, `frontmcp skills read frontmcp-deployment`, `frontmcp skills read frontmcp-deployment:references/<file>.md`, `frontmcp skills install frontmcp-deployment` — no server required. |243| **MCP `skill://`** | When a developer mounts this skill into their own FrontMCP server (`@FrontMcp({ skills: [...] })`), the SDK exposes it via SEP-2640 resources: `skill://frontmcp-deployment/SKILL.md`, `skill://frontmcp-deployment/references/{file}.md`, etc. The server’s `skill://index.json` returns the SEP-2640 discovery document for everything mounted on it. |244245The catalog itself is **not** an MCP server. The `skill://` URIs only resolve246when a server has been configured to host this skill.247248## Reference249250- [Runtime Modes](https://docs.agentfront.dev/frontmcp/deployment/runtime-modes)251- Related skills: `deploy-to-node`, `deploy-to-vercel`, `deploy-to-lambda`, `deploy-to-cloudflare`, `build-for-cli`, `build-for-browser`, `build-for-sdk`, `configure-transport`
agentfront