Production Server

sunpeak API

Overview

sunpeak provides three ways to run a production MCP server, from zero-config to full control:

Approach	Use case
`sunpeak start`	Zero-config — loads tools, resources, and auth from `dist/` automatically
`createMcpHandler`	Node.js — mount the MCP handler on your own Express/Fastify/http server
`createHandler`	Web Standard — Cloudflare Workers, Deno, Bun, Vercel Edge

sunpeak start auto-discovers tools from dist/tools/, resources from dist/{name}/, and the auth and oauth exports from dist/server.js, then passes them to startProductionHttpServer internally. createMcpHandler and createHandler accept these as config objects — you load and pass them yourself. This gives full control over how tools, resources, and auth are provided. All three use MCP Streamable HTTP transport on a single /mcp endpoint.

`createMcpHandler`

Creates a Node.js request handler for MCP over Streamable HTTP.

import { createMcpHandler } from 'sunpeak/mcp';
import type { ProductionServerConfig } from 'sunpeak/mcp';

const handler = createMcpHandler(config);
// handler: (req: IncomingMessage, res: ServerResponse) => Promise<void>

The handler responds to POST /mcp, GET /mcp, DELETE /mcp, and OPTIONS /mcp. For unmatched paths it does nothing, so you can chain it with your own routes.

Example: Express

import express from 'express';
import { createMcpHandler } from 'sunpeak/mcp';

const app = express();
app.get('/health', (req, res) => res.json({ ok: true }));

// tools: ProductionTool[], resources: ProductionResource[], auth: AuthFunction
const mcpHandler = createMcpHandler({ tools, resources, auth });
app.use((req, res, next) => {
  mcpHandler(req, res).then(() => {
    if (!res.headersSent) next();
  });
});

app.listen(3000);

`ProductionServerConfig`

string

default:"sunpeak-app"

Server name reported to hosts during MCP handshake.

string

default:"0.1.0"

Server version reported to hosts.

ServerConfig

Full server identity. Overrides name and version when provided. Supports additional fields like title, description, websiteUrl, icons, and instructions (sent in the MCP initialize response so hosts can inject it into the model’s system prompt). See Server Entry for the full field list.

ProductionTool[]

required

Tool registrations. Each has a name, tool config (optional resource link, title, description), optional schema (Zod shape for input validation), and handler function. Tools without a resource are registered as plain MCP tools (no UI).

ProductionResource[]

required

Resource registrations. Each has a name, uri, html (self-contained HTML string), and optional _meta.

(req: IncomingMessage, context: AuthorizationContext) => AuthInfo | AuthorizationFailure | null

Auth function called on every request. Return AuthInfo to authenticate, null for an initial 401, or AuthorizationFailure for an invalid-token or insufficient-scope challenge. context.body contains the parsed MCP request. See Authorization.

OAuthProtectedResourceConfig

Protected-resource discovery and bearer challenge configuration. When set, the handler serves RFC 9728 metadata at the root and endpoint-specific well-known paths and adds resource_metadata to WWW-Authenticate.

string

Public URL of the MCP server (e.g. 'https://example.com/mcp'). Used to auto-compute a default _meta.ui.domain for resources that don’t specify one. Without this, resources without an explicit domain may trigger host warnings (e.g. ChatGPT’s “Widget domain is not set”).

boolean

default:"true"

Respond with JSON instead of SSE streams. Recommended for serverless environments (Lambda, Workers, Vercel Edge) where holding open SSE connections is unreliable. Set to false if you need SSE streaming for long-running tool calls.

number

default:"15000"

Interval in milliseconds between SSE keep-alive comments when enableJsonResponse is false. Set to 0 to disable keep-alives.

boolean

default:"false"

Enable stateless v1 transport mode for serverless and horizontally-scaled deployments. When true, every request creates a fresh MCP server instance with no session tracking. This does not enable the core MCP 2026-07-28 wire protocol. The host is identified from HTTP headers (User-Agent, x-anthropic-client, x-openai-session) on every request. See Serverless Deployment, Horizontal Scaling, and MCP 2026-07-28 for MCP Apps.

`createHandler`

Creates a Web Standard request handler for serverless and edge runtimes.

import { createHandler } from 'sunpeak/mcp';
import type { WebHandlerConfig } from 'sunpeak/mcp';

const handler = createHandler(config);
// handler: (req: Request) => Promise<Response>

Unlike createMcpHandler, this handler does not do path matching — it handles every request it receives. Mount it behind your own router.

Example: Cloudflare Worker

import { createHandler } from 'sunpeak/mcp';

const handler = createHandler({ tools, resources, auth });
export default { fetch: handler };

Example: Hono

import { Hono } from 'hono';
import { createHandler } from 'sunpeak/mcp';

const app = new Hono();
const handler = createHandler({ tools, resources });
app.all('/mcp', (c) => handler(c.req.raw));
export default app;

`WebHandlerConfig`

Same shape as ProductionServerConfig (including oauth, enableJsonResponse, sseKeepAliveMs, and stateless), except auth takes a Web Standard Request:

(req: Request, context: AuthorizationContext) => AuthInfo | AuthorizationFailure | null

Auth function for Web Standard environments. The return behavior matches the Node handler.

`startProductionHttpServer`

The built-in HTTP server used by sunpeak start. A convenience wrapper around createMcpHandler that adds a health check endpoint (/health), root page, favicon, and graceful shutdown.

import { startProductionHttpServer } from 'sunpeak/mcp';

// Simple: port only
startProductionHttpServer(config, 3000);

// Full options
startProductionHttpServer(config, { port: 3000, host: '127.0.0.1' });

The second argument accepts either a port number or an HttpServerOptions object:

number

default:"8000"

HTTP port to listen on.

string

default:"0.0.0.0"

Host/interface to bind to. Use 127.0.0.1 to restrict to localhost.

For most projects, use sunpeak start instead of calling this directly.

`setJsonLogging`

Enable structured JSON logging for all production server log output.

import { setJsonLogging } from 'sunpeak/mcp';

setJsonLogging(true);

When enabled, all log messages are written as JSON lines ({"ts":"...","level":"info","msg":"..."}) to stdout (info/warn) or stderr (errors). This is useful for log aggregation tools like Datadog, CloudWatch, or Loki. The sunpeak start --json-logs flag calls this automatically.

sunpeak start

Zero-config production server CLI.

Deployment Guide

Full deployment walkthrough with custom server examples.

Getting Started

CLI

Components

Functions

Hooks

Resources

Tools

Guides

Production Server

Overview

`createMcpHandler`

Example: Express

`ProductionServerConfig`

`createHandler`

Example: Cloudflare Worker

Example: Hono

`WebHandlerConfig`

`startProductionHttpServer`

`setJsonLogging`

See Also

sunpeak start

Deployment Guide

​Overview

​createMcpHandler

​Example: Express

​ProductionServerConfig

​createHandler

​Example: Cloudflare Worker

​Example: Hono

​WebHandlerConfig

​startProductionHttpServer

​setJsonLogging

​See Also

sunpeak start

Deployment Guide

Overview

`createMcpHandler`

Example: Express

`ProductionServerConfig`

`createHandler`

Example: Cloudflare Worker

Example: Hono

`WebHandlerConfig`

`startProductionHttpServer`

`setJsonLogging`

See Also