Skip to main content

​
MCP and ChatGPT Apps Fundamentals

To build effectively with Skybridge, you first need to understand the underlying technologies it builds upon:
Read our in-depth blog article to understand how ChatGPT Apps work

​
MCP (Model Context Protocol)

MCP is an open standard that allows AI models to connect with external tools, resources, and services. Think of it as an API layer specifically designed for LLMs. An MCP server exposes:
  • Tools: Functions the model can call (e.g., search_flights, get_weather)
  • Resources: Data the model can access (e.g., files, UI components)
When you ask ChatGPT a question, it can invoke tools on your MCP server to fetch data or perform actions on your behalf.

​
ChatGPT Apps

ChatGPT Apps, announced by OpenAI in October 2025, extend MCP with a powerful new capability: interactive UI widgets that render directly inside the conversation.

​
How ChatGPT Apps Work

A ChatGPT App consists of two components:
  1. MCP Server: Handles your business logic and exposes tools
  2. UI Widgets: UI components that render in ChatGPT’s interface
When a tool is called, it can return both:
  • Text content: What the model sees and responds with
  • Widget content: A visual UI that renders for the user
This creates a dual-surface interaction model: users interact with both the conversational interface (ChatGPT) and your custom UI (widget).

​
The Widget Rendering Flow

Here’s what happens when ChatGPT renders a widget:
  1. User asks ChatGPT to perform an action (e.g., “Show me flight options to Paris”)
  2. ChatGPT calls your MCP tool (e.g., search_flights)
  3. Your tool returns a result with data, and if the tool contains a reference to a UI resource, ChatGPT fetches the resource (your compiled React component) and renders it in an iframe, hydrated with your tool’s structuredContent and _meta properties.

​
The window.openai API

Widgets run inside an iframe and have access to a special window.openai API that enables: This API is powerful but low-level and imperative—which is where Skybridge comes in.

​
Skybridge Hook Mapping

Skybridge wraps the raw window.openai API with React hooks:
Raw APISkybridge HookPurpose
window.openai.toolOutputuseToolInfo()Access initial tool input/output
window.openai.widgetStateuseWidgetState()Persistent widget state
window.openai.callTool()useCallTool()Make additional tool calls
window.openai.sendFollowUpMessage()useSendFollowUpMessage()Send follow-up messages
window.openai.openExternal()useOpenExternal()Open external URLs
window.openai.requestModal()useRequestModal()Request modal display
window.openai.themeuseLayout()Access ChatGPT theme
window.openai.localeuseUser()Access user locale
window.openai.displayModeuseDisplayMode()Access/change display mode

​
What Skybridge Adds

Skybridge is a modular ChatGPT Apps framework that bridges the gap between standard MCP servers and OpenAI APIs. It includes:
  • skybridge/server: A drop-in replacement for the official MCP SDK that adds widget registration and type inference capabilities.
  • skybridge/web: A React library providing hooks, components, and the runtime glue to render your widgets inside ChatGPT’s iframe environment.
  • Local Dev Environment: A Vite plugin adds Hot Module Reload to your ChatGPT Apps, with optimized assets building for both local and production environments.
This lets you build rich, React-based UI experiences directly within ChatGPT conversations—all with full type safety and a developer experience you’ll love. Next: Start building with the Quickstart Guide.