ChatGPT Apps SDK Next.js Starter

A minimal Next.js application demonstrating how to build an OpenAI Apps SDK compatible MCP server with widget rendering in ChatGPT.

Overview

This project shows how to integrate a Next.js application with the ChatGPT Apps SDK using the Model Context Protocol (MCP). It includes a working MCP server that exposes tools and resources that can be called from ChatGPT, with responses rendered natively in ChatGPT.

Key Components

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

The core MCP server implementation that exposes tools and resources to ChatGPT.

Key features:

• Tool registration with OpenAI-specific metadata
• Resource registration that serves HTML content for iframe rendering
• Cross-linking between tools and resources via templateUri

OpenAI-specific metadata:

{
  "openai/outputTemplate": widget.templateUri,      // Links to resource
  "openai/toolInvocation/invoking": "Loading...",   // Loading state text
  "openai/toolInvocation/invoked": "Loaded",        // Completion state text
  "openai/widgetAccessible": false,                 // Widget visibility
  "openai/resultCanProduceWidget": true            // Enable widget rendering
}

Full configuration options: OpenAI Apps SDK MCP Documentation

2. Asset Configuration (next.config.ts)

Critical: Set assetPrefix to ensure /_next/ static assets are fetched from the correct origin:

const nextConfig: NextConfig = {
  assetPrefix: baseURL,  // Prevents 404s on /_next/ files in iframe
};

Without this, Next.js will attempt to load assets from the iframe’s URL, causing 404 errors.

3. CORS Middleware (middleware.ts)

Handles browser OPTIONS preflight requests required for cross-origin RSC (React Server Components) 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
}

4. SDK Bootstrap (app/layout.tsx)

The `` component patches browser APIs to work correctly within the ChatGPT iframe:

What it patches:

• history.pushState / history.replaceState - Prevents full-origin URLs in history
• window.fetch - Rewrites same-origin requests to use the correct base URL
• `` attribute observer - Prevents ChatGPT from modifying the root element

Required configuration:

  
    
  
  {children}

Note: suppressHydrationWarning is currently required because ChatGPT modifies the initial HTML before the Next.js app hydrates, causing hydration mismatches.

Getting Started

Installation

npm install
# or
pnpm install

Development