This repository is a minimal Typescript application demonstrating how to build an OpenAI Apps SDK compatible MCP server with widget rendering in ChatGPT.
This project shows how to integrate a Typescript express 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. It also includes MCP tools without UI widget.
- Node.js 22+ (see
.nvmrcfor exact version) - pnpm (install with
npm install -g pnpm) - Ngrok
This project uses Vite for React widget development with full HMR support, allowing you to see changes in real-time, directly within ChatGPT conversation, without restarting the server.
git clone <repository-url>
cd apps-sdk-template
pnpm installRun the development server from the root directory:
pnpm devThis command starts an express server on port 3000. This server packages:
- an MCP endpoint on
/mcp- aka as the ChatGPT App Backend - a React application on Vite HMR dev server - aka as the ChatGPT App Frontend
In a separate terminal, expose your local server using ngrok:
ngrok http 3000Copy the forwarding URL from ngrok output:
Forwarding https://3785c5ddc4b6.ngrok-free.app -> http://localhost:3000- Toggle Settings → Connectors → Advanced → Developer mode in the ChatGPT client
- Navigate to Settings → Connectors → Create
- Enter your ngrok URL with the
/mcppath (e.g.,https://3785c5ddc4b6.ngrok-free.app/mcp) - Click Create
- Start a new conversation in ChatGPT
- Select your newly created connector using + → Plus → Your connector
- Try prompting the model (e.g., "Show me pikachu details")
⚠️ Since the release of Chrome 142, local network access on Chromium-based browser from website is by default blocked by an access permission prompt. As the widgets are being displayed within iframes, the prompt never appear. Hence, you won't see the iframe appear in ChatGPT. In order to make it work, you need to go tochrome://flags/#local-network-access-checkand disable the Local Network Access Checks.
Now you can edit React components in web and see changes instantly:
- Make changes to any component
- Save the file
- The widget will automatically update in ChatGPT without refreshing or reconnecting
- The Express server and MCP server continue running without interruption
Note: When you modify widget components, changes will reflect immediately. If you modify MCP server code (in src/), you may need to reload your connector in Settings → Connectors → [Your connector] → Reload.
Important: For a widget to work properly, the name of the endpoint in your MCP server must match the file name of the corresponding React component in web/src/widgets/.
For example:
- If you create a widget endpoint named
pokemon-card, you must create a corresponding React component file atweb/src/widgets/pokemon-card.tsx - The endpoint name and the widget file name (without the
.tsxextension) must be identical
This naming convention allows the system to automatically map widget requests to their corresponding React components.
Use Alpic to deploy your OpenAI App to production.
- In ChatGPT, navigate to Settings → Connectors → Create and add your MCP server URL (e.g.,
https://your-app-name.alpic.live)
.
├── server/
│ ├── app.ts # OpenAI App extension class with widget API implementation
│ ├── server.ts # MCP server with tool/resource/prompt registration
│ └── index.ts # Express server definition
└── web/
└── src/
└── widgets/ # React widget components (must match endpoint names)