ChatGPT App Development Guide

This Next.js application provides the ChatGPT integration surface for the Artifacts platform, combining MCP server and widget rendering in a unified deployment.

Key Architecture Files

• app/mcp/route.ts - MCP server route handler with dynamic authentication
• app/artifact/page.tsx - Widget rendering page (ChatGPT iframe)
• app/layout.tsx - NextChatSDKBootstrap browser API patches
• middleware.ts - CORS handling with Clerk integration
• baseUrl.ts - Environment-based URL resolution

Upstream SDK Reference (Optional)

ChatGPT Apps SDK Contains: Upstream platform guides for human developers (generic MCP patterns, widget tutorials, OAuth guides, window.openai API reference) Read when: Looking up platform API references not covered in our implementation docs below

Project Documentation

@.agents/docs/authentication.md - How we implement OAuth with Clerk @.agents/docs/mcp-server.md - Our tool/resource registration patterns

Widget Rendering Contains: Platform-specific patterns (loading state, display modes, safe area), constraints, widget↔tool integration Read when: Implementing widget pages, debugging iframe rendering, or handling ChatGPT display modes

Theming Contains: ChatGPT design system CSS variables, scoping pattern with data-artifact-container-chatgpt, theme synchronization Read when: Working on artifact styling, adding new components to widgets, or debugging theme/color inconsistencies