Basically, MCP Apps

So you know how MCP servers return text and JSON and stuff? Well, MCP Apps take that a step further: your tools can return full HTML widgets that render directly inside ChatGPT. Instead of the model dumping a wall of JSON at the user, they see an actual UI. Cards, grids, timelines -- whatever you want.

This is literally just meant to be a POC and nothing too serious. It's a CityJS London 2026 conference companion app: schedule, speakers, talk search -- all rendering as rich, themed UI inside ChatGPT.

Run it

./start.sh

That's it. One command. It installs deps, starts the server, opens a cloudflared tunnel, and hands you a URL to paste into ChatGPT. You need Node.js 18+ and cloudflared (brew install cloudflared on Mac).

You'll see something like this:

  ┌─────────────────────────────────────────────────────────┐
  │                                                         │
  │   YOUR MCP ENDPOINT:                                    │
  │                                                         │
  │   https://something-random.trycloudflare.com/mcp        │
  │                                                         │
  │   NOW GO ADD IT TO CHATGPT:                             │
  │                                                         │
  │   1. Open chatgpt.com                                   │
  │   2. Click the tools icon (wrench) in the input bar     │
  │   3. Click 'Add MCP Server'                             │
  │   4. Paste the URL above                                │
  │   5. Ask: 'What's the CityJS London schedule?'          │
  │                                                         │
  └─────────────────────────────────────────────────────────┘

Then ask ChatGPT things like "show me the speakers" or "tell me about Douglas Crockford's talk" or "find talks about AI" and watch the widgets appear.

Ok but how do I learn about MCP Apps

THE SOURCE CODE IS NOT SCARY! Go through it. There are basically 3 relevant files (and they're small!):

| File | What it does | |---|---| | server.js | The MCP server. Registers widgets, registers tools, binds them together. Start here. | | widgets/schedule.html | An HTML widget that renders a conference timeline. Read the <script> tag at the bottom. | | widgets/speakers.html | An HTML widget that renders a speaker card grid. Same pattern as above. | | widgets/speaker-detail.html | An HTML widget for a single speaker's full profile card. |

GO READ THEM. IT'S FUN, REALLY!

How it basically works

An MCP App is just an MCP server that also serves HTML widgets. When ChatGPT calls your tool, it renders your widget and pipes the tool's output data into it. Three things make this happen:

1. You write an HTML widget

A self-contained HTML file with inline CSS and JS. It receives data from ChatGPT and renders it. That's all it does. Look at widgets/speakers.html -- it's just a render(data) function and some CSS.

The widget picks up data from ChatGPT like this:

// ChatGPT puts tool output here when the widget loads
tryRender(window.openai?.toolOutput);

// Or fires this event slightly later
window.addEventListener("openai:set_globals", (e) => {
  tryRender(e.detail?.globals?.toolOutput);
});

It also picks up the theme (window.openai?.theme) so it matches ChatGPT's light/dark mode automatically.

2. You register the widget as a resource

In server.js, you tell the MCP host "hey, I have this widget":

server.registerResource(
  "schedule-widget",
  "ui://cityjs/schedule.html",
  { mimeType: "text/html;profile=mcp-app" },  // <-- this MIME type is the magic
  async () => ({
    contents: [{
      uri: "ui://cityjs/schedule.html",
      mimeType: "text/html;profile=mcp-app",
      text: scheduleWidgetHtml,  // the raw HTML string
    }],
  })
);

The MIME type text/html;profile=mcp-app is what turns a regular MCP server into an MCP App. It tells the host "this is a renderable widget, not just a file."

3. You bind a tool to the widget

When you register a tool, you tell the host which widget to render when the tool is called:

server.registerTool(
  "get_schedule",
  {
    title: "Get Schedule",
    description: "Get the CityJS London 2026 schedule...",
    inputSchema: { day: z.enum(["day1", "day2", "day3", "all"]).optional() },
    _meta: {
      ui: { resourceUri: SCHEDULE_URI },           // MCP spec way
      "openai/outputTemplate": SCHEDULE_URI,        // ChatGPT-specific way
    },
  },
  async ({ day }) => {
    return {
      structuredContent: { days },   // <-- your widget receives THIS
      content: [{ type: "text", text: JSON.stringify({ days }) }],  // fallback for non-UI hosts
    };
  }
);

structuredContent is the data your widget renders. content is a text fallback for hosts that don't do UI yet (like Claude). Always return both.

And that's basically it. Widget + resource + tool binding = MCP App.

The project

basically-mcp-apps/
  start.sh               <- run this. that's it.
  server.js              <- the MCP server. START READING HERE.
  package.json
  data/
    data.json            <- raw conference data (speakers, talks, bios)
    cityjs.js            <- enriches the raw data with rooms, types, etc.
  widgets/
    schedule.html        <- conference schedule timeline widget
    speakers.html        <- speaker grid widget
    speaker-detail.html  <- individual speaker profile card widget

Dependencies

• @modelcontextprotocol/sdk -- MCP server SDK
• zod -- input schema validation
• cloudflared -- tunnels your localhost to the internet so ChatGPT can reach it
• Node.js 18+

No React, no build step, no bundler, no framework. Just HTML files and a Node server.

Happy hacking!