runMCPServer

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, create your own MCP server that returns your published resource URL. See the Deployment Guide.

Quick Start

Framework
Library

The sunpeak framework handles MCP server configuration automatically:

sunpeak dev

This starts the ChatGPT simulator and an MCP server with Hot Module Reload. The MCP server discovers simulations from tests/simulations/{name}/ and serves the apps with automatic rebuilding.

For custom setups, configure the MCP server manually:

import { runMCPServer } from 'sunpeak/mcp';
import path from 'path';
import { fileURLToPath } from 'url';
import { resource } from '../src/resources/example/example-resource';
import exampleSimulation from '../tests/simulations/example/example-show-simulation.json';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

const simulations = [{
  ...exampleSimulation,
  resource,
  distPath: path.resolve(__dirname, '../dist/example/example.html'),
}];

runMCPServer({
  name: 'My App',
  version: '0.1.0',
  simulations,
  port: 8000,
});

Connecting to ChatGPT

Once your MCP server is running:

Run a tunnel

Expose your local server with a tunnel:

ngrok http 8000

Copy the forwarding URL (e.g., https://abc123.ngrok.io).

Connect to ChatGPT

Open ChatGPT in developer mode and connect your app:

Go to User > Settings > Apps & Connectors > Create.
Enter your tunnel URL with the /mcp path: https://abc123.ngrok.io/mcp.
Complete the connection flow.

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:

Endpoint	Method	Description
`/mcp`	GET	SSE stream for MCP communication
`/mcp/messages`	POST	Message endpoint for client requests

How It Works

The server creates MCP Tools and Resources from your simulations:

Tools - One per simulation, using the tool definition. When called, returns toolResult.structuredContent.
Resources - One per simulation, containing the built resource HTML from distPath.

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>;
}

MCP Server Guide

Step-by-step guide for connecting to ChatGPT.

Simulation

Complete simulation interface documentation.

CLI

Simulations

Resource Library

Hooks

Components

Overview

Quick Start

Connecting to ChatGPT

Configuration Options

MCPServerConfig

Server Endpoints

How It Works

See Also

MCP Server Guide

Simulation

CLI

Simulations

Resource Library

Hooks

Components

​Overview

​Quick Start

​Connecting to ChatGPT

​Configuration Options

​MCPServerConfig

​Server Endpoints

​How It Works

​See Also

MCP Server Guide

Simulation

Overview

Quick Start

Connecting to ChatGPT

Configuration Options

MCPServerConfig

Server Endpoints

How It Works

See Also