Skip to main content
sunpeak API

​
Overview

The runMCPServer function creates an MCP server that serves your built apps to hosts like ChatGPT. It’s designed for local development and testing against real MCP App hosts.
This server is for local development only. For production, use sunpeak start which runs your real tool handlers. See the Deployment Guide.

​
Quick Start

sunpeak handles MCP server configuration automatically: 
sunpeak dev
This starts the inspector and an MCP server with Hot Module Reload. The MCP server discovers tools from src/tools/ and simulations from tests/simulations/, and serves the apps with automatic rebuilding.

​
Connecting to ChatGPT

Once your MCP server is running:
1

Run a tunnel

Expose your local server with a tunnel:
ngrok http 8000
Copy the forwarding URL (e.g., https://abc123.ngrok.io).
2

Connect to ChatGPT

Open ChatGPT in developer mode and connect your app:
  1. Go to User > Settings > Apps & Connectors > Create.
  2. Enter your tunnel URL with the /mcp path: https://abc123.ngrok.io/mcp.
  3. Complete the connection flow.
3

Test your app

Send a message that triggers your tool (e.g., “show albums”) to see your app in ChatGPT.
ChatGPT caches UIs aggressively. The sunpeak MCP server offers HMR and serves resources at unique URIs to cache-bust, but you need to manually Refresh your app from the settings modal after certain changes.

​
Configuration Options

​
MCPServerConfig

​
name
string
default:"sunpeak-app"
MCP server name displayed in the host.
​
version
string
default:"0.1.0"
MCP server version.
​
port
number
default:"8000"
Server port. Can also be set via the PORT environment variable.
​
simulations
SimulationWithDist[]
required
Array of simulations with built resource paths. Each simulation must include:
  • distPath (string, required) - Path to the built resource HTML file
  • tool (Tool, required) - MCP Tool definition
  • resource (Resource, required) - MCP Resource definition
  • toolResult (object, optional) - Mock response data
See Simulation for the full interface.

​
Server Endpoints

The MCP server exposes:
EndpointMethodDescription
/mcpGETSSE stream for MCP communication
/mcp/messagesPOSTMessage endpoint for client requests

​
How It Works

The dev server creates MCP Tools and Resources from your tool files and simulations:
  1. Tools — One per simulation, using metadata from the corresponding src/tools/ file (tool config, schema). When called, returns the simulation’s toolResult.structuredContent as fixture data. Tool metadata including visibility is preserved.
  2. Resources — One per resource, containing the built resource HTML from distPath (or Vite HMR HTML for local connections). Resource metadata including permissions, csp, prefersBorder, and domain is preserved.
Your app accesses the mock data via runtime hooks: 
import { useToolData } from 'sunpeak';

function MyApp() {
  const { output } = useToolData<unknown, { items: string[] }>();

  return <div>{output?.items.map(item => <p key={item}>{item}</p>)}</div>;
}

​
Server Helpers

For custom MCP server setups, sunpeak/mcp re-exports server helpers from the MCP Apps SDK: 
import {
  registerAppTool,
  registerAppResource,
  getUiCapability,
  EXTENSION_ID,
  RESOURCE_URI_META_KEY,
  RESOURCE_MIME_TYPE,
} from 'sunpeak/mcp';
These are useful when building a fully custom MCP server. For most projects, sunpeak start handles production serving automatically. See the Deployment Guide for details.

​
See Also

MCP Server Guide

Step-by-step guide for connecting to ChatGPT.

Simulation

Complete simulation interface documentation.