🧠 ChatGPT App Starter Kit

Minimal, production-grade MCP + SSE starter for ChatGPT Apps on Vercel.

A known-working reference implementation for deploying a ChatGPT App backed by a Model Context Protocol server using Streamable HTTP + SSE. One tool, one resource, zero ambiguity on headers, sessions, or CORS.

MCP apps fail in non-obvious ways. The transport layer has sharp edges that documentation describes but doesn't make visible — missing headers, session handshake ordering, runtime buffering, CORS preflight behavior. Debugging these issues can consume hours. This repository encodes the correct behavior so you can deploy, verify, and extend from a working baseline instead of reverse-engineering failures from spec documents.

✨ Why This Exists

MCP-backed ChatGPT Apps break constantly in production for reasons that have nothing to do with tool logic.

The failure modes are subtle and compound: a missing Accept header returns a generic 406. A GET before POST produces a cryptic session error. An Edge runtime silently buffers SSE into a single burst. CORS preflight fails before your handler ever executes. Each of these is documented somewhere across MCP, Vercel, and ChatGPT platform specs — but the interactions between them are not.

Reading three sets of documentation and synthesizing the correct configuration is slow, error-prone work. This starter kit exists because the fastest way to understand a protocol is to observe it working.

What this encodes:

• The exact header, session, and CORS behavior ChatGPT expects
• Accept header normalization that handles verification flows
• A deterministic tool that isolates transport issues from logic bugs
• Path mapping between local development and Vercel deployment

What this is not:

• Not an agent framework, background job system, or multi-tool suite
• Not a UI kit or full product frontend
• Not a guarantee of approval, uptime, or future platform compatibility

🎬 How It Works

  User                        ChatGPT                      MCP Server (Vercel)
   │                            │                             │
   │  "summarize this text"     │                             │
   │ ─────────────────────────► │                             │
   │                            │  POST /api (initialize)     │
   │                            │ ───────────────────────────►│
   │                            │  ◄── MCP-Session-Id ────────│
   │                            │                             │
   │                            │  GET /api (SSE attach)      │
   │                            │ ───────────────────────────►│
   │                            │  ◄── streaming events ──────│
   │                            │                             │
   │                            │  POST /api (tools/call)     │
   │                            │ ───────────────────────────►│
   │                            │  ◄── tool result ───────────│
   │                            │                             │
   │  ◄── formatted response ──│                             │

1. Deploy apps/mcp-server to Vercel
2. Paste https://YOUR-PROJECT.vercel.app/api into ChatGPT → Create App
3. ChatGPT initializes a session via POST /api, receives MCP-Session-Id
4. ChatGPT attaches SSE stream via GET /api, calls tools via POST /api
5. Results stream back through the established session

🏗 Architecture

┌──────────────────────────────────────────────────────┐
│                    ChatGPT Client                     │
│    initialize → attach stream → call tools/read UI    │
└───────────────────────┬──────────────────────────────┘
                        │  Streamable HTTP + SSE
                        ▼
