[V0_FILE]plaintext:file=".gitignore" isMerged="true" # See https://help.github.com/articles/ignoring-files/ for more about ignoring files. # dependencies /node_modules /.pnp .pnp.* .yarn/* !.yarn/patches !.yarn/plugins !.yarn/releases !.yarn/versions # testing /coverage # next.js /.next/ /out/ # production /build # misc .DS_Store *.pem # debug npm-debug.log* yarn-debug.log* yarn-error.log* .pnpm-debug.log* # env files (can opt-in for committing if needed) .env* # vercel .vercel # typescript *.tsbuildinfo next-env.d.ts [V0_FILE]markdown:file="README.md" isMerged="true" # ChatGPT Apps SDK Next.js Starter A minimal Next.js application demonstrating how to build an [OpenAI Apps SDK](https://developers.openai.com/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:** \`\`\`typescript { "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](https://developers.openai.com/apps-sdk/build/mcp-server) ### 2. Asset Configuration (`next.config.ts`) **Critical:** Set `assetPrefix` to ensure `/_next/` static assets are fetched from the correct origin: \`\`\`typescript 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: \`\`\`typescript 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:** \`\`\`tsx {children} \`\`\` **Note:** `suppressHydrationWarning` is currently required because ChatGPT modifies the initial HTML before the Next.js app hydrates, causing hydration mismatches. ## Getting Started ### Installation \`\`\`bash npm install # or pnpm install \`\`\` ### Development \`\`\`bash npm run dev # or pnpm dev \`\`\` Open [http://localhost:3000](http://localhost:3000) to see the app. ### Testing the MCP Server The MCP server is available at: \`\`\` http://localhost:3000/mcp \`\`\` ### Connecting from ChatGPT 1. [Deploy your app to Vercel](https://vercel.com/new/clone?demo-description=Ship%20an%20ChatGPT%20app%20on%20Vercel%20with%20Next.js%20and%20Model%20Context%20Protocol%20%28MCP%29.%0A&demo-image=%2F%2Fimages.ctfassets.net%2Fe5382hct74si%2F5TdbPy0tev8hh3rTOsdfMm%2F155b970ca5e75adb74206db26493efc7%2Fimage.png&demo-title=ChatGPT%20app%20with%20Next.js&demo-url=https%3A%2F%2Fchatgpt-apps-sdk-nextjs-starter.labs.vercel.dev%2F&from=templates&project-name=ChatGPT%20app%20with%20Next.js&project-names=Comma%20separated%20list%20of%20project%20names%2Cto%20match%20the%20root-directories&repository-name=chatgpt-app-with-next-js&repository-url=https%3A%2F%2Fgithub.com%2Fvercel-labs%2Fchatgpt-apps-sdk-nextjs-starter&root-directories=List%20of%20directory%20paths%20for%20the%20directories%20to%20clone%20into%20projects&skippable-integrations=1&teamSlug=vercel) 3. In ChatGPT, navigate to **Settings → [Connectors](https://chatgpt.com/#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](https://developers.openai.com/apps-sdk/deploy/connect-chatgpt) for setup instructions. ## Project Structure \`\`\` app/ ├── mcp/ │ └── route.ts # MCP server with tool/resource registration ├── layout.tsx # Root layout with SDK bootstrap ├── page.tsx # Homepage content └── globals.css # Global styles middleware.ts # CORS handling for RSC 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](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) ## Deployment This project is designed to work seamlessly with [Vercel](https://vercel.com) deployment. The `baseUrl.ts` configuration automatically detects Vercel environment variables and sets the correct asset URLs. [![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/vercel-labs/chatgpt-apps-sdk-nextjs-starter) 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 [V0_FILE]typescriptreact:file="app/custom-page/page.tsx" isMerged="true" "use client"; import Link from "next/link"; export default function HomePage() { return (

Welcome

This is a client-side rendered page demonstrating navigation in your ChatGPT app.

