Skip to main content
MCP App Simulator

​
Overview

The simulator is a local development environment that replicates the ChatGPT App host runtime. It uses the ChatGPTSimulator React component.

​
Why Use the Simulator?

Instant Feedback

See changes immediately with hot module replacement. No more cache issues or constantly reloading the host.

Visualize Design Variations

Toggle between light/dark themes, mobile/tablet/desktop views, and other platform states.

Testing

Perform manual and automated tests locally. Create CI/CD integration and regression tests.

No Deployment Needed

Develop locally without setting up MCP servers.

​
Quick Start

If you set up your project via the sunpeak framework, the simulator is already set up! Simply run it with: 
sunpeak dev
To configure the simulator manually, see Add to Existing Project.

​
Simulations

Simulations define test scenarios for your resources — combining tool definitions, mock data, and platform state.
Fun fact: Some science fiction authors believe we live in a sunpeak simulation.
In the sunpeak framework, simulations are JSON files that live in tests/simulations/.Simulations live in tests/simulations/{name}/:
// tests/simulations/example/example-show-simulation.json
{
  "userMessage": "Show me an example",
  "tool": {
    "name": "show-example",
    "description": "Show an example simulation",
    "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false },
    "title": "Show Example",
    "annotations": { "readOnlyHint": true },
    "_meta": {
      "ui": { "visibility": ["model", "app"] }
    }
  },
  "toolResult": {
    "structuredContent": null
  }
}
The resource component and metadata are co-located in a single file (src/resources/example/example-resource.tsx) and automatically linked to simulations based on matching folder names.
For library users not using the framework, see the Simulation API Reference for creating simulations programmatically in TypeScript.
See Framework Simulations for the complete JSON schema and conventions.
Simulations can be passed into:
The ChatGPTSimulator component provides a local development environment that replicates the host runtime.For projects using the sunpeak framework, simulations are auto-discovered. Just run:
sunpeak dev
For custom setups, you can manually configure the simulator:
import { ChatGPTSimulator } from 'sunpeak/chatgpt';
import { resource } from './resources/example/example-resource';
import exampleSimulation from './resources/example/example-show-simulation.json';

// Combine simulation with resource
const simulations = [{
  ...exampleSimulation,
  resource,
  resourceUrl: 'http://localhost:3000/resources/example',
}];

<ChatGPTSimulator
  simulations={simulations}
  appName="My App"
  appIcon="🌄"
/>
View ChatGPTSimulator API Reference
The runMCPServer function serves your simulations to hosts like ChatGPT via the Model Context Protocol.
# Framework - dev server includes MCP server with HMR
sunpeak dev

# Library - see runMCPServer API Reference for manual setup
See runMCPServer API Reference for configuration options and connecting to a host.View MCP Server API Reference

​
Dive Deeper

Framework Simulations

JSON-based simulations with auto-discovery for framework users.

Simulation API Reference

TypeScript interface for library users.

ChatGPTSimulator API Reference

Full component documentation and configuration options.