openai/openai-apps-sdk-examples

openai/openai-apps-sdk-examples

Description: Example apps for the Apps SDK

Language: TypeScript

License: MIT

Stars: 2251

Forks: 506

Open issues: 129

Created: 2025-10-06T05:28:01Z

Pushed: 2026-04-15T17:01:42Z

Default branch: main

Fork: no

Archived: no

README:

Apps SDK Examples Gallery

This repository showcases example UI components to be used with the Apps SDK, as well as example MCP servers that expose a collection of components as tools. It is meant to be used as a starting point and source of inspiration to build your own apps for ChatGPT.

Note: If you are on Chrome and have recently updated to version 142, you will need to disable the `local-network-access` flag to see the widget UI.

How to disable it:

1. Go to chrome://flags/ 2. Find #local-network-access-check 3. Set it to Disabled

⚠️ Note 🚨 Make sure to restart Chrome after changing this flag for the update to take effect.

MCP + Apps SDK overview

The Model Context Protocol (MCP) is an open specification for connecting large language model clients to external tools, data, and user interfaces. An MCP server exposes tools that a model can call during a conversation and returns results according to the tool contracts. Those results can include extra metadata—such as inline HTML—that the Apps SDK uses to render rich UI components (widgets) alongside assistant messages.

Within the Apps SDK, MCP keeps the server, model, and UI in sync. By standardizing the wire format, authentication, and metadata, it lets ChatGPT reason about your connector the same way it reasons about built-in tools. A minimal MCP integration for Apps SDK implements three capabilities:

1. List tools – Your server advertises the tools it supports, including their JSON Schema input/output contracts and optional annotations (for example, readOnlyHint). 2. Call tools – When a model selects a tool, it issues a call_tool request with arguments that match the user intent. Your server executes the action and returns structured content the model can parse. 3. Return widgets – Alongside structured content, return embedded resources in the response metadata so the Apps SDK can render the interface inline in the Apps SDK client (ChatGPT).

Because the protocol is transport agnostic, you can host the server over Server-Sent Events or streaming HTTP—Apps SDK supports both.

The MCP servers in this demo highlight how each tool can light up widgets by combining structured payloads with _meta.ui.resourceUri metadata returned from the MCP servers.

Repository structure

• src/ – Source for each widget example.
• assets/ – Generated HTML, JS, and CSS bundles after running the build step.
• shopping_cart_python/ – Python MCP server that demonstrates how _meta["widgetSessionId"] keeps widgetState in sync across turns for a shopping-cart widget.
• pizzaz_server_node/ – MCP server implemented with the official TypeScript SDK.
• pizzaz_server_python/ – Python MCP server that returns the Pizzaz widgets.
• solar-system_server_python/ – Python MCP server for the 3D solar system widget.
• kitchen_sink_server_node/ – Node MCP server for the kitchen-sink-lite widget.
• kitchen_sink_server_python/ – Python MCP server for the kitchen-sink-lite widget.
• authenticated_server_python/ – Python MCP server that demonstrates authenticated tool calls.
• build-all.mts – Vite build orchestrator that produces hashed bundles for every widget entrypoint.

Pizzaz overview

This example contains multiple components showing multiple types of views and interactions: a list view, a carousel view, a map view. It also contains a "pizzaz shop" showing interactive flows and a checkout page.

This example uses the Apps SDK UI library for simple components such as images, buttons, and badges.

Kitchen sink lite overview

The kitchen sink lite sample shows the full window.openai surface working together:

• Reads host state (toolInput, toolOutput, displayMode, theme, widgetState).
• Writes host state with setWidgetState.
• Calls another MCP tool from the widget with callTool.
• Uses host helpers like requestDisplayMode, openExternal, and sendFollowUpMessage.

Use it as a reference for how to wire UI to MCP tool responses and host APIs with the Apps SDK UI components.

Prerequisites

• Node.js 18+
• pnpm (recommended) or npm/yarn
• Python 3.10+ (for the Python MCP server)
• pre-commit for formatting

Install dependencies

Clone the repository and install the workspace dependencies:

pnpm install
pre-commit install

> Using npm or yarn? Install the root dependencies with your preferred client and adjust the commands below accordingly.

Build the components gallery

The components are bundled into standalone assets that the MCP servers serve as reusable UI resources.

pnpm run build

This command runs build-all.mts, producing versioned .html, .js, and .css files inside assets/. Each widget is wrapped with the CSS it needs so you can host the bundles directly or ship them with your own server.

To iterate on your components locally, you can also launch the Vite dev server:

pnpm run dev

Serve the static assets

All of the MCP servers expect the bundled HTML, JS, and CSS to be served from the local static file server. After every build, start the server before launching any MCP processes:

pnpm run serve

The assets are exposed at `http://localhost:4444` with CORS enabled so that local tooling (including MCP inspectors) can fetch them.

> Note: The Python Pizzaz server caches widget HTML with functools.lru_cache. If you rebuild or manually edit files in assets/, restart the MCP server so it picks up the updated markup.

Run the MCP servers

The repository ships several demo MCP servers that highlight different widget bundles:

• Pizzaz (Node & Python) – pizza-inspired collection of tools and components
• Solar system (Python) – 3D solar system viewer
• Authenticated (Python) – set of tools that require different levels of OAuth
• Kitchen sink lite (Node & Python) – minimal widget + server pairing that demonstrates tool output, widget state, callTool, and host helpers
• Shopping cart (Python) – simple shopping cart widget…