MCP App Framework

Quickstart

Create a new MCP App project with one command:

npx sunpeak new

This scaffolds a project with example tools, resources, simulations, and tests, then starts a dev server with HMR and opens the inspector at http://localhost:3000. An MCP endpoint starts at http://localhost:8000/mcp for testing with real hosts. See the full quickstart guide for step-by-step setup through production deployment.

What it does

The sunpeak framework is a convention-over-configuration structure for building MCP Apps. It bundles the inspector and testing framework with a structured project layout, auto-discovery, and a CLI. Building an MCP App from scratch means wiring up an MCP server, handling protocol details, managing resource HTML, and setting up a dev environment. sunpeak handles all of that and gives you a structured project with testing from the start.

sunpeak-app/
├── src/
│   ├── resources/
│   │   └── review/
│   │       └── review.tsx                   # Review UI component + resource metadata.
│   ├── tools/
│   │   ├── review-diff.ts                   # Tool with handler, schema, and optional resource link.
│   │   ├── review-post.ts                   # Multiple tools can share one resource.
│   │   └── review.ts                        # Backend-only tool (no resource, no UI).
│   └── server.ts                            # Optional: auth, server config.
├── tests/
│   ├── unit/
│   │   └── review.test.ts                   # Unit tests for component and hook logic.
│   ├── simulations/
│   │   ├── review-diff.json                 # Mock state for testing (includes serverTools).
│   │   ├── review-post.json                 # Mock state for testing (includes serverTools).
│   │   └── review-purchase.json             # Mock state for testing (includes serverTools).
│   ├── e2e/
│   │   └── review.spec.ts                   # Playwright tests against the inspector.
│   ├── live/
│   │   └── review.spec.ts                   # Live tests against real ChatGPT (one per resource).
│   └── evals/
│       └── review.eval.ts                   # Multi-model tool calling evals.
└── package.json

Convention Over Configuration

sunpeak discovers resources, tools, and simulations from your file system:

Resources from src/resources/{name}/{name}.tsx — each exports a React component and a resource config
Tools from src/tools/{name}.ts — each exports tool (metadata), schema (Zod), and a default handler. Tools with a resource field link to a resource UI.
Simulations from tests/simulations/{name}.json — JSON fixtures loaded by the inspector and used in E2E tests
Server config from src/server.ts (optional) — exports server for identity/icons and auth() for request authentication (see Authorization)

Runtime APIs

sunpeak provides multi-platform React hooks that wrap the MCP Apps protocol. Write your app logic once, deploy it across ChatGPT, Claude, and future hosts.

Data Hooks

Hook	Description
`useToolData()`	Tool input arguments, structured output, streaming partials, error and cancellation state
`useToolInfo()`	The active tool’s definition (name, description, schemas)
`useAppState()`	Persistent state shared with the model via `useUpdateModelContext()`
`useHostContext()`	Full host-provided context object
`useHostInfo()`	Host name, version, and reported capabilities

Environment Hooks

Hook	Description
`useTheme()`	`'light'` or `'dark'` from the host
`useDisplayMode()`	`'inline'`, `'pip'`, or `'fullscreen'`
`usePlatform()`	`'mobile'`, `'desktop'`, or `'web'`
`useLocale()`	BCP 47 language tag (e.g., `'en-US'`)
`useTimeZone()`	IANA time zone (e.g., `'America/New_York'`)
`useViewport()`	Container dimensions and constraints
`useSafeArea()`	Device safe area insets
`useDeviceCapabilities()`	Hover and touch support

Action Hooks

Hook	Description
`useCallServerTool()`	Call another tool on your MCP server
`useReadServerResource()`	Read a resource from your MCP server
`useListServerResources()`	List resources on your MCP server
`useSendMessage()`	Send a user message into the chat
`useUpdateModelContext()`	Push structured data to the model’s context
`useCreateSamplingMessage()`	Request an LLM completion via the host
`useOpenLink()`	Open a URL in the host browser
`useDownloadFile()`	Trigger a file download
`useRequestDisplayMode()`	Request inline/PiP/fullscreen switch
`useRequestTeardown()`	Ask the host to unmount the View
`useSendLog()`	Send a diagnostic log to the host
`useRegisterTool()`	Register a single app-side tool the host can call
`useAppTools()`	Declare a static set of app-side tools with a single `onCallTool`
`useSendToolListChanged()`	Notify the host that app-side tools changed
`useTeardown()`	Reactive flag set when the host requests teardown

See the Hooks API Reference for complete documentation.

Host Detection

Detect which host your app is running in — see Host Detection:

import { detectHost, isChatGPT, isClaude } from 'sunpeak/host';

if (isChatGPT()) {
  // ChatGPT-specific behavior
}

MCP Server

The MCP server lets you serve your apps to AI hosts like ChatGPT and Claude. During development, sunpeak dev runs an MCP server that serves simulation fixture data. For production, use sunpeak build followed by sunpeak start.

pnpm
npm
yarn

pnpm dev        # Dev server with HMR + inspector + MCP endpoint
pnpm build      # Build resources for production
pnpm start      # Start the production MCP server

npm run dev        # Dev server with HMR + inspector + MCP endpoint
npm run build      # Build resources for production
npm run start      # Start the production MCP server

yarn dev        # Dev server with HMR + inspector + MCP endpoint
yarn build      # Build resources for production
yarn start      # Start the production MCP server

See the Deployment Guide for connecting to hosts, tunnels, and production setup.

UI Components

The framework includes pre-built components in src/resources/ and shared components in src/components/. These follow MCP App design guidelines using Tailwind CSS with MCP standard variables:

<div className="text-[var(--color-text-primary)] bg-[var(--color-background-primary)]">
  Content that adapts to the host theme
</div>

See UI Components for the full list.

The sunpeak CLI

Command	Description
`sunpeak new`	Create a new project
`sunpeak dev`	Dev server with inspector and MCP endpoint
`sunpeak build`	Build resources for production
`sunpeak start`	Start the production MCP server
`sunpeak test`	Run unit, E2E, visual, live, and eval tests
`sunpeak inspect`	Inspect any MCP server (standalone)
`sunpeak upgrade`	Upgrade sunpeak to latest version

Dive Deeper

Inspector

Test MCP Apps in replicated ChatGPT and Claude runtimes.

Testing Framework

E2E tests against the inspector. Live tests against real hosts.

Project Scaffold

Detailed project structure and file conventions.

Deployment Guide

Deploy to production with tunnels and hosting.

​Quickstart

​What it does

​Convention Over Configuration

​Runtime APIs

​Data Hooks

​Environment Hooks

​Action Hooks

​Host Detection

​MCP Server

​UI Components

​The sunpeak CLI

​Dive Deeper