ChatGPT Todo MCP demo (Apps SDK + React)

A minimal todo app for ChatGPT: an MCP server exposes tools and an interactive HTML UI, built with React + Vite and embedded as a single-file bundle. Includes a small dev OAuth layer so ChatGPT’s connector wizard can complete discovery.

Official reference: Apps SDK Quickstart.

Quick start

npm install
npm start          # builds widget (prestart) then runs server on port 8787 by default

• MCP endpoint: http://localhost:8787/mcp

• For ChatGPT: expose with HTTPS (e.g. ngrok) and create a connector pointing at https://<your-host>/mcp.

• If discovery URLs show the wrong scheme/host behind a tunnel, set:

  export PUBLIC_BASE_URL=https://your-ngrok-host.example

Project layout

Architecture and concepts

One-sentence model

ChatGPT acts as the MCP client. It speaks MCP over HTTPS to your Node server at /mcp. The server registers tools (what the model can call) and a resource (HTML for the widget). The widget runs in an iframe and talks to ChatGPT through a JSON-RPC bridge over postMessage. OAuth metadata on the same origin lets ChatGPT attach the connector; it is separate from MCP tool execution but required for onboarding.

Model Context Protocol (MCP)

MCP is a standard way for a host (ChatGPT) to discover and invoke tools and read resources on a server. This repo uses @modelcontextprotocol/sdk: an McpServer instance registers capabilities and is connected to a transport that maps MCP messages to HTTP (StreamableHTTPServerTransport).

Base MCP vs Apps SDK helpers

• @modelcontextprotocol/sdk: core McpServer, schemas, transport.

• @modelcontextprotocol/ext-apps: registerAppTool and registerAppResource normalize UI metadata (which HTML resource to show for a tool) and set the Apps HTML MIME type (RESOURCE_MIME_TYPE).

The widget is registered as a resource at a logical URI (e.g. ui://widget/todo.html). That URI does not need to be a public web URL; the host resolves it via MCP resources/read. Each tool’s _meta.ui.resourceUri points at the same URI so ChatGPT knows which UI surface belongs to which tool.

HTTP front door (server.js)

One Node http.Server handles several surfaces:

1. OAuth / discovery (oauth-dev.js) — well-known URLs and token endpoints ChatGPT expects.

2. CORS OPTIONS for /mcp.

3. Health GET /.

4. MCP POST / GET / DELETE on /mcp via the streamable HTTP transport.

5. 404 for unknown paths.

So you have one process, multiple logical HTTP APIs (OAuth HTTP + MCP HTTP).

Streamable HTTP and server lifetime

The transport is created per incoming MCP request, with sessionIdGenerator: undefined (stateless mode for this demo). A new McpServer is constructed per request and torn down when the response closes.

Important: in-memory todo state (todos in server.js) lives at module scope, not inside the McpServer instance. So state persists for the lifetime of the Node process even though each request gets a new MCP server object.

Tools and the UI contract

Tools (add_todo, complete_todo) declare input schemas (Zod) so the host validates arguments.

Tool results include:

• content: usual MCP content (e.g. text) for the model/conversation.

• structuredContent: JSON consumed by the widget—here { tasks: [...] }.

Using the same structuredContent shape for every mutation keeps the React UI in sync whether the call was triggered by the user in the widget or by the model in chat.

OAuth (oauth-dev.js)

ChatGPT’s connector flow fetches OAuth protected resource metadata and authorization server metadata (see Apps SDK auth). Without those routes, setup can fail with “Error fetching OAuth configuration.”

This repo ships a development-only authorization server (discovery, dynamic client registration, authorize redirect, PKCE token exchange) scoped to ChatGPT redirect URLs. Do not use it as-is for production—swap in Auth0, Stytch, Cognito, or similar, and verify tokens on MCP requests.

PUBLIC_BASE_URL forces the public https:// origin in metadata when proxies/ngrok do not set Host / X-Forwarded-Proto the way you need.

Widget bridge (widget/src/bridge.ts)

The built HTML runs inside ChatGPT’s iframe. It does not call your /mcp URL like a normal SPA; it uses the MCP Apps UI bridge:

1. ui/initialize then ui/notifications/initialized — handshake with the host.

2. tools/call — ask the host to run a named MCP tool with arguments (same tools the model uses).

3. ui/notifications/tool-result — when the model runs a tool, the host can push the result so the UI updates without a direct return path from tools/call.

So there are two update paths: RPC responses for UI-initiated calls, and notifications for model-initiated calls.

Why single-file HTML (Vite + vite-plugin-singlefile)

ChatGPT receives the widget as embedded HTML from the MCP resource read, not as “your site + separate JS chunks.” Relative chunk URLs would break in that embedding model. The build produces one dist/todo-widget.html with inlined JS/CSS; server.js reads it at startup into todoHtml.

React is a developer ergonomics layer; the deployable artifact is static HTML.

End-to-end flows

User in ChatGPT: message → model selects a tool → ChatGPT POSTs to your /mcp → tool runs → returns structuredContent.tasks → host shows/updates the widget.

User in the widget: React → tools/call via postMessage → host forwards to MCP → same handlers → RPC result updates state.

Connector setup: ChatGPT hits /.well-known/... on your origin → OAuth linking if required → subsequent MCP calls to /mcp may include Authorization: Bearer ... (enforcing that on every tool is a production step).

Natural next steps

Scripts

Default port: 8787 (PORT env overrides).