Starter ChatGPT App

A minimal, production-capable ChatGPT app starter that proves the full loop:

• local MCP server
• local widget development
• tunnel-based ChatGPT testing
• Render deployment
• production connector setup

What is included

• backend/: Node.js + TypeScript MCP server over HTTP.
• frontend/: React + Vite widget frontend with fixture harness.
• render.yaml: split Render Blueprint (backend web service + frontend static site).
• scripts/dev.sh: optional helper to run backend and frontend together.
• scripts/validate-env.sh: optional environment validation script.

Prerequisites

• Node.js 20+
• npm 10+
• ngrok account and CLI
• ChatGPT account with developer mode enabled
• Render account

Local setup

1. Copy environment defaults.

cp .env.example backend/.env

2. Install dependencies.

cd backend && npm install
cd ../frontend && npm install

Run locally

Backend:

cd backend
npm run dev

Frontend:

cd frontend
npm run dev

Optional helper:

./scripts/dev.sh

Build checks:

cd backend && npm run build && npm run start
cd ../frontend && npm run build

Test in ChatGPT with ngrok

1. Start backend locally on port 3000.
2. Expose it with ngrok:

ngrok http 3000

3. Copy the public HTTPS URL from ngrok.
4. Connector URL to paste into ChatGPT:

https://<your-ngrok-domain>/mcp

This starter uses the /mcp path.

ChatGPT connector setup

1. In ChatGPT, enable developer mode.
2. Add a custom connector with MCP URL set to:
   • local tunnel: https://<ngrok-domain>/mcp
   • deployed backend: https://<backend-service>.onrender.com/mcp
3. Auth behavior:
   • default: no auth required
   • optional: set APP_AUTH_TOKEN and send x-app-token: <token> in connector headers

Deploy to Render

1. Push this repo to GitHub.
2. In Render, create a new Blueprint from the repo.
3. Render reads render.yaml and provisions:
   • starter-chatgpt-app-backend (Node web service)
   • starter-chatgpt-app-frontend (static site)
4. Set required secret values when prompted:
   • APP_AUTH_TOKEN (optional)
   • OPENAI_API_KEY (optional in this starter, required if you extend tools)
   • BASE_URL (optional)
5. Deploy and wait for healthy status on /health.

Connect deployed app in ChatGPT

Connector URL format:

https://starter-chatgpt-app-backend.onrender.com/mcp

Replace host with your actual backend Render URL.

If you enabled token auth, configure header x-app-token in the connector.

Environment variables

Variable	Local	Render	Required	Notes
NODE_ENV	yes	yes	yes	development locally, production on Render
HOST	yes	yes	yes	Use 0.0.0.0
PORT	yes	yes	yes	Render provides $PORT
WIDGET_BASE_URL	yes	optional	yes*	Use local Vite URL locally
WIDGET_HOST	optional	yes	yes*	Set from frontend service via fromService
APP_AUTH_TOKEN	optional	optional	no	Enables simple header-based auth
OPENAI_API_KEY	optional	optional	no	Add when tools call OpenAI APIs
BASE_URL	optional	optional	no	Public backend URL if needed by custom logic

* Set at least one of WIDGET_BASE_URL or WIDGET_HOST.

Customize the first tool

Edit backend/src/tools/search_items.ts:

• update tool names, descriptions, and schemas
• replace sample fixture filtering logic with your own data source
• keep structuredContent, content, and _meta in sync
• keep _meta["openai/outputTemplate"] aligned with widget URI

Customize the first widget

Edit frontend/src/App.tsx and frontend/src/components/ItemCard.tsx:

• start in fixture mode for fast iteration
• keep rendering logic compatible with tool structuredContent
• build frontend and verify frontend/dist output

Common issues

• 401 Unauthorized on /mcp: connector is missing x-app-token while APP_AUTH_TOKEN is set.
• Widget not updating: rebuild frontend and redeploy static site.
• Widget asset 404: verify WIDGET_BASE_URL (local) or WIDGET_HOST (Render wiring).
• Connector adds but tool fails: confirm MCP path is exactly /mcp.
• Render health check failing: open /health and confirm backend process is listening on 0.0.0.0:$PORT.

Golden prompts

Use these after connector setup (local tunnel and deployed app):

1. Search for sample items
2. Show me details for item-001
3. Open the example widget

License

MIT. See LICENSE.