Chatgpt App Template

ChatGPT Apps SDK Template

Next.js starter template for building an OpenAI 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:

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

Reference: OpenAI Apps SDK MCP documentation

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:

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:

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)

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

It handles:

• history.pushState and history.replaceState
• window.fetch origin rewriting
• `` attribute mutations introduced by the ChatGPT host

Required setup:

  
    
  
  {children}

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

Getting Started

Installation

bun install

Development

bun run dev

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

MCP Endpoint

The MCP server is exposed at:

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.

Project Structure

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. 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
• OpenAI Apps SDK MCP server guide
• Model Context Protocol
• Next.js documentation

License

Apache License 2.0

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: amxv
• Source: amxv/chatgpt-app-template
• License: Apache-2.0
• Homepage: https://gg-chatgpt-app.vercel.app

Install and usage instructions live in the source repository linked above.