skybridge

Build ChatGPT & MCP Apps. The Modern TypeScript Way.

The fullstack TypeScript framework for AI-embedded widgets. Type-safe. React-powered. Platform-agnostic.

Documentation · Quick Start · Showcase

✨ Why Skybridge?

ChatGPT Apps and MCP Apps let you embed rich, interactive UIs directly in AI conversations. But the raw SDKs are low-level—no hooks, no type safety, no dev tools, and no HMR.

Skybridge fixes that.

| | | |:--|:--| | 🌐 Write once, run everywhere — Skybridge works seamlessly with ChatGPT (Apps SDK) and MCP-compatible clients. | ✅ End-to-End Type Safety — tRPC-style inference from server to widget. Autocomplete everywhere. | | 🔄 Widget-to-Model Sync — Keep the model aware of UI state with data-llm. Dual surfaces, one source of truth. | ⚒️ React Query-style Hooks — isPending, isError, callbacks. State management you already know. | | 👨‍💻 Full dev environment — HMR, debug traces, and local devtools. | 📦 Showcase Examples — Production-ready examples to learn from and build upon. |

🚀 Get Started

Create a new app:

npm create skybridge@latest

Or add to an existing project:

npm i skybridge
yarn add skybridge
pnpm add skybridge
bun add skybridge
deno add skybridge

👉 Read the Docs 👈

📦 Architecture

Skybridge is a fullstack framework with unified server and client modules:

• skybridge/server — Define tools and widgets with full type inference. Extends the MCP SDK.
• skybridge/web — React hooks that consume your server types. Works with Apps SDK (ChatGPT) and MCP Apps.
• Dev Environment — Vite plugin with HMR, DevTools emulator, and optimized builds.

Server

import { McpServer } from "skybridge/server";

server.registerWidget("flights", {}, {
  inputSchema: { destination: z.string() },
}, async ({ destination }) => {
  const flights = await searchFlights(destination);
  return { structuredContent: { flights } };
});

Widget

import { useToolInfo } from "skybridge/web";

function FlightsWidget() {
  const { output } = useToolInfo();

  return output.structuredContent.flights.map(flight =>
    <FlightCard key={flight.id} flight={flight} />
  );
}

🎯 Features at a Glance

• Live Reload — Vite HMR. See changes instantly without reinstalling.
• Typed Hooks — Full autocomplete for tools, inputs, outputs.
• Widget → Tool Calls — Trigger server actions from UI.
• Dual Surface Sync — Keep model aware of what users see with data-llm.
• React Query-style API — isPending, isError, callbacks.
• Platform Agnostic — Works with ChatGPT (Apps SDK) and MCP Apps clients (Goose, VSCode, etc.).
• MCP Compatible — Extends the official SDK. Works with any MCP client.

📖 Showcase

Explore production-ready examples:

| Example | Description | Demo | Code | |------------------------|----------------------------------------------------------------------------------|-----------------------------------------------------|-------------------------------------------------------------------------------------| | Awaze — Cottage Search | Holiday cottage search and booking experience — browse properties, filter by location, and explore availability | Try Demo | — | | Capitals Explorer | Interactive world map with geolocation and Wikipedia integration | Try Demo | View Code | | Ecommerce Carousel | Product carousel with cart, localization, and modals | Try Demo | View Code | | Everything | Comprehensive playground showcasing all hooks and features | Try Demo | View Code | | Investigation Game | Interactive murder mystery game with multi-screen gameplay and dynamic story progression | Try Demo | View Code | | Productivity | Data visualization dashboard demonstrating Skybridge capabilities for MCP Apps | Try Demo | View Code | | Time's Up | Word-guessing party game where the user gives hints and the AI tries to guess the secret word | Try Demo | View Code | | Lumo — Interactive AI Tutor | Adaptive educational tutor with Mermaid.js diagrams, mind maps, quizzes, and fill-in-the-blank exercises | Try Demo | View Code | | Auth — Auth0 | Full OAuth authentication with Auth0 and personalized coffee shop search | — | View Code | | Auth — Clerk | Full OAuth authentication with Clerk and personalized coffee shop search | — | View Code | | Auth — Stytch | Full OAuth authentication with Stytch and personalized coffee shop search | — | View Code | | Auth — WorkOS AuthKit | Full OAuth authentication with WorkOS AuthKit and personalized coffee shop search | — | View Code | | Flight Booking | Flight booking carousel with dynamic search and booking flow | Try Demo | View Code | | Generative UI | Dynamic UI generation using json-render and Skybridge | Try Demo | View Code | | Manifest Starter | Starter app with Manifest UI agentic components out-of-the-box | Try Demo | View Code |

See all examples in the Showcase or browse the examples/ directory.

See CONTRIBUTING.md for setup instructions

MIT License · Made with ❤️ by Alpic