runMCPServer

Overview

The runMCPServer function creates an MCP server that serves your built widgets to ChatGPT. It’s designed for local development and testing against the real ChatGPT platform.

This server is for local development only. For production, create your own MCP server that returns your published widget URL as a resource. See the Deployment Guide.

Quick Start

Framework
Library

The sunpeak framework handles MCP server configuration automatically:

sunpeak mcp

This discovers simulations in src/simulations/, links them to resources, and serves the built widgets from dist/.

For custom setups, configure the MCP server manually:

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

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

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

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

Connecting to ChatGPT

Once your MCP server is running:

Run a tunnel

Expose your local server with a tunnel:

ngrok http 6766

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 widget

Send a message that triggers your tool (e.g., “show albums”) to see your widget in ChatGPT.

ChatGPT caches UIs aggressively. The sunpeak MCP server serves resources at unique URIs to cache-bust, but you need to manually Refresh your app from the settings modal after changes.

Configuration Options

MCPServerConfig

name

string

default:"sunpeak-app"

MCP server name displayed in ChatGPT.

version

string

default:"0.1.0"

MCP server version.

port

number

default:"6766"

Server port. Can also be set via the PORT environment variable.

simulations

SimulationWithDist[]

required

Array of simulations with built widget paths. Each simulation must include:

distPath (string, required) - Path to the built widget JavaScript file
tool (Tool, required) - MCP Tool definition
resource (Resource, required) - MCP Resource definition
callToolResult (CallToolResult, 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 callToolResult.structuredContent.
Resources - One per simulation, containing the built widget HTML/JavaScript from distPath.

Your widget accesses the mock data via runtime hooks:

import { useWidgetProps, useToolResponseMetadata } from 'sunpeak';

function MyWidget() {
  // Data from callToolResult.structuredContent
  const props = useWidgetProps<{ items: string[] }>();

  // Metadata from callToolResult._meta
  const meta = useToolResponseMetadata();

  return <div>{props.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

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

​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