> ## Documentation Index
> Fetch the complete documentation index at: https://sunpeak.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# runMCPServer

> Serve your MCP Apps to hosts like ChatGPT via the Model Context Protocol.

<Badge color="yellow">sunpeak API</Badge>

## 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.

<Warning>
  This server is for **local development only**. For production, use `sunpeak start` which runs your real tool handlers. See the [Deployment Guide](/app-framework/guides/deployment).
</Warning>

## Quick Start

sunpeak handles MCP server configuration automatically:

<Tabs>
  <Tab title="pnpm">
    ```bash theme={null}
    pnpm dev
    ```
  </Tab>

  <Tab title="npm">
    ```bash theme={null}
    npm run dev
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn dev
    ```
  </Tab>
</Tabs>

This starts the inspector and an MCP server with Hot Module Reload.
The MCP server discovers tools from `src/tools/` and simulations from `tests/simulations/`, and serves the apps with automatic rebuilding.

## Connecting to ChatGPT

Once your MCP server is running:

<Steps>
  <Step title="Run a tunnel">
    Expose your local server with a tunnel:

    ```bash theme={null}
    ngrok http 8000
    ```

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

  <Step title="Connect to ChatGPT">
    Open ChatGPT and connect your app:

    1. If Developer mode is not already enabled, click your user menu in the bottom-left corner and select `Settings > Security and login > Developer mode`.
    2. Return to the ChatGPT homepage and click `Plugins` in the sidebar.
    3. Open your app if it is already there, or select the `+` button to add it.
    4. If you are adding the app, enter your tunnel URL with the `/mcp` path (`https://abc123.ngrok.io/mcp`) and complete the app form.
  </Step>

  <Step title="Test your app">
    Send a message that triggers your tool (e.g., "show albums") to see your app in ChatGPT.

    <Warning>
      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 its plugin details after certain changes.
    </Warning>
  </Step>
</Steps>

## Configuration Options

### MCPServerConfig

<ResponseField name="name" type="string" default="sunpeak-app">
  MCP server name displayed in the host.
</ResponseField>

<ResponseField name="version" type="string" default="0.1.0">
  MCP server version.
</ResponseField>

<ResponseField name="port" type="number" default="8000">
  Server port. Can also be set via the `PORT` environment variable.
</ResponseField>

<ResponseField name="simulations" type="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](/testing/simulations) for the full interface.
</ResponseField>

## 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 dev server creates MCP [Tools](/mcp-apps/mcp/tools) and [Resources](/mcp-apps/mcp/resources) from your tool files and simulations:

1. **Tools** — One per simulation, using metadata from the corresponding `src/tools/` file (`tool` config, `schema`). When called, returns the simulation's `toolResult.structuredContent` as fixture data. Tool metadata including `visibility` is preserved.
2. **Resources** — One per resource, containing the built resource HTML from `distPath` (or Vite HMR HTML for local connections). Resource metadata including `permissions`, `csp`, `prefersBorder`, and `domain` is preserved.

Your app accesses the mock data via runtime hooks:

```typescript theme={null}
import { useToolData } from 'sunpeak';

function MyApp() {
  const { output } = useToolData<unknown, { items: string[] }>();

  return <div>{output?.items.map(item => <p key={item}>{item}</p>)}</div>;
}
```

## Server Helpers

For custom MCP server setups, `sunpeak/mcp` re-exports server helpers from the MCP Apps SDK:

```typescript theme={null}
import {
  registerAppTool,
  registerAppResource,
  getUiCapability,
  EXTENSION_ID,
  RESOURCE_URI_META_KEY,
  RESOURCE_MIME_TYPE,
} from 'sunpeak/mcp';
```

These are useful when building a fully custom MCP server. For most projects, `sunpeak start` handles production serving automatically. See the [Deployment Guide](/app-framework/guides/deployment) for details.

## See Also

<Card horizontal title="MCP Server Guide" icon="server" href="/app-framework/mcp-server">
  Step-by-step guide for connecting to ChatGPT.
</Card>

<Card horizontal title="Simulation" icon="code" href="/testing/simulations">
  Complete simulation interface documentation.
</Card>