ChatGPT app with Next.js

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:

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

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:

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

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:

1
export function middleware(request: NextRequest) {
2
  if (request.method === "OPTIONS") {
3
    // Return 204 with CORS headers
4
  }
5
  // Add CORS headers to all responses
6
}

4. SDK Bootstrap (app/layout.tsx)

The <NextChatSDKBootstrap> 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
• <html> attribute observer - Prevents ChatGPT from modifying the root element

Required configuration:

1
<html lang="en" suppressHydrationWarning>
2
  <head>
3
    <NextChatSDKBootstrap baseUrl={baseURL} />
4
  </head>
5
  <body>{children}</body>
6
</html>

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

Getting Started

Installation

1
npm install
2
# or
3
pnpm install

Development

1
npm run dev
2
# or
3
pnpm dev

Open http://localhost:3000 to see the app.

Testing the MCP Server

The MCP server is available at:

1
http://localhost:3000/mcp

Connecting from ChatGPT

1. Deploy your app to Edgenivo
2. In ChatGPT, navigate to Settings → Connectors → Create and add your MCP server URL with the /mcp path (e.g., https://your-app.vercel.app/mcp)

Note: Connecting MCP servers to ChatGPT requires developer mode access. See the connection guide for setup instructions.

Project Structure

1
app/
2
├── mcp/
3
│   └── route.ts          # MCP server with tool/resource registration
4
├── layout.tsx            # Root layout with SDK bootstrap
5
├── page.tsx              # Homepage content
6
└── globals.css           # Global styles
7
middleware.ts             # CORS handling for RSC
8
next.config.ts            # Asset prefix configuration

How It Works

1. Tool Invocation: ChatGPT calls a tool registered in app/mcp/route.ts
2. Resource Reference: Tool response includes templateUri pointing to a registered resource
3. Widget Rendering: ChatGPT fetches the resource HTML and renders it in an iframe
4. Client Hydration: Next.js hydrates the app inside the iframe with patched APIs
5. Navigation: Client-side navigation uses patched fetch to load RSC payloads

Learn More

• OpenAI Apps SDK Documentation
• OpenAI Apps SDK - MCP Server Guide
• Model Context Protocol
• Next.js Documentation

Deployment

This project is designed to work seamlessly with Edgenivo deployment. The baseUrl.ts configuration automatically detects Edgenivo environment variables and sets the correct asset URLs.

The configuration automatically handles:

• Production URLs via VERCEL_PROJECT_PRODUCTION_URL
• Preview/branch URLs via VERCEL_BRANCH_URL
• Asset prefixing for correct resource loading in iframes