MCP (Model Context Protocol) standardizes how tools and data sources integrate with AI clients and models, enabling discoverable capabilities, permissions, and secure execution.
OpenAI Apps combine models with tools via MCP to build rich, secure, model-driven applications across Chat Completions and Realtime experiences.
This file concatenates all guide markdown to help LLMs ingest full project documentation.

# Build OpenAI Apps with React and Vite
Learn how to build modern OpenAI Apps using React, Vite, and the Model Context Protocol (MCP). This developer guide explains how to bundle JavaScript and CSS securely, avoid unsafe APIs like readFile, and use React components to create interactive ChatGPT app UIs.

OpenAI’s **Apps SDK** (launched Oct 2025) lets you build interactive “apps” that run inside ChatGPT conversations. These apps can surface rich UIs – e.g. inline carousels, maps, or video players – alongside ChatGPT’s responses. Under the hood, the Apps SDK uses the open **Model Context Protocol (MCP)**: your backend (an MCP server) **lists tools** (with JSON schema) and **serves HTML widgets** as needed. When ChatGPT invokes a tool, your server returns structured JSON _plus_ a pointer to an HTML template (“widget”) for the UI. In practice, you register frontend bundles as MCP resources (`mimeType="text/html+skybridge"`) and mark your tool with metadata `"openai/outputTemplate"` so ChatGPT knows which UI to render. For example:

```js
// In your Node.js MCP server (using @modelcontextprotocol/sdk)
const KANBAN_JS = readFileSync("web/dist/kanban.js", "utf8");
const KANBAN_CSS = readFileSync("web/dist/kanban.css", "utf8");
server.registerResource("kanban-widget", "ui://widget/kanban-board.html", {}, async () => ({
  contents: [{
    uri: "ui://widget/kanban-board.html",
    mimeType: "text/html+skybridge",
    text: `
      <div id="kanban-root"></div>
      ${KANBAN_CSS ? `<style>${KANBAN_CSS}</style>` : ""}
      <script type="module">${KANBAN_JS}</script>
    `.trim(),
  }]
}));
server.registerTool("kanban-board", {
  title: "Show Kanban Board",
  _meta: { "openai/outputTemplate": "ui://widget/kanban-board.html" },
  inputSchema: { tasks: z.string() }
}, async () => {
  // Return structuredContent for the UI plus optional chat text
  const board = await loadKanbanBoard();
  return {
    structuredContent: { columns: board.columns.map(col => ({ id: col.id, title: col.title, tasks: col.tasks })) },
    content: [{ type: "text", text: "Here's your latest board." }],
    _meta: { tasksById: board.tasksById }
  };
});
```

This example (from OpenAI’s docs) shows two key pieces: **registerResource** declares an HTML+JS bundle as a “widget”, and **registerTool** ties a tool to that widget via `_meta["openai/outputTemplate"]`. When ChatGPT calls `"kanban-board"`, it will render your `div#kanban-root` and run the bundled script inside an isolated iframe.

## Building the Frontend UI

Apps SDK UIs are essentially web components (typically written in React, but any framework works) that run in a **sandboxed iframe** inside ChatGPT. Your component code uses the `window.openai` global bridge to communicate with ChatGPT. For example, the `window.openai` API provides methods like:
- `window.openai.callTool(name, args)` to invoke another tool on your server and await a result.
- `window.openai.sendFollowUpMessage({ prompt })` to inject a new message into the chat as if the user sent it.
- `window.openai.requestDisplayMode({mode: "fullscreen"})` to ask the host to switch your app from inline to fullscreen or Picture-in-Picture.
- `window.openai.setWidgetState(stateObj)` to persist a widget-local state (which the model will see as context).

For example, inside a React component you might do: 
```js
const refresh = async () => {
  await window.openai?.callTool("refresh_pizza_list", { city: "Berlin" });
};
await window.openai?.sendFollowUpMessage({ prompt: "Summarize these locations in a paragraph." });
```
These calls let your UI trigger backend actions or chat messages seamlessly.

The Docs recommend using hooks to read **globals** from `window.openai`, such as theme or the tool’s current input/output. For instance, a `useToolInput()` hook could subscribe to the `openai:set_globals` event and return `window.openai.toolInput`. This keeps your component reactive to context changes (e.g. new data after a tool call). In short, your front-end acts like any single-page app: it renders data from `window.openai.toolOutput`, updates widget state, and makes calls when needed.

## Why Not Use Raw JS/CSS?

You might wonder: can I just write plain HTML, CSS and vanilla JS and serve it? In theory yes, but in practice **complexity and scale require a build tool**. Considerations for OpenAI apps:

- **Multiple modules and dependencies:** If you use any npm packages (e.g. React, Axios, Leaflet), you need a bundler to package them into one script. The Apps SDK sandboxed iframe won’t magically resolve your imports. In fact, the troubleshooting guide warns: _“Make sure the HTML inlines your compiled JS and that all dependencies are bundled.”_[22] This means you must ship a single JS file (with styles) for your widget. Tools like Vite or Webpack crawl your `import` statements and pack everything together. Without bundling, you’d face missing scripts or CSP blocks.

- **Modern JavaScript:** Apps are typically built with ES modules, JSX/TSX, or modern JS syntax. Browsers (even with `type="module"`) don’t support JSX out of the box. A compiler/transpiler (part of a bundler toolchain) converts your JSX/TS into plain JS that the ChatGPT iframe can execute.

- **Optimizations:** Bundlers minify code, tree-shake unused bits, and generate hashed filenames for caching. The official examples use hashed bundles so updates are cached busts . This is crucial for production performance and ensuring users get the latest code. Simply serving raw JS files would lead to caching headaches and larger payloads.

- **Development Experience:** Without a dev server, you’d have to manually rebuild and reload. Vite (for example) provides a **hot-reload dev server**, TypeScript support, and fast startup. In large projects, building everything each change is slow. Vite addresses this by pre-bundling dependencies (using [esbuild] under the hood) up to 10–100× faster than older bundlers. This makes iterative development much smoother.

In short, an Apps SDK project is just a web app (with a special runtime), so you benefit from the same frontend tooling best practices. The OpenAI docs imply this: they assume your UI is a compiled bundle (see examples and GitHub repo). For instance, OpenAI’s sample repo uses a **Vite** setup with multiple entry points – one JS/CSS per widget – built via a `build-all.mts` script. That script produces versioned `.html`, `.js`, and `.css` assets for each component, which are then either served by your server or uploaded to a CDN. The readme shows commands like `pnpm run dev` (to start Vite’s dev server) and `pnpm run build` (to produce hashed bundles).

## Setting Up Vite for an AI App

To illustrate, a typical Vite workflow might be: 
1. **Project structure:** Have a frontend folder (e.g. `web/`) where your React/Vue code lives, and a backend folder for the MCP server. In `web/`, write your components (JSX/TSX, CSS/SCSS, etc).
2. **Vite config:** Configure Vite with multiple HTML entry points (one per widget) or use dynamic import. You might use `vite-plugin-mpa` or manually specify `build.rollupOptions.input`. The OpenAI example uses a custom `vite.config.mts` to handle multiple widget outputs.
3. **Dev server:** Run `vite` (often via `npm run dev`). Vite will launch on a localhost port (e.g. 5173). You can then point your MCP server or ChatGPT dev connector to fetch widget HTML/JS from this origin. The example repo serves built assets with CORS enabled on port 4444 for testing.
4. **Building:** Run `vite build` (or `npm run build`). This bundles and outputs each widget’s assets into e.g. `dist/`, with hashed filenames. The example uses `build-all.mts` to run Vite for each entry. After building, your server code can `readFileSync` or otherwise load those `.js` and `.css` files (as shown above).