┌──────────────────────────────────────────────────────┐
│              MCP Server  (apps/mcp-server)             │
│                                                        │
│   OPTIONS /api  ─────── CORS preflight (204)           │
│   POST    /api  ─────── JSON-RPC dispatch              │
│                          (initialize, tools/list,       │
│                           tools/call, resources/*)      │
│   GET     /api  ─────── SSE stream attach              │
│   GET     /api/health ─ liveness probe                 │
│                                                        │
│   ┌──────────────────┐  ┌──────────────────────────┐   │
│   │  echo_summarize   │  │  ui://starter/widget     │   │
│   │  (deterministic)  │  │  (static HTML resource)  │   │
│   └──────────────────┘  └──────────────────────────┘   │
└──────────────────────────────────────────────────────┘

The deployed surface is deliberately narrow — one transport, one tool, one resource. Small enough to audit in full before extending.

Path mapping: locally the app serves at / and /health. On Vercel, the same handlers mount at /api and /api/health via the api/ directory convention. This distinction matters when debugging.

⚙️ Core System

Request Flow

Session Lifecycle

POST /api { "method": "initialize" }
  → creates StreamableHTTPServerTransport
  → assigns MCP-Session-Id (UUID)
  → stores transport in memory
  → returns session ID in response header

POST /api { "method": "tools/call" }
  → resolves transport by MCP-Session-Id header
  → dispatches to registered tool handler
  → returns JSON-RPC result

GET /api
  → resolves transport by MCP-Session-Id header
  → opens persistent SSE connection for server-push events

session close
  → removes transport from in-memory map

Sessions live in-memory. No external session store. No persistence across redeploys.

Critical ordering: GET /api will always fail without a prior POST /api initialize. Stream attachment is not the session creation step.

Header Normalization

POST requests have their Accept header automatically normalized to include both application/json and text/event-stream. This exists because:

• ChatGPT verification flows send Accept: application/json for JSON-RPC
• The MCP SDK transport expects the client to accept both content types
• Without normalization, valid ChatGPT requests would be rejected

GET is strict: missing Accept: text/event-stream returns 406 Not Acceptable. No normalization.

CORS

Every response sets:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, Accept, MCP-Session-Id, Last-Event-ID

OPTIONS /api returns 204 with these headers. ChatGPT will always preflight before POST or GET — if this fails, nothing else works.

The Example Tool

echo_summarize accepts text and returns a deterministic summary:

{
  "preview": "first 240 chars...",
  "stats": { "charCount": 142, "wordCount": 28, "lineCount": 3 },
  "firstLine": "..."
}

No network calls. No side effects. No randomness. If this tool fails after deployment, the problem is transport — not logic. That's the point.

⚠️ Failure Modes / Gotchas

This is the most important section. These failures are real, common, and poorly documented elsewhere.

Headers & Protocol

Key distinction: POST /api does not require Accept: text/event-stream. GET /api does. Mixing these up is the most common header mistake.

Session Handling

Session ordering is strict: POST /api (initialize) → receive MCP-Session-Id → GET /api with that ID → POST /api with that ID for tool calls. Skipping the initialize step or losing the session ID breaks everything downstream.

Runtime & Streaming

Edge vs Serverless matters. Some Edge runtime and proxy combinations buffer SSE output instead of streaming it. If streaming looks broken, check your runtime configuration first.

CORS

ChatGPT will preflight OPTIONS /api before every POST or GET. If the preflight fails, the actual request never fires. You'll see a CORS error with no server-side log.

Deployment

Timeouts & Execution

• Keep tool execution deterministic and fast. Vercel Serverless functions have hard timeout limits.
• Long-running tools (network calls, heavy computation) will be killed mid-execution with no graceful shutdown.
• If you need long-running operations, design tools to return quickly and provide status via subsequent calls.

Proxy & CDN

• Intermediary proxies and CDNs may buffer streaming responses, causing SSE events to arrive all at once.
• Some proxies rewrite Transfer-Encoding or Content-Type headers, breaking SSE.
• Always test against the raw Vercel URL first. Add proxies only after confirming the baseline works.

🔧 Tech Stack

🚀 Quick Start

Prerequisites: Node.js 20+, a Vercel account.

1. Install

git clone https://github.com/shuddha2021/chatgpt-app-starter-kit.git
cd chatgpt-app-starter-kit
npm install

2. Build

npm run build

3. Deploy

Option A — Vercel CLI:

cd apps/mcp-server
npx vercel

Option B — Git integration:

1. Push to GitHub
2. Import in Vercel
3. Set Root Directory to apps/mcp-server
4. Leave Output Directory blank

After deploy: https://YOUR-PROJECT.vercel.app/

4. Connect to ChatGPT

1. ChatGPT → Create → Apps → Create app
2. Set MCP server URL to:

https://YOUR-PROJECT.vercel.app/api

Note: the path is /api, not /. This is the most common deployment mistake.

5. Verify

curl -sS https://YOUR-PROJECT.vercel.app/api/health
# → {"ok":true}

Optional SSE test (requires a valid session):

curl -i \
  -H 'Accept: text/event-stream' \
  -H 'MCP-Session-Id: YOUR_SESSION_ID' \
  https://YOUR-PROJECT.vercel.app/api

Local Development

cd apps/mcp-server
npm run dev
# → http://localhost:3000
# → http://localhost:3000/health

Locally, paths are / and /health (not /api).

📁 Project Structure

apps/
├─ mcp-server/                          # ← deploy this
│  ├─ api/
│  │  ├─ index.ts                       # Vercel entrypoint → /api
│  │  └─ health.ts                      # Liveness probe → /api/health
│  ├─ src/
│  │  ├─ http.ts                        # CORS, session map, Accept normalization
│  │  ├─ mcp.ts                         # Tool + resource registration
│  │  └─ local.ts                       # Local dev server (port 3000)
│  ├─ ui/starter/widget.html            # UI resource served via MCP
│  └─ vercel.json                       # Deployment config
├─ web/                                 # Optional local demo page (Vite)
docs/
├─ HOW_TO_CUSTOMIZE.md                  # Extension patterns for tools/resources
├─ SUBMISSION_CHECKLIST.md              # ChatGPT App submission steps
├─ APP_METADATA_TEMPLATE.md             # App listing metadata
├─ PRIVACY_POLICY_TEMPLATE.md           # Privacy policy starting point
├─ MONETIZATION.md                      # Payment integration references
└─ CHANGELOG.md                         # Version history

🧩 Extensibility

Adding Tools

All tools and resources are registered in apps/mcp-server/src/mcp.ts:

server.registerTool(
  'your_tool_name',
  {
    title: 'Your Tool',
    description: 'What it does (this is what the LLM sees).',
    inputSchema: {
      query: z.string().describe('The input parameter')
    }
  },
  async ({ query }): Promise<CallToolResult> => {
    return {
      content: [{ type: 'text', text: JSON.stringify(result) }]
    };
  }
);

Adding UI Resources

1. Add an HTML file under apps/mcp-server/ui/
2. Register with a ui:// URI in mcp.ts
3. Return file content in the resource read handler

Design Rules

• Validate all inputs with Zod. The schema is both the LLM-facing contract and your runtime guard.
• Keep tools deterministic until you have a reason not to. Non-determinism makes transport debugging impossible.
• Never hard-code secrets. Use environment variables.
• Avoid background loops or agent-like behavior. This is a request-response server, not an autonomous agent.
• Keep tool execution fast. Platform timeouts will kill long-running operations without warning.
• Verify transport before adding complexity. Deploy the baseline, confirm it works, then extend. Adding non-deterministic tools before confirming the transport layer works makes failures ambiguous.

🗺 Roadmap

This repository is intentionally minimal and will remain so. Planned additions:

• Additional example tools demonstrating common patterns
• CI/CD configuration examples
• Platform compatibility notes as MCP and ChatGPT evolve

📄 License

MIT — see LICENSE.

🗺 Roadmap

This is not growing into a framework. The intent is to stay minimal.

• Track MCP spec changes as the protocol evolves
• Add a multi-tool example without increasing deployment complexity
• Keep Vercel runtime compatibility verified

📄 License

MIT — see LICENSE.

Built by Shuddha Chowdhury