Skip to main content

​
Overview

The sunpeak start command starts a production MCP server that serves your built resources and executes real tool handlers. Run sunpeak build first to compile your resources and tools. 
sunpeak build && sunpeak start

​
What It Does

The production server loads everything from dist/:
  1. Resources — Pre-built HTML bundles from dist/{name}/{name}.html with metadata from dist/{name}/{name}.json
  2. Tools — Compiled tool modules from dist/tools/*.js, registered with real handlers and Zod schemas for input validation
  3. Server entry — Optional dist/server.js for authentication and server metadata
Tools are registered with the MCP protocol using registerAppTool from the MCP Apps SDK. When a host calls a tool, the real handler executes — not simulation fixture data.

​
Options

OptionShortDescription
--port <number>-pServer port (default: 8000, also respects PORT env var)
--host <address>Bind address (default: 0.0.0.0, also respects HOST env var)
--json-logsOutput structured JSON lines to stdout/stderr
--sseUse SSE streaming instead of JSON responses (default: JSON)
--statelessStateless mode — no session tracking, fresh server per request. For serverless and horizontally-scaled deployments. See Deployment Guide.

​
Usage

# Default port (8000) on all interfaces
sunpeak start

# Custom port and host
sunpeak start --port 3000 --host 127.0.0.1

# Structured logging for production
sunpeak start --json-logs

# Via environment variables
PORT=3000 HOST=127.0.0.1 sunpeak start

​
Server Endpoints

EndpointMethodDescription
/healthGETHealth check — returns {"status":"ok","uptime":N}
/GETServer info page
/mcpPOSTInitialize a session or send messages
/mcpGETOpen an SSE stream for server-initiated notifications
/mcpDELETETerminate a session
The /health endpoint is for load balancer probes, Kubernetes liveness/readiness checks, and uptime monitoring. It is always unauthenticated. The production server uses the MCP Streamable HTTP transport. In the default stateful mode, session IDs are managed via the mcp-session-id header. In --stateless mode, only POST /mcp is available (no SSE streaming or session deletion).

​
Authentication

If your project includes a src/server.ts with an auth() export, the production server calls it on every MCP request. See Server Entry for details.

​
Testing Locally

To test production behavior locally, run the build and start commands together: 
sunpeak build && sunpeak start
Then expose the server with a tunnel (e.g., ngrok http 8000) and connect from ChatGPT.

sunpeak build

Build resources and compile tools.

Production Server API

createMcpHandler, createHandler, and config types.

Deployment Guide

Full deployment walkthrough with custom server examples.

sunpeak dev

Development server with inspector.