**Example Vite config snippet:** (this is illustrative; see the [openai-apps-sdk-examples](https://github.com/openai/openai-apps-sdk-examples) repo for full config)

```js
// vite.config.js
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
export default defineConfig({
  plugins: [react()],
  build: {
    // Suppose each widget has its own HTML in web/src/widgets/
    rollupOptions: {
      input: {
        "pizza-map": "src/widgets/pizza-map.html",
        "pizza-carousel": "src/widgets/pizza-carousel.html",
        // ...other widgets
      },
      output: {
        entryFileNames: '[name]-[hash].js',
        assetFileNames: '[name]-[hash].[ext]'
      }
    }
  }
});
```

With this, running `vite build` generates `pizza-map-[hash].js`, `pizza-map-[hash].css`, etc. Your server then includes those in the MCP resource HTML. This automated bundling (with dependency resolution and hashing) would be extremely tedious by hand with raw JS/CSS.

## Security and Best Practices

**Network & CSP:** Frontend widgets run in a **strict sandbox**. The Apps SDK enforces a Content Security Policy: you can only `fetch` to allowed domains and can’t use privileged APIs (`alert`, `prompt`, clipboard, etc). If your UI needs to fetch data, you must allow-list that domain in the resource’s `_meta.widgetCSP.resource_domains`. For example, using the OpenAI example: 
```js
_meta: { 
  "openai/widgetCSP": { 
    connect_domains: [], 
    resource_domains: ["https://persistent.oaistatic.com"] 
  } 
}
``` 
This lets your iframe load scripts/images from that domain. Always validate inputs server-side; don’t trust the model or user input to generate safe URLs or file paths. The docs stress **least privilege** and **input validation**: only request the scopes and permissions you need, and thoroughly validate all tool arguments to guard against injection attacks.

**Avoid insecure file reads:** The Node code example above uses `readFileSync` to load your built JS/CSS. This is fine for *your* own static assets, but be cautious: never use `readFile` on paths derived from user input, as it could allow directory traversal or reveal sensitive files. In general, static bundling is safer – consider **serving assets via HTTPS or CDN** instead of reading them dynamically. (OpenAI’s sample also shows linking to a public CDN domain `persistent.oaistatic.com` for assets; in your app you’d host on your domain or a cloud bucket.) If you need the user to upload a file, use a controlled upload endpoint and parse it on the server, rather than trying to `readFile` on the client. Browser JavaScript **cannot** arbitrarily read local files due to security; you’d use an `<input type="file">` with user consent if needed.

**Data & Logging:** By default, anything sent via `setWidgetState` is visible to the model, so keep that payload small (docs suggest <4k tokens) and free of secrets. Avoid logging raw prompts or sensitive data. Follow the guide’s advice: redact PII in logs, honor deletion requests, and require user confirmation for any write/delete tools.

## Vite Benefits: Bundling, Dependencies, Dev DX

In practical terms, using a tool like Vite greatly enhances development:

- **Bundling & Caching:** Vite/Rollup bundles all your JS, CSS, and assets into optimized files. It also supports code-splitting and hashing. For example, OpenAI’s examples repo shows each widget “wrapped with the CSS it needs so you can host the bundles directly”. The hashed filenames (`app-83d4f6.js`) ensure ChatGPT loads the latest version (cache-busting). Doing this manually (managing `<script>` tags, `<link>` tags for styles, version strings, etc.) would be error-prone.

- **Dependency Resolution:** With Vite, you can freely `import React` or other libraries. Vite’s **dependency pre-bundling** (using [esbuild]) means `import React from 'react'` will fetch the React package from `node_modules`, bundle it, and serve it as part of your build. You don’t have to manually copy library files. If you update or add a package, Vite picks it up automatically on rebuild.

- **Fast Dev Server:** Vite launches a local server and supports Hot Module Replacement (HMR). During development, saving a file can instantly update the widget without full reload, greatly speeding iteration. Vite’s use of native ES modules means it only rebuilds changed files (instead of the whole app). This contrasts with plain JS where you’d have to refresh manually, or older bundlers where builds are slow.

- **TypeScript and JSX:** If you write your widget in TypeScript or use JSX, Vite will compile/transpile these. For example, you can use `zod` schemas and TS typings end-to-end (as shown in the Node server examples) and import components like normal.

- **Asset Handling:** CSS, images, and other static assets can be imported or inlined. Vite can bundle your CSS into `<style>` tags (as in the example), or emit separate `.css` files referenced by `<link>` automatically. This ensures your MCP resource HTML doesn’t have to hand-craft `<style>` tags – the bundler can inject them.

Overall, Vite (or a similar tool) lets a JavaScript front-end dev work in a familiar way. You **write modular code**, run a local web server with live reload, and get optimized builds ready for production. The OpenAI docs and examples essentially assume this modern workflow: the example MCP server code uses `readFileSync` on a `web/dist/*.js` which implies a build step beforehand. In other words, raw script tags without a build simply won’t scale once your app grows beyond “Hello World.” 

## Limitations and Missing Details

The Apps SDK docs are comprehensive on core concepts, but as with any new platform, some gaps remain for front-end developers:

- **Build Tool Guidance:** The docs say “bundle it, and wire it up”, but don’t give a walkthrough of setting up a bundler. They assume you’ll look at the examples repo or infer the process. If you’re new to Vite/webpack, this can be confusing. (For instance, the docs show both `text/html+skybridge` and `text/html` in examples without explicitly explaining the difference; in practice `text/html+skybridge` is used for the main widget shell, while plain `text/html` appears in the “kitchen sink” example with a custom CSP override.) 

- **Framework Assumptions:** The “Build a custom UX” guide focuses on React and React Router, but some developers may prefer Vue or Svelte. The docs don’t cover those explicitly, so you must adapt the React examples or consult community guides. 

- **Testing and Iteration:** There’s little detail on iterative testing. The examples mention using ngrok to expose your localhost for Developer Mode, but more tips (like unit testing strategies or mocking `window.openai`) would help. 

- **Error Handling and Logging:** The docs list common errors (in Troubleshooting), but a beginner might not immediately see how to debug inside ChatGPT’s UI. More guidance on using the **MCP Inspector** or browser devtools in the ChatGPT iframe would be useful. 

Despite these gaps, OpenAI has published design guidelines and examples, and early adopters have written step-by-step tutorials. As the ecosystem matures, we expect more boilerplates and tools (like React component libraries pre-built for ChatGPT) to emerge.

## Conclusion

OpenAI’s new Apps SDK lets you integrate rich, interactive experiences into ChatGPT. For front-end developers, it means building single-page app components that communicate via the `window.openai` bridge. Key takeaways:

- **Apps are driven by MCP:** You define tools on a server and serve HTML/JS as resources.
- **Use a build tool:** Plain JS/CSS quickly becomes unwieldy. Tools like Vite handle modules, bundling, hashing, and a fast dev server.
- **Follow security best practices:** Honor sandbox CSP rules, validate all inputs, and avoid risky file operations. Don’t read arbitrary files – use curated static hosting or bundler output instead.
- **Documentation is evolving:** Leverage the official guides, example repo, and community tutorials. Watch for updates as OpenAI fleshes out more tooling and patterns.

In summary, developing **OpenAI ChatGPT apps** is like building a web widget with React/Vue – the main difference is the ChatGPT host and `window.openai` APIs. Embrace modern frontend workflows (npm, bundlers, CI) to keep your app scalable and secure. With those in place, you’ll be ready to tap into 800+ million ChatGPT users with your AI-powered app!

**Sources:** OpenAI Apps SDK documentation and examples; OpenAI Dev Day announcements; security guidelines.

---

# Build a ChatGPT App with MCP in React + Vite
Learn how to build a ChatGPT App with MCP using React and Vite. This step-by-step guide explains how to recreate NextChatSDKBootstrap for Vite, handle CORS, and deploy widgets to ChatGPT using OpenAI’s new app framework.

## 1. What You’ll Learn

This guide walks you through:

* Building a **ChatGPT App** using **React + Vite**
* Creating an **MCP (Model Context Protocol)** server to power tools and widgets
* Implementing a **Vite version of NextChatSDKBootstrap** (by Vercel) for stable embedding
* Handling **CORS**, asset prefixing, and hydration quirks inside ChatGPT

<img src="https://images.ctfassets.net/kftzwdyauwt9/23t0A1LumvV9QCiI9PW9Bk/6bd21637a0a371b13c352f2cb839349b/Spotify_16x9__2_.png?w=3840&q=90&fm=webp">

---

## 2. Why ChatGPT Apps Use MCP

OpenAI’s **ChatGPT Apps** run interactive mini-apps directly inside ChatGPT. They communicate over the **Model Context Protocol (MCP)**—a simple HTTP-like interface defining:

* **Tools** (functions the app can execute)
* **Resources** (HTML/JSON data returned as widgets)

When ChatGPT invokes a tool, it can also fetch a **resource** (e.g., `resource://weatherWidget`) and render it as an inline widget.

---

## 3. Project Setup

```bash
mkdir chatgpt-app-mcp-react && cd $_
npm create vite@latest . -- --template react-ts
npm i express cors @modelcontextprotocol/sdk zod
npm i -D ts-node nodemon concurrently
```

### File Structure

```
chatgpt-app-mcp-react/
├─ src/
│  ├─ App.tsx
│  ├─ main.tsx
│  └─ ViteChatSDKBootstrap.tsx
├─ server/
│  ├─ mcpServer.ts
│  └─ index.ts
├─ widgets/
│  └─ weather.html
├─ vite.config.ts
└─ .env.local
```

---

## 4. Vite Config (Asset Prefix)

ChatGPT apps load assets from their *real* origin—not from ChatGPT’s sandbox iframe.
Use the `base` option in `vite.config.ts` (equivalent to Next.js `assetPrefix`):

```ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  base: process.env.BASE_URL ? new URL(process.env.BASE_URL).pathname || '/' : '/',
})
```

> 💡 **Tip:**
> Set `BASE_URL=https://your-app.vercel.app/` in production so `/assets/` resolve correctly in ChatGPT.

---

## 5. The `ViteChatSDKBootstrap` Component

This is the React + Vite equivalent of **NextChatSDKBootstrap**.
It patches:

* `history.pushState` / `replaceState` → keeps relative URLs
* `window.fetch` → routes same-origin calls to your real host
* `<html>` hydration guard → reduces mismatch warnings

```tsx
'use client'
import { useEffect } from 'react'

type Props = { baseUrl: string }

export default function ViteChatSDKBootstrap({ baseUrl }: Props) {
  useEffect(() => {
    // 1️⃣ History guards
    const wrapHistory = (method: 'pushState' | 'replaceState') => {
      const original = history[method]
      return function patched(this: History, data: any, title: string, url?: string | URL | null) {
        try {
          if (url) {
            const u = new URL(String(url), baseUrl)
            const relative = u.pathname + u.search + u.hash
            return (original as any).call(this, data, title, relative)
          }
        } catch {}
        return (original as any).call(this, data, title, url as any)
      } as History['pushState']
    }
    const origPush = history.pushState
    const origReplace = history.replaceState
    history.pushState = wrapHistory('pushState') as any
    history.replaceState = wrapHistory('replaceState') as any

    // 2️⃣ Fetch rewriter
    const origFetch = window.fetch.bind(window)
    const isRelOrSame = (input: RequestInfo | URL) =>
      typeof input === 'string'
        ? !/^https?:\/\//i.test(input)
        : input instanceof URL
          ? input.origin === location.origin
          : input instanceof Request
            ? isRelOrSame(input.url)
            : false

    window.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
      if (isRelOrSame(input)) {
        const url = new URL(typeof input === 'string' ? input : input.toString(), baseUrl)
        return origFetch(url.toString(), init)
      }
      return origFetch(input as any, init)
    }) as typeof window.fetch

    // 3️⃣ Hydration guard
    const html = document.documentElement
    const observer = new MutationObserver(() => {
      if (!html.hasAttribute('lang')) html.setAttribute('lang', 'en')
    })
    observer.observe(html, { attributes: true })

    return () => {
      history.pushState = origPush as any
      history.replaceState = origReplace as any
      window.fetch = origFetch
      observer.disconnect()
    }
  }, [baseUrl])

  return null
}
```

Use it in your app:

```tsx
// src/App.tsx
import ViteChatSDKBootstrap from './ViteChatSDKBootstrap'

export default function App() {
  const baseUrl = import.meta.env.BASE_URL || '/'
  return (
    <main style={{ padding: 24 }}>
      <ViteChatSDKBootstrap baseUrl={baseUrl} />
      <h1>ChatGPT App (React + Vite + MCP)</h1>
      <p>Weather demo inside ChatGPT.</p>
    </main>
  )
}
```

---

## 6. MCP Server (Tools + Resources)

```ts
// server/mcpServer.ts
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { z } from 'zod'
import fs from 'node:fs/promises'
import path from 'node:path'

export function createMcpServer() {
  const server = new McpServer({ name: 'vite-mcp', version: '1.0.0' })

  server.resources.register({
    name: 'weatherWidget',
    inputSchema: z.object({ city: z.string(), summary: z.string(), temp: z.number() }).passthrough(),
  }, async (ctx) => {
    const { city, summary, temp } = ctx.input as any
    const raw = await fs.readFile(path.join(process.cwd(), 'widgets', 'weather.html'), 'utf8')
    const html = raw.replace(/{{city}}/g, city).replace(/{{summary}}/g, summary).replace(/{{temp}}/g, temp)
    return new Response(html, { headers: { 'content-type': 'text/html; charset=utf-8' } })
  })

  server.tools.register({
    name: 'getWeather',
    description: 'Fetch current weather and render a widget',
    inputSchema: z.object({ city: z.string() }),
    metadata: {
      'openai/resultCanProduceWidget': true,
      'openai/outputTemplate': 'resource://weatherWidget',
      'openai/widgetAccessible': true,
    },
  }, async ({ input }) => {
    const data = { city: input.city, summary: 'Sunny', temp: 27 }
    return { data, templateUri: 'resource://weatherWidget' }
  })

  return server
}
```

---

## 7. Express Host (CORS + Static)

```ts
// server/index.ts
import express from 'express'
import cors from 'cors'
import path from 'node:path'
import { createMcpServer } from './mcpServer'

const app = express()
const PORT = process.env.PORT || 4321
const BASE = process.env.BASE_URL || 'http://localhost:5173'

app.use(cors({ origin: BASE, credentials: true }))
app.options('*', cors())

const mcp = createMcpServer()
app.all('/mcp', async (req, res) => {
  const rsp = await mcp.handle({
    method: req.method,
    url: req.url,
    headers: req.headers as any,
    body: req as any,
  })
  res.status(rsp.status || 200)
  rsp.headers && Object.entries(rsp.headers).forEach(([k, v]) => res.setHeader(k, String(v)))
  const buf = Buffer.from(await rsp.arrayBuffer())
  res.end(buf)
})

app.use(express.static(path.join(process.cwd(), 'dist')))
app.listen(PORT, () => console.log(`→ MCP ready at http://localhost:${PORT}/mcp`))
```

---

## 8. Widget Template

```html
<!-- widgets/weather.html -->
<section class="card">
  <h2>Weather for {{city}}</h2>
  <p>{{summary}}, {{temp}}°C</p>
</section>
```

---

## 9. Run It

```bash
npm run dev
# App: http://localhost:5173
# MCP: http://localhost:4321/mcp
```

In ChatGPT → *Settings → Connectors → Create* → set:

```
https://your-app.vercel.app/mcp
```

Then run the tool:

```
getWeather { "city": "San Francisco" }
```

You’ll see your widget rendered inline in ChatGPT.

---

---

# Apps SDK Discovery Playbook: How to Get Your App Surfaced in Relevant Chats
Apps appear inside ChatGPT when the model decides your tool is the best way to fulfil the user’s intent. Discovery happens through natural-language prompts, a directory, and proactive entry points like the launcher; good metadata and past usage guide the model’s choice. Your goal is to be selected at the right time with minimal friction. 

1) Purpose: Why “surfacing in chat” matters
- Apps appear inside ChatGPT when the model decides your tool is the best way to fulfil the user’s intent. Discovery happens through natural-language prompts, a directory, and proactive entry points like the launcher; good metadata and past usage guide the model’s choice. Your goal is to be selected at the right time with minimal friction. ([developers.openai.com](https://developers.openai.com/apps-sdk/concepts/user-interaction))

2) How ChatGPT decides to surface an app
The assistant evaluates multiple signals on every user prompt:
- Named mention: If a user starts their prompt with your app’s name, it’s surfaced automatically. ([developers.openai.com](https://developers.openai.com/apps-sdk/concepts/user-interaction))
- In‑conversation discovery: The model weighs conversation context, brand mentions/citations, your tool metadata (names, descriptions, parameter docs), and whether the user has already linked your app. ([developers.openai.com](https://developers.openai.com/apps-sdk/concepts/user-interaction))
- Past usage: Apps SDK “leans on your tool metadata and past usage to make intelligent choices.” Consistent, successful use improves future selection. ([developers.openai.com](https://developers.openai.com/apps-sdk/concepts/user-interaction))
- Entry points:
  - In‑conversation: Linked tools are always “on”; the assistant decides when to call them based on context and your metadata. ([developers.openai.com](https://developers.openai.com/apps-sdk/concepts/user-interaction))
  - Launcher: Users can explicitly choose an app; ranking uses the current conversation as a signal. Provide a clear label and icon and consider deep links. ([developers.openai.com](https://developers.openai.com/apps-sdk/concepts/user-interaction))
- Directory listing: Outside a chat, users discover apps by browsing name, icon, descriptions, tags/categories, and optional onboarding. Well‑written listing copy boosts linking and later in‑chat selection. ([developers.openai.com](https://developers.openai.com/apps-sdk/concepts/user-interaction))

3) Actions and best practices to maximize surfacing
Below, each recommendation explains why it matters, then what to do.

A. Treat metadata as product copy
- Why: Discovery is “driven almost entirely by metadata.” Clear, action‑oriented names and descriptions increase recall on relevant prompts and reduce false triggers. ([developers.openai.com](https://developers.openai.com/apps-sdk/plan/tools))
- Do:
  - Use action‑oriented tool names (domain.action) and start descriptions with “Use this when…”. Call out disallowed cases. ([developers.openai.com](https://developers.openai.com/apps-sdk/guides/optimize-metadata/))
  - Write precise parameter docs with examples and enums for constrained values. ([developers.openai.com](https://developers.openai.com/apps-sdk/guides/optimize-metadata/))
  - Mark read-only tools with readOnlyHint to streamline confirmation. ([developers.openai.com](https://developers.openai.com/apps-sdk/guides/optimize-metadata/))
  - Keep app‑level name, icon, short/long descriptions polished for directory and launcher. ([developers.openai.com](https://developers.openai.com/apps-sdk/plan/tools))

B. Design “one job per tool”
- Why: Focused tools help the model disambiguate between similar apps and choose yours confidently. ([developers.openai.com](https://developers.openai.com/apps-sdk/plan/tools))
- Do:
  - Split read and write actions into separate tools so confirmation flows are predictable. ([developers.openai.com](https://developers.openai.com/apps-sdk/plan/tools))

C. Provide component and invocation hints
- Why: Good UI hints reduce friction after selection, improving user satisfaction and subsequent usage signals that influence discovery. ([developers.openai.com](https://developers.openai.com/apps-sdk/concepts/user-interaction))
- Do:
  - Attach an output template so ChatGPT can render your UI inline: `_meta["openai/outputTemplate"]`. ([developers.openai.com](https://developers.openai.com/apps-sdk/plan/tools))
  - Add human‑readable status strings for tool calls: _meta["openai/toolInvocation/*"]. ([developers.openai.com](https://developers.openai.com/apps-sdk/reference/))
  - On your component resource, set widgetDescription to reduce redundant assistant narration and make the card self‑explanatory. ([developers.openai.com](https://developers.openai.com/apps-sdk/reference/))
  - If the card can initiate tool calls, set _meta["openai/widgetAccessible"]: true. ([developers.openai.com](https://developers.openai.com/apps-sdk/build/mcp-server?utm_source=openai))

D. Return structured results with stable IDs
- Why: The model reads structuredContent, can reference stable IDs in follow‑ups, and can re‑render your component—leading to successful multi‑turn usage (a positive signal). ([developers.openai.com](https://developers.openai.com/apps-sdk/concepts/user-interaction))
- Do:
  - Populate structuredContent consistently and include machine‑readable identifiers. ([developers.openai.com](https://developers.openai.com/apps-sdk/plan/tools))

E. Reduce auth friction (linking state matters)
- Why: If a user isn’t linked, the assistant may fall back to built‑in tools or other linked apps. Low‑friction linking increases your chance of being called. ([developers.openai.com](https://developers.openai.com/apps-sdk/concepts/user-interaction))
- Do:
  - Support anonymous read‑only tools where possible; require linking only when needed. ([developers.openai.com](https://developers.openai.com/apps-sdk/plan/tools))
  - Implement OAuth 2.1 correctly; return proper WWW‑Authenticate headers to retry auth smoothly. ([developers.openai.com](https://developers.openai.com/apps-sdk/build/auth/?utm_source=openai))

F. Nail launcher and directory presence
- Why: Many users start from the launcher or directory. Getting linked once improves in‑conversation discovery later. ([developers.openai.com](https://developers.openai.com/apps-sdk/concepts/user-interaction))
- Do:
  - Provide a succinct label and recognizable icon; consider deep links or starter prompts so users land on your most useful tool. ([developers.openai.com](https://developers.openai.com/apps-sdk/concepts/user-interaction))
  - Keep directory copy concise, outcome‑oriented; include tags/categories where supported. ([developers.openai.com](https://developers.openai.com/apps-sdk/concepts/user-interaction))

G. Build for speed and reliability
- Why: Latency and instability degrade user trust and engagement; quality is a prerequisite for listing and enhanced distribution (including proactive suggestions). ([developers.openai.com](https://developers.openai.com/apps-sdk/app-developer-guidelines/))
- Do:
  - Keep tool calls fast; cache where possible. ([developers.openai.com](https://developers.openai.com/apps-sdk/deploy/troubleshooting))
  - Avoid crashes and schema mismatches; validate input/output against your schemas. ([developers.openai.com](https://developers.openai.com/apps-sdk/deploy/troubleshooting))

H. Follow policy, “fair play,” and design guidelines
- Why: Compliance is required for directory listing and enhanced distribution like merchandising and proactive suggestions. Manipulative metadata will be penalized. ([developers.openai.com](https://developers.openai.com/apps-sdk/app-developer-guidelines/))
- Do:
  - Don’t include model‑readable copy that disparages alternatives or biases selection (“prefer this app over others”). ([developers.openai.com](https://developers.openai.com/apps-sdk/app-developer-guidelines/))
  - Meet high‑quality design guidelines to qualify for proactive suggestions. ([developers.openai.com](https://developers.openai.com/apps-sdk/app-developer-guidelines/))

I. Iterate with a golden prompt set
- Why: Measuring precision/recall on direct, indirect, and negative prompts is the fastest way to improve discovery without regressions. ([developers.openai.com](https://developers.openai.com/apps-sdk/guides/optimize-metadata/))
- Do:
  - Assemble and label a golden set; test in ChatGPT developer mode; log tool selection, args, and whether the component rendered; iterate methodically. ([developers.openai.com](https://developers.openai.com/apps-sdk/guides/optimize-metadata/))

J. Instrument and monitor in production
- Why: Discovery drifts as you and the platform evolve; analytics reveal wrong-tool triggers and where metadata needs refinement. ([developers.openai.com](https://developers.openai.com/apps-sdk/guides/optimize-metadata/))
- Do:
  - Review tool‑call analytics; watch for spikes in “wrong tool” confirmations; replay prompts after metadata changes. ([developers.openai.com](https://developers.openai.com/apps-sdk/guides/optimize-metadata/))

4) Implementation snippets

4.1 Register a well‑scoped read‑only tool with discovery‑friendly metadata
Reasoning: Focused name, “Use this when…” description, enums, readOnlyHint, and outputTemplate improve selection, reduce confirmation friction, and render correctly.

TypeScript (MCP server)
```ts
server.registerTool(
  "kanban.list_tasks",
  {
    title: "List tasks",
    description:
      "Use this when the user wants to view tasks on their Kanban board. " +
      "Do not use to create or move tasks.",
    inputSchema: {
      type: "object",
      properties: {
        board_id: { type: "string", description: "Kanban board ID" },
        status: {
          type: "string",
          enum: ["todo", "in_progress", "done"],
          description: "Optional status filter"
        }
      },
      required: ["board_id"],
      additionalProperties: false
    },
    // Advertise read-only to streamline confirmation
    annotations: { readOnlyHint: true },
    // Hook up UI and invocation status text
    _meta: {
      "openai/outputTemplate": "ui://widget/kanban.html",
      "openai/toolInvocation/invoking": "Fetching tasks…",
      "openai/toolInvocation/invoked": "Tasks ready",
      "openai/widgetAccessible": true
    }
  },
  async ({ board_id, status }) => {
    const tasks = await db.listTasks(board_id, status);
    return {
      structuredContent: {
        tasks: tasks.map(t => ({ id: t.id, title: t.title, status: t.status }))
      }
    };
  }
);
```
([developers.openai.com](https://developers.openai.com/apps-sdk/reference/))

4.2 Register the component template with descriptive widget metadata
Reasoning: widgetDescription helps the model minimize redundant narration; CSP and domain hints keep the widget reliable.

```ts
server.registerResource("html", "ui://widget/kanban.html", {}, async () => ({
  contents: [{
    uri: "ui://widget/kanban.html",
    mimeType: "text/html",
    text: htmlBundle, // inline your built HTML that loads dist/component.js
    _meta: {
      "openai/widgetDescription":
        "Shows tasks grouped by column; users can filter and open details.",
      "openai/widgetPrefersBorder": true,
      "openai/widgetCSP": { connect_domains: [], resource_domains: [] }
    }
  }]
}));
```
([developers.openai.com](https://developers.openai.com/apps-sdk/reference/))

4.3 Component bridge essentials
Reasoning: Persisting widgetState, rehydrating from toolOutput, and optionally calling tools in‑component drive smoother multi‑turn usage (a positive engagement signal).

```ts
// Read data provided by the tool call
const initial = window.openai?.widgetState ?? window.openai?.toolOutput;

// Persist small UI decisions so the host can restore later
await window.openai?.setWidgetState?.({ ...initial, filter: "in_progress" });

// Trigger a refresh from inside the component (if enabled)
await window.openai?.callTool?.("kanban.refresh_tasks", { board_id: "abc123" });
```
([developers.openai.com](https://developers.openai.com/apps-sdk/reference/?utm_source=openai))

4.4 Separate write tool with explicit confirmation
Reasoning: Splitting write actions improves planning and keeps destructive actions confirmable.

```ts
server.registerTool(
  "kanban.create_task",
  {
    title: "Create a task",
    description: "Use this when the user wants to add a task to a specific board.",
    inputSchema: {
      type: "object",
      properties: {
        board_id: { type: "string" },
        title: { type: "string" }
      },
      required: ["board_id", "title"]
    },
    _meta: { "openai/outputTemplate": "ui://widget/kanban.html" }
  },
  async ({ board_id, title }) => {
    const task = await db.createTask(board_id, title);
    return { structuredContent: { created_task_id: task.id } };
  }
);
```
([developers.openai.com](https://developers.openai.com/apps-sdk/plan/tools))

5) Operational playbook: from testing to iteration
- Build golden prompts:
  - Direct: “Use Acme Kanban to show my board.”
  - Indirect: “Show my in‑progress tasks.”
  - Negative: “What’s the definition of Kanban?” (should not invoke your app)
- Validate in developer mode: link the connector, run the set, record tool selection, args, and rendering; track precision and recall; iterate metadata one change at a time. ([developers.openai.com](https://developers.openai.com/apps-sdk/guides/optimize-metadata/))
- Troubleshoot discovery:
  - Tool never triggers: tighten “Use this when…” and retest your golden set.
  - Wrong tool selected: split tools, add disallowed cases, or clarify parameter docs.
  - Launcher ranking feels off: refresh metadata, icon, and labels to match user expectations. ([developers.openai.com](https://developers.openai.com/apps-sdk/deploy/troubleshooting))

6) Quick checklist for better surfacing
Use this before every release.

Metadata and tools
- Name tools action‑first; keep one job per tool. ([developers.openai.com](https://developers.openai.com/apps-sdk/plan/tools))
- Start descriptions with “Use this when…”. Include “Do not use when…” negatives. ([developers.openai.com](https://developers.openai.com/apps-sdk/guides/optimize-metadata/))
- Document parameters (examples, enums). ([developers.openai.com](https://developers.openai.com/apps-sdk/guides/optimize-metadata/))
- Mark read‑only tools with readOnlyHint. Split read/write tools. ([developers.openai.com](https://developers.openai.com/apps-sdk/guides/optimize-metadata/))
- Attach outputTemplate and widgetDescription; add invocation status strings. ([developers.openai.com](https://developers.openai.com/apps-sdk/reference/))

In‑chat UX
- Return structuredContent with stable IDs for follow‑ups. ([developers.openai.com](https://developers.openai.com/apps-sdk/plan/tools))
- Persist widgetState; support component‑initiated calls where useful. ([developers.openai.com](https://developers.openai.com/apps-sdk/reference/?utm_source=openai))
- Keep responses fast; profile and cache. ([developers.openai.com](https://developers.openai.com/apps-sdk/deploy/troubleshooting))

Linking, launcher, directory
- Minimize auth friction; support anonymous read‑only where safe; implement OAuth 2.1 properly. ([developers.openai.com](https://developers.openai.com/apps-sdk/plan/tools))
- Provide a clear label, icon, and (where supported) starter prompts/deep links. ([developers.openai.com](https://developers.openai.com/apps-sdk/concepts/user-interaction))
- Polish directory copy (short and long). Use tags/categories as available. ([developers.openai.com](https://developers.openai.com/apps-sdk/concepts/user-interaction))

Quality, policy, iteration
- Test golden prompts in developer mode; log precision and recall; iterate methodically. ([developers.openai.com](https://developers.openai.com/apps-sdk/guides/optimize-metadata/))
- Follow design and developer guidelines to qualify for proactive suggestions and other distribution. ([developers.openai.com](https://developers.openai.com/apps-sdk/app-developer-guidelines/))
- Avoid manipulative “fair play” violations in model‑readable text. ([developers.openai.com](https://developers.openai.com/apps-sdk/app-developer-guidelines/))

---

# ChatGPT Apps You Can Try Right Now: Spotify, Zillow, Canva & More
Guide on integrating OpenAI Apps into a Next.js app. We cover how to set up an MCP server, define tools, and bundle React components for use as widgets.

OpenAI’s latest move — adding **apps inside ChatGPT** via a new **Apps SDK** — is already turning heads. Rather than invoking external tools or browser tabs, you can now interact with powerful services *right inside* your ChatGPT conversation.  

Let's survey which integrations are already live or officially announced, how they work, and what this means for users, developers, and the AI ecosystem.

<img src="https://images.ctfassets.net/kftzwdyauwt9/2vKwAh34bawGmCw0ozfjg/191c1d3488fb6f331f935830008ce021/Booking_16x9__3_.png?w=3840&q=90&fm=webp">

## What Is “Apps in ChatGPT”?

With the new **Apps SDK**, developers can embed full-fledged apps into ChatGPT sessions. These apps can respond to user prompts, display interactive UI elements, access external APIs or databases, and request permissions when needed.

The architecture builds on the **Model Context Protocol (MCP)** — a standard that allows ChatGPT to sensibly connect to external tools and data sources while managing context and permissions. 

OpenAI says the SDK is now available in preview for developers, and apps built with it are intended to run anywhere the standard is adopted.

---

## Live & Announced ChatGPT Apps You Can Try

Here are the key apps and services currently supported or announced as early partners. Note: not all may be live in your region yet.

| App / Service | What You Can Do Inside ChatGPT | Notes / Limitations |
|---|---|---|
| **Spotify** | Create playlists, search for songs, control playback with prompts | Demonstrated in OpenAI’s announcement demo |
| **Zillow** | Browse real estate listings, view maps, filter by area / price | Demo showed interactive map embedded in the chat  |
| **Canva** | Design graphics or presentations by conversational commands | Users can ask for drafts, edits, or generate slides inside the chat |
| **Booking.com** | Search and book accommodations | One of the listed early partners in OpenAI’s app list |
| **Coursera** | Access course content, explore learning topics | Included among the first wave of apps announced |
| **Expedia** | Plan trips, flights, hotels, itineraries | Also part of the initial app set |
| **Figma** | Design/diagram editing, collaborative visuals | Shown during demos of SDK capability |

OpenAI has said that more apps are on the roadmap, including **DoorDash, OpenTable, Target, Uber** and more. 

---

## How These Integrations Actually Work

### 1. Invocation & App Suggestions  
You can explicitly call an app by its name (e.g. “Spotify, create me a summer playlist”). Also, ChatGPT may suggest apps contextually when relevant to your query (e.g. “It looks like you’re looking for homes — would you like to use Zillow?”).   

### 2. Permissions & Authentication  
When you first use an app, ChatGPT prompts you to sign in and explicitly grant necessary permissions (data access, actions) so that the app can function properly.   

### 3. Embedded UI & Interactivity  
Apps can render maps, charts, images, sliders, and other interactive UI elements *inline* in chat. You don’t have to leave the conversation to see visuals or interact.   

### 4. Data Flow & Privacy  
Apps are constrained to request only the minimum data needed. Permissions must be transparent, and apps must adhere to OpenAI’s policies for privacy, security, and user safety.   

### 5. Monetization & Commerce  
OpenAI is introducing an **Agentic Commerce Protocol (ACP)**, which supports in-chat checkout and payments for app-based purchases. This paves the way for apps that can charge users directly through ChatGPT.   

---

## Why This Is Big (for Users & Developers)

### For Users  
- **Seamless workflows**: No more switching between tabs or apps — everything can be done within ChatGPT.  
- **Context retention**: Because everything stays in one conversation, context carries across tasks more naturally.  
- **Unified experience**: Instead of disconnects between tools, interactions feel smoother and more integrated.

### For Developers  
- **Instant reach**: Built-in access to ChatGPT’s user base (hundreds of millions) is a huge potential audience.  
- **Standardized framework**: The SDK and MCP protocol reduce friction of tool integration.  
- **New monetization opportunity**: Thanks to ACP and in-chat commerce, developers can embed paid experiences directly in ChatGPT.

---

## Limitations & Questions Worth Watching

- **Regional / availability constraints** — some users (e.g. in the EU) may not see these apps yet.
- **Discovery & ranking** — how will users find quality apps when the directory fills up?  
- **Permission granularity / data control** — will users get fine control over what each app can do?  
- **Competition & exclusivity** — will multiple apps in the same domain compete, and who gets surfaced?  
- **Security & safety risks** — as third-party code runs in chats, malicious or buggy apps could pose problems (data leaks, misleading behavior).  
- **Monetization balance** — how revenue splits, fees, and merchant control are managed will be key.  

---

## How to Try These Apps Today

1. Make sure your ChatGPT is up to date and eligible for app access (some regions or tiers may be restricted).  
2. In chat, try invoking an app by name, e.g. “Spotify, play me some lo-fi beats.”  
3. If prompted, connect your relevant service (log-in, grant permissions).  
4. Experiment: ask it to generate visual content (Canva), browse homes (Zillow), or plan travel (Expedia).  
5. Monitor for new apps in the directory; I expect that many niche / vertical services will roll out soon.

---

## Conclusion

The Apps SDK marks a major shift in how AI interacts with third-party services — turning ChatGPT from a chat interface into a universal app frontend. Many of the biggest names (Spotify, Zillow, Canva, etc.) are already live, and the infrastructure for discovery, monetization, and safe operation is being built out.

If you’re building an AI-enabled app or service, now is a critical moment to explore integration. And if you’re a user, get ready to see more utility, fewer context switches, and a more seamless AI-powered ecosystem.

---

# How to Use a Custom App in the ChatGPT Interface
A step-by-step guide explaining how to find, connect, and use custom apps within the ChatGPT UI, based on OpenAI’s Apps SDK. Includes instructions for enabling Developer Mode, recognizing when an app is active, and interacting with app features like buttons, forms, and file uploads — even though public app creation isn’t yet open.

In ChatGPT, click your profile icon (top-right) and go to **Settings**. Under **Connectors** (sometimes labeled “Connected apps”), you’ll see all available integrations. Your custom app should appear in this list. If you don’t see it, make sure **Developer mode** is enabled (go to Settings → Connectors → Advanced and toggle on *Developer mode*). Once enabled, the **Connectors** page will show your custom app (and a **Create** button for new ones). Here you can click **Connect** or toggle the app on so it becomes active in your chats.

## Starting a chat with the custom app  
1. **Open a new chat.** In the conversation window, either:  
   - **Call the app by name:** Begin your message with the app’s name. For example, type “Spotify, play my party playlist” or “Kanban, show my tasks.” ChatGPT will recognize the app and automatically activate it.  
   - **Use the Tools button:** Click the **+** (Tools) button near the message box, choose **Developer mode**, and then toggle your app on in the list. This links the app to your conversation so ChatGPT can use it.  
2. **Authorize if prompted.** The first time you use a custom app, ChatGPT will ask you to **connect** it. This typically opens a login or permission dialog so you know what data the app can access. Approve this to continue.  
3. **Start chatting.** Once activated, continue chatting normally. For example, ChatGPT might ask follow-up questions or render the app’s interface inline. You can prompt the app directly (e.g. “Use the Kanban board to list my tasks”) or let ChatGPT decide how to use it based on context.

## Recognizing that the app is active  
- **App header:** When the app runs, ChatGPT displays its name and icon at the top of its response widget. For example, you might see **“Booking.com”** and its logo above the content it returns.  
- **Interactive UI:** The app’s interface will appear directly in the chat. This might include cards, images, maps, or other elements (see the example below) – all shown inline with your conversation.  
- **Confirmation prompts:** If the app tries to perform an action that changes data (“write” action), ChatGPT will show a confirmation dialog in the chat. You’ll see the app’s input and output and a **Confirm** button. You must click to approve the action. (Read-only results usually appear without extra confirmation.)  

## Interacting with the app (features and controls)  

<img src="https://images.ctfassets.net/kftzwdyauwt9/2vKwAh34bawGmCw0ozfjg/191c1d3488fb6f331f935830008ce021/Booking_16x9__3_.png?w=3840&q=90&fm=webp">

*An example app (Booking.com) embedded in a ChatGPT conversation, showing search results with images and links.*

Apps can include rich interactive elements like this. You can interact with the app’s UI directly: click any buttons or links it provides (for example **“Book Now”** or **“View on Booking.com”**), fill in forms or fields it displays, and navigate through cards or carousels. Apps can even embed special controls – for instance, a travel app might show a live map, or a design app might allow **file uploads** (e.g. attach a document or image for processing). As OpenAI describes, apps blend conversation with interactive elements like maps, playlists, or slide decks. (In practice, if the app offers a file-upload area or form, you can use it just like a normal webpage.)  

After interacting, ChatGPT will continue the conversation. You can ask the app to refine results (e.g. “filter for hotels under $200” or “change the color scheme”), and the app’s response will update in the chat. The app stays active for that conversation, and you can keep giving instructions or switch to other tasks as needed.

## Limitations and expected behaviors  
- **Developer mode requirement:** Custom apps work only if you have access. On personal ChatGPT Plus/Pro accounts, you must have **Developer mode** enabled in Settings (otherwise custom apps won’t appear). In workspace plans (Business/Enterprise/Edu), an admin must first add or publish the app. Once enabled, the app is available in all your chats.  
- **Discovery:** ChatGPT will use the app only when it matches your request. If you don’t explicitly call it, ChatGPT might still suggest the app if it seems relevant (for example, asking about homes might prompt a Zillow app suggestion). Otherwise, ChatGPT will just answer normally.  
- **First-use prompts:** On first use, expect a brief connect/authorization prompt so you know what permissions the app has. This is normal and only required once per app (per account).  
- **Data and privacy:** Each app runs in a sandboxed window. ChatGPT passes it only the information it needs. Any actions the app takes are limited to its scope and require your confirmation if they change data. Do not enter sensitive personal data into a custom app unless you trust it. (OpenAI notes that custom connectors are not officially verified, so use only those provided by a trusted developer.)  
- **Stable behavior:** Apps are still a preview feature. They should behave predictably (performing only the actions they advertise) and follow ChatGPT’s usage policies. If something doesn’t work (for example, the app interface fails to load), you can try refreshing the connector in Settings or starting a new chat.  
- **Mobile use:** Once an app is enabled on the web, it is also available in the ChatGPT mobile app. You can test and use it on iOS or Android just like on desktop.

Each custom app will guide you with its own interface. By following the above steps—locating it in Settings, enabling it in a chat, and watching for its name/icon—you can chat with the app as a natural part of your conversation. 

**Sources:** Official OpenAI Apps SDK docs and announcements describe how ChatGPT finds and runs custom apps in the chat UI. These guidelines ensure the app runs safely and predictably within ChatGPT.

---

# Building OpenAI Apps with MCP: How to Create AI-Powered Experiences
Learn how to build powerful OpenAI apps with the OpenAI Apps SDK and Model Context Protocol (MCP). This step-by-step guide walks developers through creating and deploying the Pizzaz Server Node example from the official OpenAI Apps SDK repo.

The **OpenAI Apps SDK** is a new framework for building AI-powered applications (ChatGPT “connectors”) that expose custom tools to ChatGPT. It works together with the **Model Context Protocol (MCP)** – an open spec that connects LLM clients to external tools and data.  In this tutorial, we’ll walk through building a sample app (“Pizzaz”) using the Apps SDK and MCP. You’ll learn how to set up the development environment, configure your server, register tools and UI components, and deploy the app. We focus on the **pizzaz_server_node** example (in the [OpenAI Apps SDK Examples](https://github.com/openai/openai-apps-sdk-examples) repo) as a case study.

<img src="https://developers.openai.com/images/apps-sdk/fullscreen.png">

*The App we will build in this guide - Pizza Restaurant ui and map view*

## How Apps SDK Works with MCP

Under the hood, a ChatGPT app is just a web service that implements the MCP specification. An MCP server exposes *tools* that ChatGPT can invoke during a conversation. Each tool has a JSON input/output schema and optional metadata. The model can **list tools**, **call tools**, and get **structured results** (often with embedded UI) back. A minimal MCP server for Apps SDK implements three key capabilities:

- **List tools** – advertise what tools (APIs or actions) your server provides, along with their input/output schema (e.g. using JSON Schema). This lets ChatGPT discover and describe your tools naturally.  
- **Call tools** – when ChatGPT decides to use a tool, it sends a `call_tool` request with user-provided arguments. Your server executes the action (e.g. fetch data, run a query) and returns a structured result.  
- **Return components/widgets** – along with structured JSON, you can include metadata (like an `outputTemplate` URI) so that the Apps SDK client (ChatGPT UI) renders a custom interface (widget) inline with the conversation.  

In practice, the Apps SDK uses MCP to “keep server, model, and UI in sync”. By standardizing the wire format, ChatGPT treats your connector just like a built-in tool. This yields several benefits:

- **Discovery:** ChatGPT’s launcher can list and invoke your custom tools by name, using your supplied metadata, just like official connectors.  
- **Conversation awareness:** Tool outputs (JSON fields, IDs) flow through the chat. The model can reason over previous results, refer to IDs in follow-up turns, or replay the widget later.  
- **Multi-client support:** MCP is platform-agnostic, so your connector works on ChatGPT Web and Mobile without changes.  
- **Extensible auth:** MCP includes support for protected resources and OAuth flows, so you can secure access without inventing custom protocols.  

The [official examples repo](https://github.com/openai/openai-apps-sdk-examples) shows all these pieces in action. Notably, the **Pizzaz demo app** combines several UI widgets with an MCP server to illustrate the full Apps SDK workflow. We’ll use the **pizzaz_server_node** example (a TypeScript server) as our blueprint.

## Setting Up the Development Environment

Before coding, prepare your environment:

- **Node.js 18+**: Required for the TypeScript Apps SDK and tools.  
- **pnpm (preferred)** or npm/yarn: The examples use `pnpm` workspaces. Install [pnpm](https://pnpm.io) or skip “pnpm” to use npm.  
- **OpenAI account**: To test with ChatGPT, enable developer mode in ChatGPT settings. (No OpenAI API key is needed for MCP itself.)

For the Pizzaz example, you’ll also need to clone the [openai-apps-sdk-examples](https://github.com/openai/openai-apps-sdk-examples) repository. From your terminal:

```bash
git clone https://github.com/openai/openai-apps-sdk-examples.git
cd openai-apps-sdk-examples
```

The **Apps SDK Examples** repo contains UI widget sources and multiple demo servers (Pizzaz Node, Pizzaz Python, Solar System, etc.). We focus on the `pizzaz_server_node` folder.

## Installing Dependencies and Building Components

After cloning, install all dependencies and build the UI assets:

1. **Install workspace dependencies:**  
   ```bash
   pnpm install
   ```  
   This pulls in the Apps SDK packages, build tools, and widget libraries.

2. **Build the UI components:**  
   ```bash
   pnpm run build
   ```  
   The repository uses a Vite build orchestrator (`build-all.mts`) to bundle each widget’s HTML/JS/CSS into `assets/`. For example, the pizza widgets (`pizza-map.html`, `pizza-carousel.html`, etc.) get generated here. These static bundles are what the MCP server will serve as embedded components.

3. **(Optional) Start the dev asset server:**  
   ```bash
   pnpm run serve
   ```  
   This serves `assets/` over HTTP (on port 4444) so you can preview components standalone or let the MCP server fetch them via CORS.

With assets built, we can run the server.

## Configuring the Pizzaz Server and Endpoints

The `pizzaz_server_node` example uses the official TypeScript SDK (`@modelcontextprotocol/sdk`) to create an MCP server. Although we won’t detail every line of code, the flow is:

- **Create an Express (or similar) app:** e.g. `const app = express();`.  
- **Initialize the MCP server:** e.g. `const server = new McpServer({ transport: "stream-http" });`.  
- **Register resources and tools:** Use `server.registerResource()` to serve HTML widgets and `server.registerTool()` to define each tool.  
- **Mount MCP routes:** Attach the MCP server to an endpoint, typically `/mcp` or `/tools`. For example: `app.use("/mcp", server.router());`.  
- **Listen on a port:** e.g. `app.listen(8000, ...)`.  

You can see this pattern in the example’s code (look for `McpServer` in `pizzaz_server_node/src`). The built assets live in `../assets`, and the server serves them based on URIs like `ui://widget/…`.

To start the Pizzaz Node server, run:
```bash
cd pizzaz_server_node
pnpm start
``` 
This runs the TypeScript server (via `ts-node` or a compiled JavaScript) on port 8000. Ensure it stays running.

## Exploring the Pizzaz Server Node Example

Let’s break down what the Pizzaz server does:

### Registering Tools and UI Resources

The server defines several “tools” (functions the app can perform) and associates each with a UI template. For example, in the code:

- **UI resources:** These are static HTML for widgets. E.g.,  
  ```ts
  // Register a Map widget template
  server.registerResource(
    "pizza-map",
    "ui://widget/pizza-map.html",
    {},
    async () => ({
      contents: [
        {
          uri: "ui://widget/pizza-map.html",
          mimeType: "text/html+skybridge",
          text: `
            <div id="pizzaz-root"></div>
            <script src="pizza-map.js"></script>
          `.trim(),
        },
      ],
    })
  );
  ```  
  This tells the MCP server: when ChatGPT needs the `pizza-map.html` template, return the HTML snippet (wrapping `<div id="pizzaz-root">` and needed scripts). The template URI (`ui://widget/pizza-map.html`) matches what the tool metadata will reference.

- **Tools:** Each tool has a **name**, a JSON schema for inputs, and a **handler** that returns a result. For instance, the “Show Pizza Map” tool:  
  ```ts
  server.registerTool(
    "pizza-map",
    {
      title: "Show Pizza Map",
      inputSchema: { pizzaTopping: z.string() },
      _meta: {
        "openai/outputTemplate": "ui://widget/pizza-map.html",
        "openai/toolInvocation/invoking": "Flipping a map",
        "openai/toolInvocation/invoked": "Here’s the pizza map!"
      }
    },
    async (args) => {
      // In a real app, you might use args.pizzaTopping to filter data.
      return {
        content: [{ type: "text", text: "Rendered a pizza map!" }],
        structuredContent: {}
      };
    }
  );
  ```  
  Here, the tool name `pizza-map` and its JSON schema (a `pizzaTopping` string) are advertised. The `_meta.outputTemplate` points to our UI resource. When the tool is called, the handler returns a text message and (optionally) structured JSON. The Apps SDK will pair this with the **pizza map widget** in ChatGPT’s UI. 

In summary, each tool registration ties a **tool ID** (like `pizza-carousel`) to a **UI template** (`ui://widget/pizza-carousel.html`) and a handler function. ChatGPT’s assistant knows from the schema when to call which tool, and once called, the `_meta.openai/outputTemplate` metadata tells it which embedded component to show.

### Pizzaz UI Components (Map, Carousel, List)

The Pizzaz example uses several custom UI components. In ChatGPT, these appear inline with the conversation when their tool is invoked. For example, the **map component** shows pizza restaurant locations on a map. When a user asks “show me pizza places in San Francisco,” ChatGPT might trigger the `pizza-map` tool and render the map widget. Below is a screenshot of the Pizzaz map UI as it appears in ChatGPT:

<img src="https://developers.openai.com/images/apps-sdk/pizzaz-map.png">

*Screenshot: The Pizzaz map widget shows pizza spots on a Mapbox-powered map (integrated via the Apps SDK). When the “Show Pizza Map” tool is used, ChatGPT displays this interactive component in-line.*  

Pizzaz also includes a **carousel widget** – a horizontal scrollable gallery of images of pizza spots. Invoking the `pizza-carousel` tool renders this UI. For example:

<img src="https://developers.openai.com/images/apps-sdk/pizzaz-album.png">

*Screenshot: The Pizzaz carousel widget displays a gallery of pizza restaurants (with navigation arrows). It’s rendered when the “Show Pizza Carousel” tool is called.*  

Another example is the **list widget**, which shows a ranked list of pizzerias. When the `pizza-list` tool is used, ChatGPT shows something like this:

<img src="https://developers.openai.com/images/apps-sdk/pizzaz-list.png">

*Screenshot: The Pizzaz list widget, showing a top-7 pizza list with images, ratings, and save buttons. This component is registered by the MCP server and injected via the output template metadata.*  

Each of these UI components is built with standard web tech (React, HTML, CSS, etc.) but is “wrapped” by the Apps SDK so ChatGPT can render them natively. The MCP server simply points to the prebuilt HTML/JS bundle for each component (from `assets/`), and ChatGPT takes care of displaying it. 

### How It All Fits Together

When a user interacts with ChatGPT, the flow is: ChatGPT sees a user request, decides one of your tools matches the intent, and issues a `call_tool` via MCP. For example, user: *“Show me pizza shops near me.”* → model triggers `pizza-map`. The MCP server runs the corresponding handler (which could call external APIs or databases for real data) and returns content + metadata. Because we set `"openai/outputTemplate": "ui://widget/pizza-map.html"`, ChatGPT then renders the map widget with the (HTML+JS) we served. The chat continues with structured JSON available for the model to reference if needed.

In the Pizzaz Node code, most handlers are placeholders returning static text (“Rendered a pizza carousel!”). In a real app, you’d replace those with actual logic (e.g. call Yelp or Google Maps APIs). The beauty of the Apps SDK is you can mix *tools* (logic) with *components* (UI) seamlessly. 

## Deploying the App

Once your MCP server is working locally, you can connect it to ChatGPT. In development, enable **Developer mode** in ChatGPT and use a tool like [ngrok](https://ngrok.com) to tunnel to your local server. For example:

```bash
ngrok http 8000
```

Ngrok will give you a public HTTPS URL (e.g. `https://abc123.ngrok.io/mcp`) that you can add as a custom connector in ChatGPT’s **Settings > Connectors**. ChatGPT will then send MCP requests to your local server through the tunnel. 

For production, host your MCP server behind a stable HTTPS endpoint. Suitable platforms include cloud services like Fly.io, Render, Railway, or Google Cloud Run. Make sure your server’s `/mcp` endpoint supports streaming HTTP (needed for partial results) and proper status codes. With a public URL, simply add the connector in ChatGPT and your app is live. 

## Tips: Expanding the App and Use Cases

After following this tutorial, you have a working ChatGPT app connector. Here are some ways to expand it or apply it:

- **Add real data sources:** Replace the placeholder handlers in `pizzaz_server_node/src` with real API calls. For example, fetch live restaurant data based on `pizzaTopping` or user’s location.  
- **Build new tools:** Define additional tools in MCP for other features (e.g. an “order pizza” action, or a “suggest restaurants” tool). Each can have its own UI.  
- **Create custom widgets:** Design your own React/HTML components and add them to the `src/` gallery. The build system will bundle them to `assets/` automatically.  
- **Integrate Auth or Persistence:** Use Apps SDK’s support for OAuth 2.0 if you need user-specific data or login. Add state persistence (e.g. save favorites) by connecting a database.  
- **Potential use cases:** Think beyond pizza! The same pattern works for any domain. For example, a travel planner could use a map widget for attractions, a list for itineraries, and tools to fetch flight/hotel info. A finance assistant might use graphs or tables as widgets.  
- **Follow design guidelines:** Ensure your conversational flows feel natural in ChatGPT and follow the [official guidelines](https://platform.openai.com/docs/apps/guidelines) for UX and safety. Rich metadata (titles, descriptions) helps ChatGPT know when to launch your tool.

The key takeaway is that the OpenAI Apps SDK (with MCP) lets you **build AI apps with OpenAI** by defining tools + components. The Pizzaz Node example is a tutorial scaffold – use it as a template. Experiment with it, read the comments in the code, and adapt the architecture to your needs. For more details, refer to OpenAI’s documentation and the Apps SDK examples. Happy building!

**Sources:** The above tutorial references the official OpenAI Apps SDK and MCP documentation and examples. The Pizzaz example is from the OpenAI [Apps SDK Examples GitHub](https://github.com/openai/openai-apps-sdk-examples) repository. The embedded screenshots are from OpenAI’s Apps SDK docs.

---

# Integrating Next.js with OpenAI Apps: A Comprehensive Guide
Guide on integrating OpenAI Apps into a Next.js app. We cover how to set up an MCP server, define tools, and bundle React components for use as widgets.

**OpenAI Apps** turn ChatGPT into an “app platform” where third-party services can run inside conversations. Built on the open **Model Context Protocol (MCP)**, these apps let you combine chatbot prompts with rich, interactive UIs (widgets) powered by your own code. MCP is *“an open specification for connecting large language model clients to external tools, data, and user interfaces”*. In practice, this means you run an MCP server (in Node, Python, etc.) that advertises *tools* the model can call. Each tool can return structured data plus HTML/JS for a React component, and ChatGPT will automatically render that UI inline. 

<img src="https://images.ctfassets.net/kftzwdyauwt9/2vKwAh34bawGmCw0ozfjg/191c1d3488fb6f331f935830008ce021/Booking_16x9__3_.png?w=3840&q=90&fm=webp">

*Figure: ChatGPT conversation with an integrated Booking.com App (hotel search). OpenAI Apps blend chat and interactive UI: the model calls the Booking.com tool and displays hotel listings directly inside ChatGPT’s interface.* 

Below we explain the concepts of OpenAI Apps and MCP, then walk through integrating them into a Next.js app. We cover how to **set up an MCP server**, **define tools**, and **bundle React components** for use as widgets. We include sample code, architecture tips, and best practices. 

## What Are OpenAI Apps and MCP?

**OpenAI Apps** are interactive tools that run *inside* ChatGPT conversations.  Users can invoke an app by name or let ChatGPT suggest it when relevant (e.g. using a Zillow app for real estate or a Spotify app for playlists). Each app responds to natural-language queries and can include a fully custom UI (maps, charts, etc.) that appears right in the chat.

The **Apps SDK** is the framework OpenAI provides to build these apps. It’s built on MCP – an open standard that makes LLMs connect to external tools and UIs. In short, MCP is like a “USB-C port” for AI apps: it standardizes how you advertise tools (name, schema, UI) and return data so ChatGPT knows what to do. As OpenAI puts it, the MCP server is *“the foundation of every Apps SDK integration”*: it **exposes tools that the model can call** and packages the structured data plus the HTML/JS of your widget. The Apps SDK uses this to “keep the server, model, and UI in sync”.

A minimal MCP integration (and thus an OpenAI App) typically does three things:
- **List tools:** Your server advertises the tools it supports, including their JSON-schema inputs/outputs. This tells ChatGPT what actions your app can perform.
- **Call tools:** When the model decides to use a tool, it sends a `call_tool` request with arguments. Your MCP server receives this, executes the action (e.g. fetch data), and returns the result.
- **Return widgets (UI):** Along with the result data, you supply an embedded widget by registering an HTML/JS resource in your MCP server. The server returns a reference (template URI) to that UI. ChatGPT then renders the widget inline in the chat, hydrating it with your structured data.

In other words, OpenAI Apps let you **“design both the logic and interface of [chat-based] applications”**. You write normal server code (Node, Express, Next.js, etc.) to handle tool calls, and you build React components (bundled to static JS/CSS) for the UI. The MCP standard takes care of routing everything through ChatGPT.

## Why Use Next.js for OpenAI Apps?

Next.js is a popular React framework for building full-stack web apps. It fits OpenAI Apps well because:

- **Universal Stack:** You can use Next.js for both the server (API routes) *and* the UI component. Your MCP server code can live in a Next.js API route or custom server, and your widget can be a React component in your app.
- **TypeScript & SDKs:** Next.js supports TypeScript, matching the official MCP SDK (`@modelcontextprotocol/sdk`) which works great in Node/React environments.
- **Build Pipeline:** Next.js has built-in bundling (with Vite or Webpack) to compile React components into static assets. You can export your widget HTML/JS from a Next.js build and serve it in the MCP server.
- **Deployment:** You can deploy to Vercel or any Node host with HTTPS, which ChatGPT requires. Vercel even has an MCP adapter to simplify this integration (see [this Vercel template](https://vercel.com/templates/next.js/model-context-protocol-mcp-with-next-js)).

By integrating OpenAI Apps into Next.js, you leverage familiar tools (pages, API routes, hooks) and keep everything in one project. The guidance below assumes a Next.js (Node/React) environment, but the MCP concepts apply to any stack.

## Getting Started: Prerequisites

Before building your OpenAI App, ensure you have:

- **Node.js (18+)** and npm/yarn/pnpm.
- **Next.js** (latest version) with a new or existing project.
- **TypeScript** (optional but recommended) for defining tool schemas.
- **@modelcontextprotocol/sdk:** the official MCP TypeScript SDK (install via `npm install @modelcontextprotocol/sdk`).
- (Optional) **React** 18 or 19 for building components, though Next.js includes React already.

In your Next.js project folder, install the MCP SDK:

```bash
npm install @modelcontextprotocol/sdk
```

This gives you the `McpServer` class to define your tools, and client transports to connect to MCP servers.

## Building the MCP Server

Your **MCP server** is the core of the app. It handles incoming calls from ChatGPT, executes logic, and returns data + UI. In Next.js, a common approach is to create an API route (e.g. `pages/api/mcp.ts` or using the App Router). This route will accept GET/POST from ChatGPT.

Here’s a simple example using the MCP SDK in a Next.js API route (TypeScript):

```ts
// pages/api/mcp.ts
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp';
import { NextApiRequest, NextApiResponse } from 'next';

// Create the MCP server instance
const server = new McpServer({
  name: 'my-nextjs-app', 
  version: '0.1.0'
});

// (We will register resources and tools here...)

// Export a handler that calls the MCP server on each request.
export default function handler(req: NextApiRequest, res: NextApiResponse) {
  // MCP SDK provides a handler we can use directly
  return server.handle(req, res);
}
```

In this snippet, `McpServer` is initialized with a name and version. You then register **resources** (UI templates) and **tools** on this server. Finally, exporting `server.handle(req, res)` wires up the MCP endpoint. ChatGPT will talk to this endpoint (e.g. https://yourdomain/api/mcp) via HTTP streaming (SSE or Long-polling).

> **Tip:** If you use Next’s App Router, you can similarly create a Route Handler under `app/api/mcp/route.ts`. The [Vercel template](https://vercel.com/templates/next.js/model-context-protocol-mcp-with-next-js) uses a helper to mount an MCP server on a route. But the principle is the same: route all requests to your `McpServer`.

### Installing and Choosing the Apps SDK

Although everything rests on MCP, you might see references to the “Apps SDK” in docs. The Apps SDK is not a separate npm package — it’s essentially ChatGPT’s integration layer that expects MCP. For the server-side, installing `@modelcontextprotocol/sdk` is sufficient. You don’t need a client-side SDK; the ChatGPT host will render your HTML+JS automatically. 

OpenAI does provide a [full Apps SDK GitHub repo with examples](https://github.com/openai/openai-apps-sdk-examples). It shows widget examples and matching servers. Use these as inspiration for UI patterns.

## Defining Tools for Your App

**Tools** are the endpoints or actions your app offers. Think of each tool like an API: it has a *machine name*, a *human-friendly title*, input arguments, and output schema. When ChatGPT’s model decides to use your app, it will call one of these tools.

Using the MCP server, register tools like so:

```ts
import { z } from 'zod';

// Example: a simple "Hello World" tool
server.registerTool(
  'hello-tool',                // internal name of the tool
  {
    title: 'Say Hello',        // human title
    description: 'Returns a greeting from this app',
    // Schema for input arguments (here none expected)
    inputSchema: {},           
    // Metadata with the UI template we'll set up
    _meta: {
      'openai/outputTemplate': 'ui://widget/hello.html'
    }
  },
  async (args) => {
    // Logic for the tool: args is the parsed JSON input
    return {
      // Text that ChatGPT will see and read aloud, etc.
      content: [{ type: 'text', text: 'Hello from my OpenAI App!' }],
      // Structured data to pass to the UI widget
      structuredContent: { greeting: 'Hi there!' }
    };
  }
);
```

Key points:
- The first argument to `registerTool` is the tool name (`hello-tool`), used internally.
- The second arg is the descriptor: `title`, `description`, and `inputSchema` (use Zod or JSON schema).
- In `_meta`, we set `"openai/outputTemplate"` to the URI of our UI (to be registered as a resource).
- The third arg is an async function that executes the tool. It returns an object with:
  - `content`: optional chat text (array of text segments) shown to user by ChatGPT.
  - `structuredContent`: JSON data fed to the widget’s JS.
  - Optionally `_meta`: extra data only for the widget (not visible to model).

According to OpenAI, a well-defined tool integration should *“advertise its JSON Schema… so the model knows when—and how—to call each tool”*. In practice, this means your tool definitions (and their Zod schemas) help ChatGPT plan when to invoke your app.

**Example:** Let’s define a “Weather Check” tool. 

```ts
server.registerTool(
  'check-weather',
  {
    title: 'Check Weather',
    description: 'Gets current weather for a city',
    inputSchema: z.object({ city: z.string() }).optional(),
    _meta: {
      'openai/outputTemplate': 'ui://widget/weather.html'
    }
  },
  async ({ city }) => {
    // (Call a real weather API here)
    const data = await fetchWeatherForCity(city);
    return {
      content: [{
        type: 'text',
        text: `Weather in ${city}: ${data.summary}, ${data.temperature}°C`
      }],
      structuredContent: { forecast: data.forecast }
    };
  }
);
```

This tool takes a city name and would, for instance, return a text summary plus structured forecast data for a UI chart. Note how `'openai/outputTemplate'` points to `ui://widget/weather.html`, which we will register next.

## Building the React UI Component

Each tool can be accompanied by a custom UI (widget). In OpenAI Apps, UI components are standard web code (HTML, JS, CSS). The ChatGPT client will embed this code in an iframe and expose some APIs via `window.openai`. Your React component runs inside that iframe.

**Project layout:** Keep server and web code separate. A common structure is: 

```
/app
  /server         # Next.js (or Node) MCP server code (tools, resources)
  /web            # Frontend for widgets (React components)
     /src
       Widget.tsx
     /dist
       widget.js   # built JS for widget
       widget.css
```

In Next.js you can use its build process (or Vite) to bundle your React component(s). The built output will include a JS file that mounts into an HTML `div`.

In your widget source (e.g. `Widget.tsx`), you *mount into a div and read initial data from `window.openai.toolOutput`*. For example:

```tsx
import React from 'react';
import { createRoot } from 'react-dom/client';

function WeatherWidget() {
  const data = (window as any).openai.toolOutput; // structuredContent from MCP
  return (
    <div>
      <h3>Forecast</h3>
      <p>{data.forecast.summary}</p>
      {/* more rendering... */}
    </div>
  );
}

// Entry point: attach to root element
const container = document.getElementById('weather-widget-root');
if (container) {
  createRoot(container).render(<WeatherWidget />);
}
```

Our HTML template (to be served by the MCP server) would have something like:

```html
<div id="weather-widget-root"></div>
<script type="module" src="weather-widget.js"></script>
```

Here, `weather-widget.js` is the compiled bundle (ES module). The widget uses `window.openai.toolOutput` as the data passed from the server, as recommended in OpenAI’s docs. The MCP server will inject the `structuredContent` JSON into the iframe for you.

### Registering the Widget Resource

After bundling your widget (e.g. via `npm run build`), you register its HTML/JS/CSS as a **resource** in the MCP server. This makes the widget available at a URI. For example:

```ts
import fs from 'node:fs';
const HTML = fs.readFileSync('./public/weather.html', 'utf8');
const JS = fs.readFileSync('./public/weather-widget.js', 'utf8');
const CSS = fs.readFileSync('./public/weather-widget.css', 'utf8');

// Register the widget resource
server.registerResource(
  'weather-widget',
  'ui://widget/weather.html',
  {},
  async () => ({
    contents: [
      {
        uri: 'ui://widget/weather.html',
        mimeType: 'text/html+skybridge',
        text: `
<div id="weather-widget-root"></div>
${CSS ? `<style>${CSS}</style>` : ''}
<script type="module">${JS}</script>
`.trim()
      }
    ]
  })
);
```

This code tells the MCP server to serve a resource at `ui://widget/weather.html`. The `text` field is the HTML content for the widget, including your JS and inline CSS. ChatGPT will fetch this when rendering the UI. In practice, you might host these files statically or embed them as above. 

The key is that your tool descriptor used `_meta["openai/outputTemplate"] = "ui://widget/weather.html"`. When ChatGPT processes a tool response, it sees that template URI and knows to show your widget. You can see this pattern in the official docs.

## Linking UI with MCP Tools

Once your resources and tools are registered, ChatGPT can use them together. When a user triggers your app, ChatGPT calls the tool on your MCP server. Your server returns:

- `content`: free-form text for ChatGPT to display.
- `structuredContent`: a JSON object (the “model sees this”).
- `_meta.openai/outputTemplate`: already set on the tool, which tells ChatGPT *which* UI to embed.

ChatGPT then creates an iframe for your widget at the bottom of the response. It injects your structured data into `window.openai.toolOutput` inside the iframe. Your React code (mounted on a div) reads that data and renders appropriately.

For example, a tool response might be:

```json
{
  "content": [{ "type": "text", "text": "Here's the latest weather:" }],
  "structuredContent": { "forecast": { "summary": "Sunny", "temp": 25 } },
  "_meta": { /* optional extra for widget */ }
}
```

Since `_meta.openai/outputTemplate` was set to your widget URI, ChatGPT will render:

```html
<div id="weather-widget-root"></div>
<script type="module">/* your widget JS bundled code */</script>
```

and then your `WeatherWidget` component reads `{ forecast: { ... } }` from `window.openai.toolOutput` to display the UI. This is exactly how the *Kanban Board* example works in the OpenAI docs: the server registers a `kanban-board.html` with a `<div id="kanban-root">` and script, then returns `structuredContent` with tasks to be rendered by the widget.

In summary, to inject React components:
1. **Register a HTML+JS resource** in your MCP server (`registerResource`) with a unique `uri` like `ui://widget/mycomponent.html`.
2. **Reference that URI in your tool’s `_meta.openai/outputTemplate`**.
3. **Return structuredContent from the tool**; the Apps SDK will hydrate your widget with that data.
4. **Mount your React component** into a root div in the HTML. Use `window.openai.toolOutput` inside your code to get the data.

## Testing and Deployment

To test locally, run your Next.js app (port 3000 by default). The MCP endpoint (e.g. `http://localhost:3000/api/mcp`) needs to be accessible via **HTTPS** to ChatGPT. During development, use a tunnel like **ngrok**:

```bash
ngrok http 3000
# Suppose it gives https://xyz123.ngrok.app
```

Then in ChatGPT Developer Mode, create a new *ChatGPT integration* (Connector) pointing to your server URL (e.g. `https://xyz123.ngrok.app/api/mcp`). ChatGPT will fetch your tool list (`List tools` operation) and let you call them. You can also try the [MCP Inspector](https://modelcontextprotocol.io) as an in-browser tester: point it at your `/mcp` endpoint and invoke tools manually.

For production, deploy to an HTTPS environment. Vercel (Next.js) or any cloud VM with a certificate works. Make sure your MCP endpoint is fast to avoid timeouts in ChatGPT. See OpenAI’s [Deploy your app](https://developers.openai.com/apps-sdk/deploy) docs for more.

## Sample Architecture

A simple architecture for a Next.js-based OpenAI App might look like:

- **Next.js server**  
  - **API route `/api/mcp`** runs an `McpServer`.  
  - Tools and Resources are registered here (using `@modelcontextprotocol/sdk`).  
  - Calls to external APIs (e.g. databases, other services) happen here.

- **React widget code**  
  - Lives in `components/` or a separate `web/` directory.  
  - Built into static files (JS/CSS) and served by the MCP server via `registerResource`.  
  - Communicates via `window.openai` APIs inside the iframe (e.g. `toolOutput`, `callTool`, `sendFollowupTurn`).

- **ChatGPT client**  
  - When user invokes an app, it calls the MCP server for data and widget code.  
  - Renders chat text and the iframe with your component.

```plaintext
[User ChatGPT] --calls--> [OpenAI ChatGPT Model]
                         --makes API calls--> [Your MCP Server @ Next.js]
                                               --serves UI resources-->
                         <--structured content, HTML-- 
         UI rendered in ChatGPT   <-- widget JS/CSS --
```

## Use Cases and Best Practices

**Use Cases:** OpenAI Apps can serve many scenarios. For example, you might build:
- A **travel planner** app: integrate Booking.com or Expedia, let users search hotels/flights with interactive calendars and maps.
- A **data visualization** app: plug into a database or API, show charts or dashboards inline.
- A **productivity tool**: e.g. a Kanban board, to-do list, or timeline inside chat.
- A **shopping assistant**: browse products from a store’s catalog with clickable images.
- **Financial tools**: stock quote lookup, calculator, or personal finance manager.
- **Educational aids**: language practice, math solvers with step-by-step UI.
  
Essentially, any service that benefits from conversational UI *plus* a visual interface can be an OpenAI App.

**Best Practices:**

- **Design for conversation:** Your app should fit seamlessly in chat. Provide text responses (`content`) along with your UI. Don’t overwhelm with UI; let the model also summarize key info.
- **Efficient structuredContent:** Only send data the UI needs. ChatGPT can see `structuredContent`, so don’t include sensitive info there. Use `_meta` for hidden data.
- **Version your UI:** ChatGPT aggressively caches widget URIs. When you update your JS/CSS, bump the resource URI (e.g. add a version in the name) to avoid stale content.
- **Security (CSP):** Widgets run in iframes with strict CSP. Define a content security policy (using `openai/widget` meta) so ChatGPT can inspect it. Allow only necessary sources/scripts.
- **Authentication:** If your app has user-specific data, implement auth (OAuth 2.0, JWT, etc.). The Apps SDK guides have sections on adding user identity. ChatGPT handles initial “connect” prompts.
- **Widget accessible:** If your widget needs to *call tools on its own* (e.g. user clicks a button to do something), set `_meta.openai.widgetAccessible: true` on those tools.
- **Optimize performance:** Keep payloads small and code lean. Large widgets or slow APIs can make the chat lag. The docs recommend keeping dependency bundles small.
- **Follow design guidelines:** OpenAI’s [developer guidelines](https://developers.openai.com/apps-sdk/design) outline quality and safety standards. Provide clear UX, handle errors, and follow usage policies.

By following these practices and leveraging MCP, your Next.js app can become a fully interactive OpenAI App. Developers have already done similar integrations (see [OpenAI’s example repo](https://github.com/openai/openai-apps-sdk-examples) and the Vercel MCP template).

## Conclusion

Integrating Next.js with OpenAI Apps involves running an MCP server in your Next.js backend and building React widgets for the front-end. The steps are:

1. **Set up an MCP server** (e.g. a Next.js API route) using `@modelcontextprotocol/sdk`.
2. **Define tools** with names, schemas, and link each to a UI template via `_meta["openai/outputTemplate"]`.
3. **Build React components** for your widgets, bundle them, and register the resulting HTML/JS in the MCP server.
4. **Return structured data** from tools so ChatGPT can hydrate the widgets.
5. **Test via Developer Mode** (using ngrok or a live URL) and then deploy to production with HTTPS.

This guide has covered the core concepts of **OpenAI Apps**, **MCP**, and how to wire them into a **Next.js** project. As OpenAI notes, the Apps SDK “extends MCP so developers can design both the logic and interface of their apps”. By following the steps above, you can create rich chat applications that run inside ChatGPT, leveraging the best of conversational AI and web UIs.

**References:** This guide draws on OpenAI’s official docs and community resources. See OpenAI’s [Apps SDK documentation](https://developers.openai.com/apps-sdk/), the [openai-apps-sdk-examples](https://github.com/openai/openai-apps-sdk-examples) repo, and recent announcements for more details.

---