Skip to main content
Definitions: An MCP App is an interactive UI embedded in an agent conversation.A ChatGPT App is an MCP App with optional ChatGPT-specific features.The UI of an MCP App is an MCP Resource.The API of an MCP App is an MCP Tool.More on MCP here.
This documentation is available via MCP at https://docs.sunpeak.ai/mcp, use it in your coding agent!

​
Overview

sunpeak is an npm package that helps you build MCP Apps — interactive UIs that run inside AI chat hosts like ChatGPT and Claude. sunpeak consists of:

​
The sunpeak Library

  1. Runtime APIs: Strongly typed APIs for the MCP Apps runtime, architected for multi-platform support (ChatGPT, Claude, and more).
  2. Simulator: React component replicating the host runtime to test Apps locally and automatically.
  3. MCP Server: Serve Resources with mock data to real hosts with HMR (no more cache issues or 5-click manual refreshes).

​
The sunpeak Framework

Next.js for MCP Apps. Using a Review page as an example, sunpeak projects look like: 
my-app/
├── src/resources/
│   └── review/
│       └── review-resource.tsx # Review UI component + resource metadata.
├── tests/simulations/
│   └── review/
│       ├── review-{scenario1}-simulation.json  # Mock state for testing.
│       └── review-{scenario2}-simulation.json  # Mock state for testing.
└── package.json
  1. Project Scaffold: Complete development setup with the sunpeak library.
  2. UI Components: Production-ready components following MCP App design guidelines.
  3. Convention over configuration:
    • Create UIs by creating a -resource.tsx file that exports a ResourceConfig and a React component (example).
    • Create test state (simulations) for local dev, host testing, automated testing, and demos by creating a -simulation.json file (example).

​
The sunpeak CLI

Commands for managing MCP Apps:
  • sunpeak new - Create a new project
  • sunpeak dev - Start dev server with MCP endpoint and live simulator
  • sunpeak build - Build resources for production
  • sunpeak upgrade - Upgrade sunpeak to latest version

​
Examples

Example sunpeak resource & simulation files for an MCP App called “Review”.

​
Resource

Each resource .tsx file exports both a ResourceConfig metadata object and the React component: 
// src/resources/review/review-resource.tsx

import { useToolData } from 'sunpeak';
import type { ResourceConfig } from 'sunpeak';

export const resource: ResourceConfig = {
  name: 'review',
  description: 'Visualize and review a code change',
  _meta: { ui: { csp: { resourceDomains: ['https://cdn.openai.com'] } } },
};

export function ReviewResource() {
  const { output: data } = useToolData<unknown, { title: string }>();

  return <h1>Review: {data?.title}</h1>;
}

​
Simulation

Testing an MCP App requires setting a lot of state: state in your backend (accessed via MCP tool), the app runtime, and the host agent itself. Simulation files let you define key App states for development, automated testing, and demo purposes. Simulation files contain an official MCP Tool object and tool result data with structured content. Host state (like light/dark mode) is not set on the simulation, but rather on the sunpeak simulator itself via UI, props, or URL params. 
// tests/simulations/review-diff-simulation.json

{
  // Official MCP tool object.
  "tool": {
    "name": "review-diff",
    "description": "Show a review dialog for a proposed code diff",
    "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false },
    "title": "Diff Review",
    "annotations": { "readOnlyHint": false },
    "_meta": {
      "ui": { "visibility": ["model", "app"] },
    },
  },
  // Tool input arguments (sent to CallTool).
  "toolInput": {
    "changesetId": "cs_789",
    "title": "Refactor Authentication Module",
  },
  // Tool result data (CallToolResult response).
  "toolResult": {
    "structuredContent": {
      "title": "Refactor Authentication Module",
      // ...
    },
  },
}