ChatGPT App Boilerplate

A production-ready template for building ChatGPT Apps with MCP (Model Context Protocol).

Features

• MCP server with JSON-RPC over HTTP (Vercel-compatible)
• React widget with ChatGPT integration hooks
• Local development server with hot reload
• Widget build pipeline (esbuild)
• Complete OpenAI Apps SDK documentation in /context

Quick Start

# 1. Clone this repository
git clone https://github.com/YOUR_USERNAME/your-app-name.git
cd your-app-name

# 2. Install dependencies
npm install

# 3. Build the widget
npm run build:widget

# 4. Start local development server
npm run dev:local

# 5. Expose with ngrok (in another terminal)
ngrok http 3000

# 6. Add connector in ChatGPT developer mode
# Use the ngrok URL as your MCP endpoint

Project Structure

├── app/                     # Next.js App Router
│   ├── api/mcp/route.ts    # MCP JSON-RPC endpoint (Vercel)
│   ├── layout.tsx          # Root layout
│   └── page.tsx            # Landing page
├── src/
│   ├── server/
│   │   ├── mcpServer.ts    # MCP server factory (local dev)
│   │   ├── dev.ts          # Local development server
│   │   └── tools/          # Your MCP tools
│   │       └── echo.ts     # Example tool
│   └── web/
│       ├── App.tsx         # Main widget component
│       ├── hooks/          # ChatGPT integration hooks
│       │   └── useOpenAi.ts
│       └── components/     # Your widget components
│           └── EchoCard.tsx
├── scripts/
│   └── build-widget.ts     # Builds widget to HTML
├── public/
│   └── widget.html         # Generated widget (after build)
├── context/                # OpenAI Apps SDK documentation
└── package.json

Development

Available Scripts

Script	Description
npm run dev	Start Next.js dev server (for Vercel preview)
npm run dev:local	Start local MCP dev server with hot reload
npm run build	Build Next.js app for production
npm run build:widget	Build React widget to public/widget.html

Adding Your Own Tools

1. Create a new tool in src/server/tools/:

// src/server/tools/myTool.ts
export const myTool = {
  name: 'my_tool',
  description: 'What your tool does',
  inputSchema: {
    type: 'object',
    properties: {
      input: { type: 'string', description: 'Input parameter' },
    },
    required: ['input'],
  },
};

export function myToolHandler(args: { input: string }) {
  return { result: args.input };
}

2. Register it in app/api/mcp/route.ts (for Vercel) and src/server/mcpServer.ts (for local dev)

Adding Widget Components

1. Create components in src/web/components/
2. Import and use them in src/web/App.tsx
3. Run npm run build:widget to rebuild

ChatGPT Integration Hooks

The useOpenAi.ts hooks provide:

• useToolOutput() - Get tool result data
• useToolInput() - Get tool input (if needed)
• useTheme() - Get light/dark theme preference
• useWidgetState() - Persistent widget state
• useCallTool() - Call MCP tools from widget
• useSendFollowUp() - Send follow-up messages to ChatGPT

Deployment

Vercel (Recommended)

1. Push to GitHub
2. Import to Vercel
3. Deploy

The app/api/mcp/route.ts is the production MCP endpoint.

Local Development with ngrok

1. npm run dev:local - Start local server
2. ngrok http 3000 - Expose to internet
3. Use ngrok URL in ChatGPT developer mode

Documentation

See /context/ folder for complete OpenAI Apps SDK documentation:

• Core Concepts: MCP server, UX principles, UI guidelines
• Building: Server setup, ChatGPT UI, authentication, state management
• Deployment: Deploy, connect, test, submit your app
• Learnings: Vercel-specific deployment insights

Customization

Replace these values throughout the codebase:

Find	Replace with
my-chatgpt-app	Your package name
My ChatGPT App	Your app title
A ChatGPT App built with MCP	Your description

License

MIT