MCP App Starter (Skybridge + OpenAI Apps SDK UI + Storybook)

A domain-agnostic template for building ChatGPT Apps and MCP Apps with:

• Skybridge
• OpenAI Apps SDK UI
• React + Vite + Tailwind CSS
• Biome for linting and formatting
• Storybook for isolated component development

Skybridge provides the abstraction layer so app code can focus on widget components and tool behavior instead of low-level MCP plumbing.

Skybridge supports both MCP Apps and ChatGPT Apps. Background on MCP Apps: MCP Apps: The next chapter for MCP.

Why this template

• Build once for both ChatGPT App and MCP App use cases.
• Keep architecture simple and typed end to end.
• Develop UI in Storybook (fast, isolated feedback) instead of depending on chat-only render loops.
• Use Skybridge devtools tooling locally during non-production runs (including inspector/debug workflows).

Runtime architecture (quick view)

1. server/src/server.ts creates an McpServer and registers widgets/tools.
2. server/src/index.ts calls server.run() to start the server with built-in MCP middleware, devtools, and asset serving.
3. web/src/widgets/starter.tsx mounts a widget entrypoint with mountWidget.
4. web/src/helpers.ts uses generateHelpers<AppType>() to type frontend tool output from server definitions.

For deeper docs, see /docs.

Current starter widget files

• web/src/widgets/starter.tsx - widget entrypoint mounted by Skybridge
• web/src/widgets/StarterAlertSection.tsx - primary starter alert block
• web/src/widgets/StarterNextStepsSection.tsx - suggested next customization steps
• web/src/widget.tsx - required root wrapper that imports index.css

Prerequisites

• Node.js 24+
• pnpm

Quickstart

pnpm install
pnpm dev

Local endpoints:

• App/devtools: http://localhost:3000
• MCP endpoint: http://localhost:3000/mcp
• Storybook (separate process): http://localhost:6006

Scripts

• pnpm dev - run local Skybridge dev stack
• pnpm prepare - install git hooks via lefthook
• pnpm check - TypeScript type-check (tsc --noEmit)
• pnpm lint - check code with Biome linter
• pnpm format - check code formatting with Biome
• pnpm biome:check - run both lint and format checks
• pnpm biome:fix - automatically fix lint and format issues
• pnpm build - production build via Skybridge
• pnpm start - run built app
• pnpm start.local - run built app with .env support
• pnpm preview - build + start locally
• pnpm storybook - run Storybook on http://localhost:6006
• pnpm build-storybook - build Storybook static output

Repository map

• server/src/index.ts - Entry point that calls server.run() to start the server
• server/src/server.ts - Starter widget registration and tool handler output
• web/src/helpers.ts - Typed helper generation from server AppType
• web/src/widget.tsx - Root style import wrapper
• web/src/widgets/ - Widget entrypoints, UI components, and stories
• .storybook/ - Storybook config (Tailwind + alias + static assets)
• docs/ - Architecture and development documentation

Customize flow

1. Register or update tools/widgets in server/src/server.ts.
2. Create matching widget entrypoints and UI components in web/src/widgets/.
3. Add or update stories near components (*.stories.tsx) and iterate in Storybook first.
4. Validate with pnpm check, pnpm biome:check, and pnpm build.
5. Run pnpm prepare once per clone so pre-commit checks run automatically.