Apps SDK Examples Gallery

This repository contains production-ready example UI components for the Apps SDK together with a companion MCP server. Use it as a starting point or as a reference when building your own connectors for ChatGPT.

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 the 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.

This MCP server highlights how a tool can light up widgets by combining structured payloads with _meta.openai/outputTemplate metadata returned from the server.

Repository structure

• src/ – Source for each widget example (Todo list and MyCareersFuture search).

• assets/ – Generated HTML, JS, and CSS bundles after running the build step.

• mycareersfuture_server_python/ – Python MCP server that renders live job dashboards.

• build-all.mts – Vite build orchestrator that produces hashed bundles for every widget entrypoint.

Prerequisites

• Node.js 18+

• pnpm (recommended) or npm/yarn

• Python 3.10+ (for the Python MCP server)

Install dependencies

Clone the repository and install the workspace dependencies:

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 server serves as reusable UI resources.

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.

Need a deeper breakdown of the MCP server? See MCP_SERVER.md.

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

Serve the static assets

If you want to preview the generated bundles without the MCP server, start the static file server after running a build:

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

Run the MCP server

The repository ships one MCP server that highlights how to power a widget with live data:

• MyCareersFuture (Python) – live job search dashboards powered by the public API.

Every tool response includes plain text content, structured JSON, and _meta.openai/outputTemplate metadata so the Apps SDK can hydrate the matching widget.

MyCareersFuture Python server

Testing in ChatGPT

To add these apps to ChatGPT, enable developer mode, and add your apps in Settings > Connectors.

To add your local server without deploying it, you can use a tool like ngrok to expose your local server to the internet.

For example, once your MCP server is running, you can run:

You will get a public URL that you can use to add your local server to ChatGPT in Settings > Connectors.

For example: https://<custom_endpoint>.ngrok-free.app/mcp

Once you add a connector, you can use it in ChatGPT conversations.

You can add your app to the conversation context by selecting it in the "More" options.

You can then invoke tools by asking something related. For example, for the MyCareersFuture connector, you can ask "Find software engineering openings in Singapore."

Next steps

• Customize the widget data: edit the handlers in mycareersfuture_server_python/main.py to connect to your own systems or APIs.

• Create additional widgets by adding new entries into src/—the build orchestrator discovers them automatically.

Contributing

You are welcome to open issues or submit PRs to improve this app, however, please note that we may not review all suggestions.

License

This project is licensed under the MIT License. See LICENSE for details.