Claude Simulator for MCP Apps: Test Claude Apps Locally with sunpeak

Source: Dev.to

Source: Dev.to – Claude Simulator for MCP Apps: Test Claude Apps Locally with sunpeak

TL;DR: sunpeak v0.15 adds a local Claude simulator. Run sunpeak dev, pick Claude from the Host dropdown (or use the ?host=claude URL parameter), and test your MCP App in both Claude and ChatGPT from a single dev server.

Until now, Sunpeak’s local simulator only replicated the ChatGPT runtime. If you wanted to see how your MCP App behaved in Claude, you had to deploy it and connect manually. That’s fixed.

sunpeak v0.15 ships with first‑class Claude support. The old ChatGPTSimulator is now just Simulator, and both Claude and ChatGPT are registered as host shells out of the box. Switch between them with a dropdown, a URL parameter, or a prop.

What Changed

• Multi‑host simulator
  The simulator now supports a pluggable host‑shell system instead of a single ChatGPT‑specific component. Each host registers its own conversation UI, color palette, and theme behavior. The Simulator component renders the selected host.

• Default hosts

  1. ChatGPT – familiar gray/white palette with the ChatGPT conversation layout.
  2. Claude – warm beige/cream palette matching claude.ai, with Claude’s conversation chrome.

• Host‑specific capabilities

  • ChatGPT – supports extra features such as file uploads/downloads on top of the standard MCP App protocol.
  • Claude – currently implements only the core MCP App protocol; the shell handles Claude’s rendering quirks. Future Claude‑specific APIs will be added here.

Your resource component renders in both environments, wrapped in each host’s chat UI, so you see exactly what your users will see.

How to Use It

Existing Sunpeak Project

# Upgrade to v0.15 and migrate CSS classes
sunpeak upgrade

# Start the development server
sunpeak dev

Open http://localhost:3000. A Host dropdown appears in the simulator sidebar.

• Claude – test your app in the Claude runtime.
• ChatGPT – switch back to the ChatGPT runtime.

New Project

# Install Sunpeak globally
pnpm add -g sunpeak

# Scaffold a new project
sunpeak new

# Run the dev server
cd my-app && sunpeak dev

The scaffolded project uses the new Simulator component by default, with both hosts available from the first run.

Host Selection

You can pick a host in three ways:

1. Sidebar dropdown – appears when multiple hosts are registered; click to switch at runtime.
2. URL parameter – add ?host=claude or ?host=chatgpt to the simulator URL. Great for bookmarking or sharing a specific configuration.
3. defaultHost prop – set the initial host in code:

import { Simulator } from 'sunpeak/simulator';

<Simulator defaultHost="claude" />

If you don’t specify a host, the default is chatgpt.

Migrating from ChatGPTSimulator

If your project still imports the old ChatGPTSimulator from sunpeak/chatgpt, it currently works as an alias to the new simulator. This alias will be removed soon, so update your imports now.

Before

import { ChatGPTSimulator } from 'sunpeak/chatgpt';

After

import { Simulator } from 'sunpeak/simulator';

Note:
The simulations, resource components, and test suite remain unchanged. The new Simulator simply adds the host dropdown and Claude’s rendering behavior.

What Your App Looks Like in Claude

The Claude host shell wraps your resource component in Claude’s conversation UI:

• Background – uses Claude’s warm beige and gray tones.
• User messages – appear in Claude‑style bubbles.
• Toolbar & display‑mode controls – inline, fullscreen, and picture‑in‑picture work the same as in ChatGPT.

Shared Core Data Flow

• useToolData – receives tool output.
• useAppState – syncs state back to the host.
• SafeArea – handles safe‑rendering boundaries.

Host‑Specific Differences

• ChatGPT supports file uploads/downloads.
• Claude currently has no file‑transfer APIs, but any future Claude‑specific APIs will be exposed through the same shell system.

The simulator lets you catch these differences locally instead of deploying.

Extensible Host System

The host‑shell registry is open. When a new major MCP App host appears, Sunpeak can add support without changing the Simulator component or your resource code. Each host registers itself with:

• id – a unique identifier for the host
• label – a human‑readable name displayed in UI components
• conversation component – the module that handles dialogue with the host
• optional theme – UI styling specific to the host (e.g., colors, icons)
• extra‑API hooks – any additional interfaces the host wishes to expose

This design ensures that adding or updating hosts is a plug‑and‑play experience for developers.

Theme & Styling

• Theme function: (add description here)
• Style variables: (list variables here)

The simulator automatically picks up all registered hosts.
For now, Claude and ChatGPT cover the two largest MCP App hosts.

Getting Started

pnpm add -g sunpeak
sunpeak new
cd my-app && sunpeak dev

• Enter fullscreen mode
• Exit fullscreen mode

Open the application, select Claude from the Host dropdown, and start building.

Helpful Guides

• How to Build a Claude App – Architecture and code patterns for Claude.
• ChatGPT App Tutorial – Walkthrough for building a resource from scratch (the same steps work for Claude).
• Building One MCP App for ChatGPT and Claude – Cross‑platform story.
• Testing Guide – Vitest and Playwright setup.
• Sunpeak Documentation – Quickstart and full API reference.

Build once with Sunpeak, test locally in both Claude and ChatGPT, and ship to every MCP App host.