Deployment

​

Build for Production

pnpm build

npm run build

yarn build

dist/
├── albums/
│   ├── albums.html    # Self-contained HTML (JS + CSS inlined)
│   └── albums.json    # Resource metadata (_meta, name, uri)
├── tools/
│   ├── show-albums.js # Compiled tool handler + schema
│   └── ...
├── server.js          # Compiled server entry (if src/server.ts exists)
└── ...

​

Start the Production Server

pnpm start

npm run start

yarn start

pnpm start -- --port 3000          # Custom port
pnpm start -- --host 127.0.0.1     # Bind to localhost only
pnpm start -- --json-logs           # Structured JSON logging
pnpm start -- --sse                 # Use SSE streaming instead of JSON responses
pnpm start -- --stateless           # Stateless mode (no session tracking)
PORT=3000 HOST=127.0.0.1 pnpm start  # Or via environment variables

npm run start -- --port 3000          # Custom port
npm run start -- --host 127.0.0.1     # Bind to localhost only
npm run start -- --json-logs           # Structured JSON logging
npm run start -- --sse                 # Use SSE streaming instead of JSON responses
npm run start -- --stateless           # Stateless mode (no session tracking)
PORT=3000 HOST=127.0.0.1 npm run start  # Or via environment variables

yarn start --port 3000          # Custom port
yarn start --host 127.0.0.1     # Bind to localhost only
yarn start --json-logs           # Structured JSON logging
yarn start --sse                 # Use SSE streaming instead of JSON responses
yarn start --stateless           # Stateless mode (no session tracking)
PORT=3000 HOST=127.0.0.1 yarn start  # Or via environment variables

• Registers each tool from dist/tools/ with its real handler and Zod schema (input validation)
• Serves pre-built resource HTML from dist/{name}/{name}.html
• Calls your auth() function from src/server.ts on every request (if present)
• Uses MCP Streamable HTTP transport on a single /mcp endpoint
• Provides a /health endpoint for load balancer probes and uptime monitoring
• Handles graceful shutdown on SIGTERM/SIGINT

​

Testing Locally

pnpm build && pnpm start

npm run build && npm run start

yarn build && yarn start

​

Custom Server Setup

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

const app = express();

// Your middleware
app.use(cors({ origin: 'https://chatgpt.com' }));
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);

​

Serverless / Edge Deployment

// Cloudflare Worker
import { createHandler } from 'sunpeak/mcp';

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

// Hono (any runtime)
import { Hono } from 'hono';
import { createHandler } from 'sunpeak/mcp';

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

​

Stateless vs Stateful Mode

• Serverless (Lambda, Workers, Vercel Edge) where each request may hit a different instance with no shared memory
• Horizontally scaled deployments where configuring sticky sessions isn’t practical

​

Domain Resolution in Stateless Mode

const handler = createHandler({
  tools,
  resources,
  stateless: true,
  serverUrl: 'https://my-app.example.com/mcp',
});

​

Production Operations

​

Health Checks

{ "status": "ok", "uptime": 3600 }

​

Structured Logging

pnpm start -- --json-logs

npm run start -- --json-logs

yarn start --json-logs

{"ts":"2025-01-15T10:30:00.000Z","level":"info","msg":"Session started: a1b2c3d4...","sessionId":"a1b2c3d4-...","active":1}
{"ts":"2025-01-15T10:30:01.000Z","level":"info","msg":"CallTool: show-albums{artist}"}

​

Binding Interface

pnpm start -- --host 127.0.0.1
HOST=127.0.0.1 pnpm start

npm run start -- --host 127.0.0.1
HOST=127.0.0.1 npm run start

yarn start --host 127.0.0.1
HOST=127.0.0.1 yarn start

​

Process Management

# Docker
CMD ["sunpeak", "start", "--json-logs"]

# PM2
pm2 start "sunpeak start --json-logs" --name sunpeak-app

# systemd
ExecStart=/usr/bin/sunpeak start --json-logs

​

Reverse Proxy

# nginx
location /mcp {
    proxy_pass http://127.0.0.1:8000;
    proxy_http_version 1.1;
    proxy_set_header Connection '';
    proxy_buffering off;       # Required if enableJsonResponse is false (SSE mode)
}

location /health {
    proxy_pass http://127.0.0.1:8000;
}

​

Horizontal Scaling

• AWS ALB: Enable target group stickiness
• nginx: Use ip_hash or sticky cookie
• Cloudflare: Enable session affinity
• Kubernetes: Set session affinity annotations on your Ingress

pnpm start -- --stateless

npm run start -- --stateless

yarn start --stateless

const handler = createMcpHandler({
  tools,
  resources,
  stateless: true,
});

​

What Not to Worry About

• TLS/HTTPS — Use a reverse proxy (nginx, Caddy, Cloudflare)
• Rate limiting — Configure at the proxy or CDN level
• Request body limits — Handled by the proxy or platform

​

Publish to ChatGPT

​

Prerequisites

• Your MCP server is deployed at a public production HTTPS URL.
• Your resources are built with sunpeak build.
• The submitter has Apps Management: Write access for the OpenAI Platform organization. Organization owners already have this access.
• The publisher has completed individual or business identity verification in the same organization and project used for submission.
• You can serve the domain verification token at /.well-known/openai-apps-challenge on the MCP hostname or an allowed parent hostname.
• If sign-in is required, reviewer credentials work without MFA, SMS, email confirmation, or private-network access.

​

Prepare the submission

• Plugin name, short and long descriptions, logo, category, website, support URL, privacy policy URL, and terms URL.
• Production MCP server URL, authentication details, and reviewer credentials when needed.
• A content security policy listing the exact domains the app fetches from.
• Clear tool names, descriptions, input schemas, output shapes, and accurate readOnlyHint, openWorldHint, and destructiveHint annotations for every tool.
• Starter prompts that show realistic workflows.
• Exactly five positive test cases and three negative test cases, including expected behavior and any fixture data.
• Country or region availability and release notes.

​

Submit the MCP-backed plugin

1. Open the plugin submission portal and select Create plugin.
2. Choose With MCP for an app-only plugin or an app-plus-skills plugin.
3. Complete the public listing and publisher identity fields.
4. Enter the production MCP server URL, configure authentication, and provide demo credentials when required.
5. Add the app’s content security policy.
6. Complete domain verification if the portal asks for it. The challenge endpoint must return only the exact token as plain text.
7. Select Scan Tools, fix any server or metadata errors, deploy the fixes, and scan again.
8. Add starter prompts, five positive tests, three negative tests, availability, release notes, and policy attestations.
9. Select Submit for Review.

​

Production Checklist

• Set an exact CSP (Content Security Policy) for your resources.
• Configure CORS if serving from a different domain.
• Set up HTTPS for secure communication.
• Verify that tool annotations match real behavior.
• Confirm that the domain challenge and reviewer credentials work from the public internet.
• Check that listing URLs and publisher identity match.