Go to the main page

); } [V0_FILE]css:file="app/globals.css" isMerged="true" @import "tailwindcss"; :root { --background: #ffffff; --foreground: #171717; } @theme inline { --color-background: var(--background); --color-foreground: var(--foreground); --font-sans: var(--font-geist-sans); --font-mono: var(--font-geist-mono); } @media (prefers-color-scheme: dark) { :root { --background: #0a0a0a; --foreground: #ededed; } } body { background: var(--background); color: var(--foreground); font-family: Arial, Helvetica, sans-serif; } [V0_FILE]typescript:file="app/hooks/types.ts" isMerged="true" /** * Source: https://github.com/openai/openai-apps-sdk-examples/tree/main/src */ export type OpenAIGlobals< ToolInput = UnknownObject, ToolOutput = UnknownObject, ToolResponseMetadata = UnknownObject, WidgetState = UnknownObject > = { // visuals theme: Theme; userAgent: UserAgent; locale: string; // layout maxHeight: number; displayMode: DisplayMode; safeArea: SafeArea; // state toolInput: ToolInput; toolOutput: ToolOutput | null; toolResponseMetadata: ToolResponseMetadata | null; widgetState: WidgetState | null; setWidgetState: (state: WidgetState) => Promise; }; type API = { callTool: CallTool; sendFollowUpMessage: (args: { prompt: string }) => Promise; openExternal(payload: { href: string }): void; // Layout controls requestDisplayMode: RequestDisplayMode; }; export type UnknownObject = Record; export type Theme = "light" | "dark"; export type SafeAreaInsets = { top: number; bottom: number; left: number; right: number; }; export type SafeArea = { insets: SafeAreaInsets; }; export type DeviceType = "mobile" | "tablet" | "desktop" | "unknown"; export type UserAgent = { device: { type: DeviceType }; capabilities: { hover: boolean; touch: boolean; }; }; /** Display mode */ export type DisplayMode = "pip" | "inline" | "fullscreen"; export type RequestDisplayMode = (args: { mode: DisplayMode }) => Promise<{ /** * The granted display mode. The host may reject the request. * For mobile, PiP is always coerced to fullscreen. */ mode: DisplayMode; }>; export type CallToolResponse = { result: string; }; /** Calling APIs */ export type CallTool = ( name: string, args: Record ) => Promise; /** Extra events */ export const SET_GLOBALS_EVENT_TYPE = "openai:set_globals"; export class SetGlobalsEvent extends CustomEvent<{ globals: Partial; }> { readonly type = SET_GLOBALS_EVENT_TYPE; } /** * Global oai object injected by the web sandbox for communicating with chatgpt host page. */ declare global { interface Window { openai: API & OpenAIGlobals; innerBaseUrl: string; } interface WindowEventMap { [SET_GLOBALS_EVENT_TYPE]: SetGlobalsEvent; } } [V0_FILE]typescript:file="app/hooks/use-display-mode.ts" isMerged="true" /** * Source: https://github.com/openai/openai-apps-sdk-examples/tree/main/src */ import { useOpenAIGlobal } from "./use-openai-global"; import type { DisplayMode } from "./types"; /** * Hook to get the current display mode of the widget. * * @returns The current display mode ("pip" | "inline" | "fullscreen") or null if not available * * @example * ```tsx * const displayMode = useDisplayMode(); * if (displayMode === "fullscreen") { * // Render full UI * } * ``` */ export function useDisplayMode(): DisplayMode | null { return useOpenAIGlobal("displayMode"); } [V0_FILE]typescript:file="app/hooks/use-is-chatgpt-app.ts" isMerged="true" import { useSyncExternalStore } from "react"; export function useIsChatGptApp(): boolean { return useSyncExternalStore( () => { // No subscription needed for this static value return () => {}; }, () => { // Client snapshot - check the actual window value if (typeof window === "undefined") return false; return (window as any).__isChatGptApp ?? false; }, () => { // Server snapshot - always false since window is undefined on server return false; } ); } [V0_FILE]typescript:file="app/hooks/use-max-height.ts" isMerged="true" /** * Source: https://github.com/openai/openai-apps-sdk-examples/tree/main/src */ import { useOpenAIGlobal } from "./use-openai-global"; /** * Hook to get the maximum height available for the widget. * Useful for responsive layouts that need to adapt to container constraints. * * @returns The maximum height in pixels, or null if not available * * @example * ```tsx * const maxHeight = useMaxHeight(); * const style = { maxHeight: maxHeight ?? "100vh", overflow: "auto" }; * ``` */ export function useMaxHeight(): number | null { return useOpenAIGlobal("maxHeight"); } [V0_FILE]typescript:file="app/hooks/use-openai-global.ts" isMerged="true" /** * Source: https://github.com/openai/openai-apps-sdk-examples/tree/main/src */ import { useSyncExternalStore } from "react"; import { SET_GLOBALS_EVENT_TYPE, SetGlobalsEvent, type OpenAIGlobals, } from "./types"; /** * Low-level hook to subscribe to a specific OpenAI global value. * Uses React's useSyncExternalStore for efficient reactivity. * * @param key - The key of the OpenAI global to subscribe to * @returns The current value of the global or null if not available * * @example * ```tsx * const theme = useOpenAIGlobal("theme"); // "light" | "dark" | null * ``` */ export function useOpenAIGlobal( key: K ): OpenAIGlobals[K] | null { return useSyncExternalStore( (onChange) => { if (typeof window === "undefined") { return () => {}; } const handleSetGlobal = (event: SetGlobalsEvent) => { const value = event.detail.globals[key]; if (value === undefined) { return; } onChange(); }; window.addEventListener(SET_GLOBALS_EVENT_TYPE, handleSetGlobal, { passive: true, }); return () => { window.removeEventListener(SET_GLOBALS_EVENT_TYPE, handleSetGlobal); }; }, () => (typeof window !== "undefined" ? window.openai?.[key] ?? null : null), () => null ); } [V0_FILE]typescript:file="app/hooks/use-request-display-mode.ts" isMerged="true" import { useCallback } from "react"; import type { DisplayMode } from "./types"; /** * Hook to request display mode changes from the ChatGPT host. * * @returns A function to request a specific display mode. The host may reject the request. * For mobile, PiP is always coerced to fullscreen. * * @example * ```tsx * const requestDisplayMode = useRequestDisplayMode(); * * const handleExpand = async () => { * const { mode } = await requestDisplayMode("fullscreen"); * console.log("Granted mode:", mode); * }; * ``` */ export function useRequestDisplayMode() { const requestDisplayMode = useCallback(async (mode: DisplayMode) => { if (typeof window !== "undefined" && window?.openai?.requestDisplayMode) { return await window.openai.requestDisplayMode({ mode }); } return { mode }; }, []); return requestDisplayMode; } [V0_FILE]typescript:file="app/hooks/use-widget-props.ts" isMerged="true" /** * Source: https://github.com/openai/openai-apps-sdk-examples/tree/main/src */ import { useOpenAIGlobal } from "./use-openai-global"; /** * Hook to get widget props (tool output) from ChatGPT. * * @param defaultState - Default value or function to compute it if tool output is not available * @returns The tool output props or the default fallback * * @example * ```tsx * const props = useWidgetProps({ userId: "123", name: "John" }); * ``` */ export function useWidgetProps>( defaultState?: T | (() => T) ): T { const toolOutput = useOpenAIGlobal("toolOutput") as T; const fallback = typeof defaultState === "function" ? (defaultState as () => T | null)() : defaultState ?? null; return toolOutput ?? fallback; } [V0_FILE]typescriptreact:file="app/layout.tsx" isMerged="true" import type { Metadata } from "next"; import { Geist, Geist_Mono } from "next/font/google"; import "./globals.css"; import { baseURL } from "@/baseUrl"; const geistSans = Geist({ variable: "--font-geist-sans", subsets: ["latin"], }); const geistMono = Geist_Mono({ variable: "--font-geist-mono", subsets: ["latin"], }); export const metadata: Metadata = { title: "Create Next App", description: "Generated by create next app", }; export default function RootLayout({ children, }: Readonly<{ children: React.ReactNode; }>) { return ( {children} ); } function NextChatSDKBootstrap({ baseUrl }: { baseUrl: string }) { return ( <> ); } [V0_FILE]typescript:file="baseUrl.ts" isMerged="true" export const baseURL = process.env.NODE_ENV == "development" ? "http://localhost:3000" : "https://" + (process.env.VERCEL_ENV === "production" ? process.env.VERCEL_PROJECT_PRODUCTION_URL : process.env.VERCEL_BRANCH_URL || process.env.VERCEL_URL); [V0_FILE]typescript:file="middleware.ts" isMerged="true" import { NextResponse } from "next/server"; import type { NextRequest } from "next/server"; export function middleware(request: NextRequest) { if (request.method === "OPTIONS") { const response = new NextResponse(null, { status: 204 }); response.headers.set("Access-Control-Allow-Origin", "*"); response.headers.set( "Access-Control-Allow-Methods", "GET,POST,PUT,DELETE,OPTIONS" ); response.headers.set("Access-Control-Allow-Headers", "*"); return response; } return NextResponse.next({ headers: { "Access-Control-Allow-Origin": "*", "Access-Control-Allow-Methods": "GET,POST,PUT,DELETE,OPTIONS", "Access-Control-Allow-Headers": "*", }, }); } export const config = { matcher: "/:path*", }; [V0_FILE]json:file="package.json" isMerged="true" { "name": "openai-apps-minimal-nextjs", "version": "0.1.0", "private": true, "scripts": { "dev": "next dev --turbopack", "build": "next build --turbopack", "start": "next start" }, "dependencies": { "@modelcontextprotocol/sdk": "^1.20.0", "mcp-handler": "^1.0.2", "next": "15.5.4", "react": "19.1.0", "react-dom": "19.1.0", "zod": "3.24.2", "class-variance-authority": "0.7.1", "clsx": "2.1.1", "lucide-react": "0.552.0", "tailwind-merge": "3.3.1", "tailwindcss-animate": "1.0.7" }, "devDependencies": { "@tailwindcss/postcss": "^4", "@types/node": "^20", "@types/react": "^19", "@types/react-dom": "^19", "tailwindcss": "^4", "typescript": "^5", "postcss": "8.5.6" }, "packageManager": "pnpm@10.14.0+sha512.ad27a79641b49c3e481a16a805baa71817a04bbe06a38d17e60e2eaee83f6a146c6a688125f5792e48dd5ba30e7da52a5cda4c3992b9ccf333f9ce223af84748" } [V0_FILE]javascript:file="postcss.config.mjs" isMerged="true" const config = { plugins: ["@tailwindcss/postcss"], }; export default config; [V0_FILE]json:file="tsconfig.json" isMerged="true" { "compilerOptions": { "target": "ES2017", "lib": ["dom", "dom.iterable", "esnext"], "allowJs": true, "skipLibCheck": true, "strict": true, "noEmit": true, "esModuleInterop": true, "module": "esnext", "moduleResolution": "bundler", "resolveJsonModule": true, "isolatedModules": true, "jsx": "preserve", "incremental": true, "plugins": [ { "name": "next" } ], "paths": { "@/*": ["./*"] } }, "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"], "exclude": ["node_modules"] } [V0_FILE]plaintext:file="app/favicon.ico" url="https://hebbkx1anhila5yf.public.blob.vercel-storage.com/git-blob/prj_9qHPjWv8HhHyWdTMSG1MVXA3Lvdu/OBeuqNFllvzcOxAfozDcmk/app/favicon.ico" isMerged="true" [V0_FILE]xml:file="public/file.svg" url="https://hebbkx1anhila5yf.public.blob.vercel-storage.com/git-blob/prj_9qHPjWv8HhHyWdTMSG1MVXA3Lvdu/DwTL2Rsyak235wm-yiG4dI/public/file.svg" isMerged="true" [V0_FILE]xml:file="public/globe.svg" url="https://hebbkx1anhila5yf.public.blob.vercel-storage.com/git-blob/prj_9qHPjWv8HhHyWdTMSG1MVXA3Lvdu/01AXmotpqQJ63fKHnt126X/public/globe.svg" isMerged="true" [V0_FILE]xml:file="public/next.svg" url="https://hebbkx1anhila5yf.public.blob.vercel-storage.com/git-blob/prj_9qHPjWv8HhHyWdTMSG1MVXA3Lvdu/XxhCJzp5tSVkhGy6Zfni9Q/public/next.svg" isMerged="true" [V0_FILE]xml:file="public/vercel.svg" url="https://hebbkx1anhila5yf.public.blob.vercel-storage.com/git-blob/prj_9qHPjWv8HhHyWdTMSG1MVXA3Lvdu/jJ0tDZIP24y6aCM8r4444t/public/vercel.svg" isMerged="true" [V0_FILE]xml:file="public/window.svg" url="https://hebbkx1anhila5yf.public.blob.vercel-storage.com/git-blob/prj_9qHPjWv8HhHyWdTMSG1MVXA3Lvdu/xajfHHqLIXXkEManLFuVFZ/public/window.svg" isMerged="true" [V0_FILE]typescript:file="app/hooks/index.ts" isEdit="true" isMerged="true" // OpenAI API hooks export { useRequestDisplayMode } from "./use-request-display-mode" // OpenAI state hooks export { useDisplayMode } from "./use-display-mode" export { useWidgetProps } from "./use-widget-props" export { useOpenAIGlobal } from "./use-openai-global" // Additional hooks export { useMaxHeight } from "./use-max-height" export { useIsChatGptApp } from "./use-is-chatgpt-app" // Types export type * from "./types" [V0_FILE]typescriptreact:file="app/page.tsx" isEdit="true" isQuickEdit="true" isMerged="true" "use client" import Image from "next/image" import Link from "next/link" import { useWidgetProps } from "./hooks/use-widget-props" import { useMaxHeight } from "./hooks/use-max-height" import { useDisplayMode } from "./hooks/use-display-mode" import { useRequestDisplayMode } from "./hooks/use-request-display-mode" import { useIsChatGptApp } from "./hooks/use-is-chatgpt-app" export default function Home() { const toolOutput = useWidgetProps<{ name?: string result?: { structuredContent?: { name?: string } } }>() const maxHeight = useMaxHeight() ?? undefined const displayMode = useDisplayMode() const requestDisplayMode = useRequestDisplayMode() const isChatGptApp = useIsChatGptApp() const name = toolOutput?.result?.structuredContent?.name || toolOutput?.name return (

{displayMode !== "fullscreen" && ( )}

{!isChatGptApp && (

This app relies on data from a ChatGPT session.

No{" "} window.openai {" "} property detected

)}

Welcome to the ChatGPT Apps SDK Next.js Starter
Name returned from tool call: {name ?? "..."}
MCP server path: /mcp

Visit another page Deploy on Vercel

) } [V0_FILE]typescript:file="next.config.ts" isEdit="true" isMerged="true" import type { NextConfig } from "next" import { baseURL } from "./baseUrl" const nextConfig: NextConfig = { assetPrefix: baseURL, eslint: { ignoreDuringBuilds: true, }, typescript: { ignoreBuildErrors: true, }, images: { unoptimized: true, }, } export default nextConfig [V0_FILE]typescript:file="app/mcp/route.ts" isEdit="true" isQuickEdit="true" import { baseURL } from "@/baseUrl" import { createMcpHandler } from "mcp-handler" const getAppsSdkCompatibleHtml = async (baseUrl: string, path: string) => { const result = await fetch(`${baseUrl}${path}`) return await result.text() } type ContentWidget = { id: string title: string templateUri: string invoking: string invoked: string html: string description: string widgetDomain: string } function widgetMeta(widget: ContentWidget) { return { "openai/outputTemplate": widget.templateUri, "openai/toolInvocation/invoking": widget.invoking, "openai/toolInvocation/invoked": widget.invoked, "openai/widgetAccessible": false, "openai/resultCanProduceWidget": true, } as const } const handler = createMcpHandler(async (server) => { const html = await getAppsSdkCompatibleHtml(baseURL, "/") const contentWidget: ContentWidget = { id: "show_content", title: "Show Content", templateUri: "ui://widget/content-template.html", invoking: "Loading homepage...", invoked: "Homepage loaded", html: html, description: "Displays the Next.js app homepage", widgetDomain: baseURL, } server.registerResource( "content-widget", contentWidget.templateUri, { title: contentWidget.title, description: contentWidget.description, mimeType: "text/html+skybridge", _meta: { "openai/widgetDescription": contentWidget.description, "openai/widgetPrefersBorder": true, }, }, async (uri) => ({ contents: [ { uri: uri.href, mimeType: "text/html+skybridge", text: `${contentWidget.html}`, _meta: { "openai/widgetDescription": contentWidget.description, "openai/widgetPrefersBorder": true, "openai/widgetDomain": contentWidget.widgetDomain, }, }, ], }), ) server.registerTool( contentWidget.id, { title: contentWidget.title, description: "Display the Next.js app homepage in a widget", inputSchema: {}, _meta: widgetMeta(contentWidget), }, async () => { return { content: [ { type: "text", text: "Showing the Next.js app homepage", }, ], structuredContent: { timestamp: new Date().toISOString(), }, _meta: widgetMeta(contentWidget), } }, ) }) export const GET = handler export const POST = handler

About

Tags

Share

More from mattc0llier

More Templates Like This

About

Tags

Share

About

Tags

Share

More from mattc0llier

More Templates Like This