chatgpt-app-template — Next.js Starter Template

SHA-256: 62240ac53f7ee21dedf0bd4c47c1b63697bb92bee867d06f4409760736745308

2026-10-14T13:38:58.901Z

# ChatGPT Apps SDK Template

Next.js starter template for building an [OpenAI Apps SDK](https://developers.openai.com/apps-sdk) app with a Model Context Protocol (MCP) server, ChatGPT widget rendering, and a working end-to-end example.

This repo is meant to be cloned as a starting point for custom ChatGPT apps. It includes the plumbing needed to expose MCP tools to ChatGPT, render a UI inside the ChatGPT iframe, and handle the browser quirks that come with cross-origin widget rendering.

## Included Example: Doctor Finder

The starter ships with a small doctor finder demo so the template is easy to understand in a real workflow instead of just abstract SDK code.

The example includes:
- a `find_doctor` MCP tool registered in `app/mcp/route.ts`
- mock doctor data with specialty and symptom matching
- a widget UI that renders doctor cards inside ChatGPT
- structured tool output passed from ChatGPT into the Next.js widget

Use it as a reference for how to build your own vertical-specific app, then swap the sample domain model and UI for your own tools.

## Overview

This project shows how to integrate a Next.js application with the ChatGPT Apps SDK using MCP. It includes a working MCP server that exposes tools and resources ChatGPT can call, with responses rendered natively in ChatGPT as an interactive widget.

## Key Components

### 1. MCP Server Route (`app/mcp/route.ts`)

The MCP server registers tools and widget resources for ChatGPT.

Key pieces:
- tool registration with OpenAI-specific metadata
- resource registration for iframe rendering
- cross-linking between tools and widgets via `templateUri`
- structured tool output that the widget can read directly

OpenAI-specific metadata:

```typescript
{
  "openai/outputTemplate": widget.templateUri,
  "openai/toolInvocation/invoking": "Loading...",
  "openai/toolInvocation/invoked": "Loaded",
  "openai/widgetAccessible": false,
  "openai/resultCanProduceWidget": true
}
```

Reference: [OpenAI Apps SDK MCP documentation](https://developers.openai.com/apps-sdk/build/mcp-server)

### 2. Widget UI (`app/page.tsx`)

The root page is the widget rendered inside ChatGPT. In the sample app it:
- reads structured tool output through the Apps SDK hooks
- renders doctor search results as cards
- supports fullscreen mode
- shows a helpful fallback banner when opened outside ChatGPT

### 3. Asset Configuration (`next.config.ts`)

Set `assetPrefix` so `/_next/` static assets load from the correct origin:

```typescript
const nextConfig: NextConfig = {
  assetPrefix: baseURL,
};
```

Without this, Next.js will try to load assets from the iframe URL and you will get 404s.

### 4. CORS Middleware (`middleware.ts`)

The middleware handles browser preflight requests needed for cross-origin React Server Component fetching during client-side navigation:

```typescript
export function middleware(request: NextRequest) {
  if (request.method === "OPTIONS") {
    // Return 204 with CORS headers
  }
  // Add CORS headers to all responses
}
```

### 5. SDK Bootstrap (`app/layout.tsx`)

`<NextChatSDKBootstrap>` patches browser behavior so the widget works correctly inside the ChatGPT iframe.

It handles:
- `history.pushState` and `history.replaceState`
- `window.fetch` origin rewriting
- `<html>` attribute mutations introduced by the ChatGPT host

Required setup:

```tsx
<html lang="en" suppressHydrationWarning>
  <head>
    <NextChatSDKBootstrap baseUrl={baseURL} />
  </head>
  <body>{children}</body>
</html>
```

`suppressHydrationWarning` is currently needed because ChatGPT modifies the initial HTML before hydration.

## Getting Started

### Installation

```bash
bun install
```

### Development

```bash
bun run dev
```

Open `http://localhost:3000` to inspect the widget locally.

### MCP Endpoint

The MCP server is exposed at:

```text
http://localhost:3000/mcp
```

### Connecting From ChatGPT

1. Deploy the app somewhere publicly reachable, such as Vercel.
2. In ChatGPT, go to `Settings -> Connectors -> Create`.
3. Add your MCP server URL with the `/mcp` path, for example `https://your-app.vercel.app/mcp`.

Connecting MCP servers to ChatGPT requires developer mode access. See the [OpenAI connection guide](https://developers.openai.com/apps-sdk/deploy/connect-chatgpt).

## Project Structure

```text
app/
├── components/           # Widget UI components
├── data/                 # Sample doctor data
├── hooks/                # Apps SDK widget hooks
├── layout.tsx            # Root layout with SDK bootstrap
├── mcp/
│   └── route.ts          # MCP server with tool/resource registration
├── page.tsx              # ChatGPT widget UI
└── custom-page/          # Example extra route
middleware.ts             # CORS handling for RSC
next.config.ts            # Asset prefix configuration
```

## How The Doctor Finder Example Works

1. ChatGPT invokes the `find_doctor` tool exposed by `app/mcp/route.ts`.
2. The tool searches mock doctor data by symptom or specialty.
3. The tool response includes structured content plus the widget `templateUri`.
4. ChatGPT renders the widget in an iframe.
5. The Next.js widget reads the tool result and displays doctor cards.

This is the core pattern to reuse when adapting the template for other workflows such as commerce tools, scheduling, operations dashboards, or internal assistants.

## Deployment

This template is designed to work well on [Vercel](https://vercel.com). `baseUrl.ts` automatically detects Vercel environment variables so the widget can resolve static assets and runtime fetches correctly across production and preview deployments.

The configuration handles:
- production URLs via `VERCEL_PROJECT_PRODUCTION_URL`
- preview URLs via `VERCEL_BRANCH_URL`
- asset prefixing for iframe-safe resource loading

## Learn More

- [OpenAI Apps SDK documentation](https://developers.openai.com/apps-sdk)
- [OpenAI Apps SDK MCP server guide](https://developers.openai.com/apps-sdk/build/mcp-server)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [Next.js documentation](https://nextjs.org/docs)

## License

Apache License 2.0