Chatgpt App Builder

Creating Apps For LLMs

ChatGPT apps are conversational experiences that extend ChatGPT through tools and custom UI views. They're built as MCP servers invoked during conversations.

⚠️ The app is consumed by two users at once: the human and the ChatGPT LLM. They collaborate through the view—the human interacts with it, the LLM sees its state. Internalize this before writing code: the view is your shared surface.

SPEC.md keeps track of the app's requirements and design decisions. Keep it up to date as you work on the app.

No SPEC.md? → Read discover.md first. Nothing else until SPEC.md exists.

SPEC.md exists? → Read SPEC.md, then follow architecture.md to design the change. Update SPEC.md, then read the relevant Implementation references below before writing code.

Setup

1. Copy template → copy-template.md: when starting a new project with ready SPEC.md 2. Run locally → run-locally.md: when ready to test, need dev server or ChatGPT connection

Architecture

Design or evolve UX flows and API shape → architecture.md

Implementation

• Fetch and render data → fetch-and-render-data.md: when implementing server handlers and view data fetching
• State and context → state-and-context.md: when persisting view UI state and updating LLM context
• Prompt LLM → prompt-llm.md: when view needs to trigger LLM response
• UI guidelines → ui-guidelines.md: display modes, layout constraints, theme, device, and locale
• External links → open-external-links.md: when redirecting to external URLs or setting "open in app" target
• OAuth → oauth.md: when tools need user authentication to access user-specific data
• CSP → csp.md: when declaring allowed domains for fetch, assets, redirects, or iframes

Deploy

• Ship to production → deploy.md: when ready to deploy via Alpic
• Publish to ChatGPT Directory → publish.md: when ready to submit for review

Full API docs: https://docs.skybridge.tech/api-reference.md

Evals

Manual evaluations for the creating-chatgpt-app skill.

Format

Each eval file is a JSON array:

[
  {
    "query": "User input to test",
    "expected_behavior": "OUTCOME. What the response should do."
  }
]

Running Evals

In Claude Code:

Run the evals in evals/<reference>.json. For each query, spawn a Sonnet agent with the relevant skill context and compare the response against expected_behavior. Feed the whole SKILL.md and evaluated reference file without compression. Report pass/fail for each.

Architecture Workflow

Concepts

A tool is a backend action with no UI. It takes input and returns structured output. It can CRUD data and perform operations (checkout, submit, etc.).

A view is a tool with a UI. It renders the tool output visually. The UI is a React app that can:

• navigate multiple views (search → detail → confirmation)
• manage its own state
• call other tools to fetch data absent from the view output schema or trigger actions.

Step 1: Identify the UX Flows

A flow is an end-to-end user journey that accomplishes one goal (e.g., "book a flight" = search → select → checkout). Extract flows from the SPEC's value proposition. Stick to the spec: don't invent flows or infer intermediate steps.

Example:

Input (SPEC):

Book flights by destination and dates, and cancel existing bookings by booking ID.

✅ Good output:

Book flight:
1. Search flights
2. Select flight
3. Checkout
Cancel booking:
1. Cancel booking

❌ Bad output:

Search flights:
1. Search flights
2. View results
Book flight: ← wrong: split booking into separate flow
1. Select flight
2. Enter passenger details
3. Checkout
Cancel booking:
1. List bookings ← wrong: invented step
2. Cancel booking

Do not proceed to Step 2 yet: validate with user, adjust based on feedback.

Step 2: Does the flow need UI?

Based on the UX flow:

YES if:

• Browsing/comparing multiple items
• Visual data improves understanding (maps, charts, images)
• Selections are easier in a visual layout

NO if:

• Inputs are naturally conversational (amounts, dates, descriptions)
• Output is simple enough as text
• No visual element would meaningfully improve the experience

Step 3: Design the API

Best Practices

Naming: Both views and tools start with a verb: search_flights, get_details, create_checkout.

One view per flow/intent: Different flows can have separate views ❌ search_flights view + view_flight view (same flow → merge into one view) ✅ search_flights view + manage_bookings view (different flows)

Don't duplicate: View output is returned to the LLM for conversation. View can be re-invoked. Don't create a tool that duplicates what the view fetches. ❌ search_flights view + get_flights tool (same data → view already fetches this) ✅ unique search_flights view that can be re-invoked by LLM or user

View UI handles its own state: Cart, selections, and form inputs live in the view - not as tools. ❌ add_to_cart tool (cart is view state) ❌ select_seat tool (selection is view state) ❌ update_quantity tool (form input is view state) ✅ Tools are for backend operations only: create_checkout, submit_order, make_reservation

Don't lazy-load: Tool calls are expensive. Return all needed data upfront. ❌ search_flights view + get_flight_details tool (lazy-loading details) ✅ search_flights view returns full flight data including details

---

For each identified flow:

If NEEDS UI → View + Optional Tool(s)

Example: Flight Booking

UX Flow: 1. Search flights by dates, destination 2. Browse results, select flight 3. View flight details 4. Click checkout → redirect to payment

API:

View: search_flights

• Input: { dates, destination }
• Output: { flights } → rendered as list
• Views: search results, flight detail + passenger form
• Calls create_checkout tool → redirects to payment

Tool: create_checkout

• Input: { flightId, passengers[] }
• Output: { checkoutUrl } → view redirects to Stripe

If DOES NOT NEED UI → Tool(s) Only

Example: Manage Bookings

UX Flow: 1. User: "Cancel my flight to Paris" 2. LLM asks for email, fetches bookings, asks clarifying questions if needed 3. LLM confirms and cancels

API:

Tool: list_bookings

• Input: { email }
• Output: { booking[] } → LLM says "You have two upcoming flights for Paris, which one do you want to cancel?"

Tool: cancel_booking

• Input: { bookingId }
• Output: { booking } → LLM summarizes: "Your booking for Paris on Jan 1 has been canceled."

Step 4: Review

Present the final architecture to the user, adjust based on feedback.

Step 5: Update SPEC.md

Update SPEC.md with the UX flows and API design.

Example:

...

## UX Flows

Book a flight:
1. Search flights by destination and dates
2. Browse results, select flight
3. Enter passenger details
4. Checkout (redirect to Stripe)

Cancel booking:
1. Provide email
2. Select booking to cancel

## Tools and Views

**View: search_flights**
- **Input**: `{ destination, dates }`
- **Output**: `{ flights[] }`
- **Views**: results list, flight detail, passenger form
- **Behavior**: manages passenger state locally, calls `create_checkout` tool

**Tool: create_checkout**
- **Input**: `{ flightId, passengers[] }`
- **Output**: `{ checkoutUrl }`

**Tool: list_bookings**
- **Input**: `{ email }`
- **Output**: `{ bookings[] }`

**Tool: cancel_booking**
- **Input**: `{ bookingId }`
- **Output**: `{ success, booking }`

Start From Template

Scaffold a project by setting up the Skybridge template starter. Skybridge is a TypeScript framework for building MCP servers with type-safe APIs and React views.

Workflow

1. Ask: "Which package manager?" (npm / pnpm / yarn / bun / deno)

2. Run (do not rm beforehand—create handles conflicts):

{pm} create skybridge@latest {target-dir}

# deno
deno init --npm skybridge {target-dir}

3. Start the dev server. Read logs to assess readiness/health; fix any errors (TypeScript, etc.) before proceeding.

4. Start implementing your app using these core concepts:

• Server handlers and view components → fetch-and-render-data.md
• View state and LLM context → state-and-context.md
• Display modes → ui-guidelines.md

5. Delete unused views files and leftover code.

Content Security Policy

Views run in sandboxed iframes with strict CSP. Whitelist external domains under the tool's view.csp:

server.registerTool(
  {
    name: "search-flights",
    description: "Search flights",
    inputSchema: { ... },
    view: {
      component: "search-flights",
      description: "Flight results",
      csp: {
        connectDomains: ["https://api.example.com"],
        resourceDomains: ["https://cdn.example.com"],
        frameDomains: ["https://maps.example.com"],
        redirectDomains: ["https://checkout.example.com"],
      },
    },
  },
  async (input) => ({ ... })
);

Skybridge auto-includes the server's domain. Only add external domains.

Deploy

Deploy to Alpic using Alpic CLI.

Parameters

• {path-to-project} is the path to the project directory. It is relative to the current working directory.
• When executing a command requiring {path-to-project}, check that you provided the correct path to the project.

Steps

1. Make sure the user is logged in to Alpic

Execute npx alpic@latest login to login to Alpic.

2. Deploy to Alpic

If it's a first time deployment (absence of .alpic/ folder in the project directory), ask the user for the project name. Then, execute npx alpic@latest deploy --yes --project-name {project-name} {path-to-project}.

3. Subsequent deployments

For subsequent deployments (presence of .alpic/ folder in the project directory), execute npx alpic@latest deploy --yes {path-to-project}.

4. Setup GitHub integration

If it's a new project, ask the user first if they want to setup git. If yes:

• Push to GitHub — Commit and push code
• Link to Alpic project - Use npx alpic@latest git connect --yes {path-to-project}

Full docs: docs.alpic.ai/quickstart

Discovery Workflow

Goal: Idea maturation, not speed.

Proceed in phases. Even if the user provides details, complete each phase through conversation. Do not infer or assume but discuss and validate with user. Proceed one phase at a time—do not write SPEC.md nor proceed to implementation until all phases are validated.

---

Phase 1: Value Proposition

1. Problem + User: What problem? For whom? 2. Pain: How solved today? What's painful? 3. Core actions: 1-3 focused actions (not a full app port)

---

Phase 2: Why LLM?

1. Conversational win: Where does "just say it" beat clicking? 2. LLM adds: What does the LLM contribute? (intent, generation, reasoning) 3. What LLM lacks: Your data? APIs? Ability to take real actions?

Fail patterns (stop if any match):

• Long-form or static content better suited for a website
• Complex multi-step workflows that exceed display modes
• Dashboards (use tables, lists, or short paragraphs instead)
• Full app ports instead of focused atomic actions
• No clear answer to "why inside an AI assistant vs standalone?"

→ If fails: explain gap, suggest different interface or narrower scope.

---

Phase 3: UI Overview

Describe the user journey through core actions:

1. First view: What does the user see when they start? 2. Key interactions: What happens at each core action? 3. End state: How does the experience conclude?

---

Phase 4: Product Context

Gather: existing products, APIs/data, auth method, constraints.

---

Phase 5: Create SPEC.md

Only after phases 1-4 are discussed and validated with the user. Do not write SPEC.md from the initial query alone.

Assemble from phases. Target: cwd if empty, else {app-name}/.

Example

# Pizza Ordering App

## Value Proposition
Order pizza through conversation. Target: PizzaCo customers wanting quick orders. Pain: navigating menus is slower than describing what you want.

**Core actions**: Browse menu, customize order, track delivery.

## Why LLM?
**Conversational win**: "My usual but with mushrooms" = one sentence vs. multiple screens.
**LLM adds**: Intent from natural descriptions, handles modifications.
**What LLM lacks**: Real menu and pricing data, order placement.

## UI Overview
**First view**: Popular pizzas with quick "reorder last" option.
**Browsing**: Menu with categories, filters, and customization options.
**Checkout**: Order summary, confirm, and place order.
**Tracking**: Live delivery status with ETA and map.

## Product Context
- **Existing products**: Mobile app, website
- **API**: REST at api.pizzaco.com (OAuth2, 100 req/min)
- **Auth**: PizzaCo account (OAuth2)
- **Constraints**: Payment via existing account only

After SPEC.md is created, confirm with user before proceeding to implementation.

Download file

Save content to the user's filesystem → useDownload

Views run in sandboxed iframes where <a download> and URL.createObjectURL are blocked. useDownload asks the host to perform the save; the host shows a confirmation dialog first.

MCP Apps only. On ChatGPT (Apps SDK), use useFiles to work with attachments instead.

Inline text (CSV, JSON, markdown)

import { useDownload } from "skybridge/web";

function ExportButton({ rows }: { rows: Row[] }) {
  const { download } = useDownload();

  const handleClick = async () => {
    const csv = rows.map((r) => `${r.id},${r.name}`).join("\n");
    const { isError } = await download({
      contents: [
        {
          type: "resource",
          resource: {
            uri: "file:///orders.csv", // filename hint
            mimeType: "text/csv",
            text: csv,
          },
        },
      ],
    });
    if (isError) {
      // user cancelled or host denied — soft fail, not an exception
    }
  };

  return <button onClick={handleClick}>Export CSV</button>;
}

Inline binary

await download({
  contents: [
    {
      type: "resource",
      resource: {
        uri: "file:///chart.png",
        mimeType: "image/png",
        blob: base64EncodedPng,
      },
    },
  ],
});

Resource link (host fetches)

await download({
  contents: [
    {
      type: "resource_link",
      uri: "https://api.example.com/reports/q4.pdf",
      name: "Q4 Report",
      mimeType: "application/pdf",
    },
  ],
});

Notes

• Must be user-initiated (button/menu click). Calls from mount effects will be rejected.
• The uri is a filename hint; the host derives the suggested save name from the last path segment.
• isError: true is a soft signal (user cancelled / host denied). Transport errors throw.
• For binary content above a few hundred KB, prefer resource_link over inline base64.

Fetch and render data

• Fetch structured data and render with custom UI → view
• Fetch textual data or trigger actions → tool
• Tool can be triggered by user interaction within a view UI

Project Structure

my-app/
├── src/
│   ├── server.ts         # McpServer with tool + view registration
│   ├── helpers.ts        # Type-safe hooks via generateHelpers
│   ├── index.css         # Global CSS, must be imported in every view
│   └── views/            # React components (filename = view component name)
│       └── search-flights.tsx
└── package.json

Naming convention: View filename must match the view.component name using kebab-case. search_flights → register with view.component: "search-flights" → file views/search-flights.tsx

Server Handlers

Output:

• `structuredContent`: concise JSON the view uses and the model reads. Include only what the model should see.
• `content` (optional): narration (Markdown or plaintext) shown to LLM
• `_meta` (optional): large or sensitive data exclusively for the view. _meta never reaches the model.

Annotations (set true when):

• `readOnlyHint`: only reads data, no side effects
• `openWorldHint`: publishes content or reaches outside user's account
• `destructiveHint`: deletes or overwrites user data

Example:

• src/server.ts

import { McpServer } from "skybridge/server";
import { z } from "zod";

const server = new McpServer(
  { name: "my-app", version: "0.0.1" },
  { capabilities: {} },
)
  .registerTool(
    {
      name: "search-flights",
      description: "Search for flights",
      inputSchema: { destination: z.string(), dates: z.string() },
      annotations: { readOnlyHint: true, openWorldHint: false, destructiveHint: false },
      view: {
        component: "search-flights",
        description: "Flight results",
      },
    },
    async ({ destination, dates }) => {
      const flights = await fetchFlights(destination, dates);
      const structuredContent = { flights: [] };
      const _meta = { images: [] }
      for (const { id, departureTime, price, airlineLogo } of flights) {
        structuredContent.flights.push({ id, departureTime, price });
        _meta.images.push(airlineLogo);
      }
      return {
        structuredContent,
        content: [{ type: "text", text: `Found ${flights.length} flights.` }],
        _meta // mind the underscore prefix
      };
    }
  )
  .registerTool(
    {
      name: "book-flight",
      description: "Book a flight",
      inputSchema: { flightId: z.string() },
      annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: false },
    },
    async ({ flightId }) => {
      const confirmationId = await bookFlight(flightId);
      return {
        structuredContent: { confirmationId },
        content: [{ type: "text", text: `Flight booked. Confirmation: ${confirmationId}` }],
      };
    }
  );

server.run();

export type AppType = typeof server;

UI Components

• generate type-safe hooks with generateHelpers
• useToolInfo: access view input/output
• useCallTool: trigger tool from UI

Example:

• src/helpers.ts

import { generateHelpers } from "skybridge/web";
import type { AppType } from "./server.js";

export const { useToolInfo, useCallTool } = generateHelpers<AppType>();

• src/views/search-flights.tsx

import "@/index.css";
import { useToolInfo, useCallTool } from "../helpers.js";

export default function SearchFlights() {
  const { input, output, isPending, responseMetadata } = useToolInfo<"search-flights">();
  const {
    callTool, // returns void, use `data` to get the actual output
    data: bookFlightOutput,
    isPending: isBooking,
    isSuccess: isBooked,
  } = useCallTool("book-flight");

  if (isPending) {
    return <div>Searching flights to {input?.destination}...</div>;
  }

  if (isBooked) {
    return <div>Booked! Confirmation: {bookFlightOutput.structuredContent.confirmationId}</div>;
  }

  return (
    <div>
      <h2>Flights to {input.destination}</h2>
      <ul>
        {output.flights.map((flight, i) => (
          <li key={i}>
            <img src={responseMetadata.images[i]} />
            {flight.departureTime} - ${flight.price}
            <button
              onClick={() => callTool({ flightId: flight.id })}
              disabled={isBooking}
            >
              {isBooking ? "Booking..." : "Book"}
            </button>
          </li>
        ))}
      </ul>
    </div>
  );
}

OAuth Authentication

Enable user authentication so tools can access user-specific data.

How it works

1. MCP server exposes OAuth discovery endpoints 2. Host reads them, walks the user through OAuth, refreshes tokens 3. Host calls /mcp with Authorization: Bearer <token> 4. requireBearerAuth middleware verifies the token and rejects with HTTP 401 if invalid — tool handlers never run unauthenticated 5. Tool handlers read user identity from extra.authInfo

1. Discovery endpoints

Mount OAuth metadata so MCP clients can discover the authorization server:

// src/server.ts
import { mcpAuthMetadataRouter } from "@modelcontextprotocol/sdk/server/auth/router.js";
import { McpServer } from "skybridge/server";

const server = new McpServer(
  { name: "my-app", version: "0.0.1" },
  { capabilities: {} },
).use(
  mcpAuthMetadataRouter({
    oauthMetadata: {
      issuer: "https://your-oauth-provider.com",
      authorization_endpoint: "https://your-oauth-provider.com/oauth2/authorize",
      token_endpoint: "https://your-oauth-provider.com/oauth2/token",
      response_types_supported: ["code"],
      grant_types_supported: ["authorization_code", "refresh_token"],
      code_challenge_methods_supported: ["S256"],
    },
    // SERVER_URL: this server's public URL (localhost:3000, Alpic tunnel, or prod)
    resourceServerUrl: new URL(process.env.SERVER_URL),
  }),
);

This serves /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource.

2. Write a token verifier

requireBearerAuth takes a verifier with verifyAccessToken(token): Promise<AuthInfo>. Verify the provider's JWT against its JWKS:

⚠️ Fetch your provider's docs for the exact JWKS URL and issuer.

// src/auth.ts
import { InvalidTokenError } from "@modelcontextprotocol/sdk/server/auth/errors.js";
import type { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";
import * as jose from "jose";

const jwks = jose.createRemoteJWKSet(
  new URL("https://your-oauth-provider.com/oauth2/jwks"),
);

export async function verifyAccessToken(token: string): Promise<AuthInfo> {
  const { payload } = await jose.jwtVerify(token, jwks, {
    issuer: "https://your-oauth-provider.com",
  });

  if (!payload.sub || typeof payload.sub !== "string") {
    throw new InvalidTokenError("missing sub claim");
  }

  return {
    token,
    clientId: (payload.client_id ?? payload.azp ?? "") as string,
    scopes: typeof payload.scope === "string" ? payload.scope.split(" ") : [],
    expiresAt: payload.exp,
    extra: { sub: payload.sub },
  };
}

3. Enforce auth on /mcp

// src/server.ts (continued)
import { requireBearerAuth } from "@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js";
import { verifyAccessToken } from "./auth.js";

server.use(
  "/mcp",
  requireBearerAuth({
    verifier: { verifyAccessToken },
    requiredScopes: ["openid", "email", "profile"], // optional
  }),
);

Unauthenticated requests get HTTP 401 before any tool handler runs.

4. Read auth in handlers

import type { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";

server.registerTool(
  {
    name: "get-orders",
    description: "Get user orders",
  },
  async (_input, extra) => {
    const auth = extra.authInfo as AuthInfo;
    const orders = await fetchOrders(auth.extra?.sub as string);
    return {
      structuredContent: { orders },
      content: [{ type: "text", text: `Found ${orders.length} orders` }],
    };
  },
);

Open external links

• "Open in App" button URL → useSetOpenInAppUrl
• External redirect → useOpenExternal

"Open in App" button

Top right corner in fullscreen mode. Set programmatically. If the origin matches the view server URL, ChatGPT navigates to the full href (any path). If the origin differs, ChatGPT falls back to the view server URL.

Example:

import { useSetOpenInAppUrl } from "skybridge/web";
import { useEffect } from "react";

function ProductDetail({ productId }: { productId: string }) {
  const setOpenInAppUrl = useSetOpenInAppUrl();

  useEffect(() => {
    setOpenInAppUrl(`https://example.com/products/${productId}`).catch(console.error);
  }, [productId]);

  return <div>{/* Product details */}</div>;
}

External redirect

Example:

import { useOpenExternal } from "skybridge/web";

function ExternalLink() {
  const openExternal = useOpenExternal();

  return (
    <button onClick={() => openExternal("https://example.com")}>
      Visit Website
    </button>
  );
}

You can control return-path behavior with an optional second argument (ChatGPT only):

openExternal("https://example.com", { redirectUrl: false });

Use redirectUrl: false to skip automatic ?redirectUrl=... appending.

Shows confirmation dialog unless domain is whitelisted:

// src/server.ts
server.registerTool(
  {
    name: "search-flights",
    description: "Search for flights",
    inputSchema: { destination: z.string(), dates: z.string() },
    view: {
      component: "search-flights",
      description: "Flight results",
      csp: {
        redirectDomains: ["https://airline.example.com"],
      },
    },
  },
  async ({ destination, dates }) => { /* ... */ }
);

Prompt model

Trigger an LLM completion from user interaction with useSendFollowUpMessage.

Example:

import { useSendFollowUpMessage } from "skybridge/web";

export function FindBestFlightButton() {
  const sendMessage = useSendFollowUpMessage();

  return (
    <button onClick={() => sendMessage({
      prompt: "Find the best flight option, based on user preferences and agenda."
    })}>
      Find Best Flight
    </button>
  );
}

Publish to Directories

1. Audit Annotations

Common cause of rejection. Ensure all tools and views have correct annotations. See fetch-and-render-data.md.

2. Audit CSP

Ensure all external domains are declared in the tool's view.csp. See csp.md.

3. Submit

ChatGPT

Guide user to submit the app at platform.openai.com → Apps.

OpenAI verifies app ownership via /.well-known/openai-apps-challenge. Guide user to Alpic Distribution tab → OpenAI Apps Verification Token → paste the token from OpenAI.

Claude

Guide user to submit the app on the Anthropic Connectors Directory FAQ.

Running Locally Workflow

1. Start Dev Server

Install dependencies and start the dev server in the background:

{pm} install && {pm} run dev

For Deno projects, use deno task dev instead.

When started, output the local MCP server and devtools URL.

Hot reload enabled (nodemon for server, HMR for views).

2. Test in DevTools via Chrome DevTools MCP (Optional)

Use the devtools to render views locally. Use this method when iterating with the user on the rendered result of its app.

The devtools page exposes WebMCP tools, powering faster interactions than with traditional click/fill/screenshot interactions. Requires the Chrome DevTools MCP server running with --categoryExperimentalWebmcp=true, which adds the list_webmcp_tools and execute_webmcp_tool tools.

1. navigate_page to the devtools URL output by the dev server 2. list_webmcp_tools to discover the page's tools:

• one tool per app tool — executes it on the local MCP server, returns its result, and renders its view in the preview pane
• devtools_set_view_options — sets any subset of displayMode (inline|pip|fullscreen), darkTheme (boolean), mobileDevice (boolean), locale (BCP 47 code)

3. execute_webmcp_tool with toolName and JSON-stringified input

Interactions inside the rendered view itself are not WebMCP tools, use regular DOM understanding and interactions. Use take_screenshot only to visually verify rendering — screenshot the preview iframe (accessible name html-preview in the page snapshot) rather than the full page.

3. Connect to AI Assistants (Optional)

Ask user if they want to test in ChatGPT/Claude or just use local devtools.

If yes, expose the local server via Alpic tunnel:

alpic tunnel --port 3000

Extract the forwarding URL from Alpic tunnel output (e.g., https://cool-marmot-fondue-420.alpic.dev).

Connect to ChatGPT

Provide the user with these instructions to create the app in ChatGPT: 1. Go to Apps Settings → Create App 2. Enter a name and description for the app 3. Paste this URL: {tunnel-url}/mcp 4. Set the appropriate Authentication scheme. In doubt, pick "No Authentication" 5. Click Create 6. Test by typing @{app-name} in a ChatGPT chat

Troubleshooting:

• 'Create App' button missing: ask user to enable Developer mode in Settings → Apps → Advanced Settings
• 'Create App' button not working: confirm they have ChatGPT Plus, Pro, Business, or Enterprise/Edu plan

Connect to Claude

Provide the user with these instructions to create the app in Claude: 1. Go to Connector Settings → Add Custom Connector 2. Enter a name and URL: {tunnel-url}/mcp 3. Click Create 4. In Claude chat, click the + button and select @{app-name}

Troubleshooting:

• 'Add Custom Connector' button missing: confirm they have a Claude paid plan

Manage View State and LLM Context

• View state (useViewState/createStore) persists and is visible to LLM as structured data.
• data-llm gives LLM context for referential language ("this one").
• React useState is ephemeral and invisible to LLM.

Decision guide:

useViewState

Single component, simple access patterns.

function SeatPicker({ seats }) {
  const [{ selectedSeat }, setState] = useViewState({ selectedSeat: null });

  return (
    <div className="seat-grid">
      {seats.map(seat => (
        <button
          key={seat.id}
          onClick={() => setState((prev) => ({ ...prev, selectedSeat: seat.id }))}
          className={selectedSeat === seat.id ? "selected" : ""}
        >
          {seat.id}
        </button>
      ))}
    </div>
  );
}

Why useViewState: Single component reads selectedSeat to highlight button. View or LLM reads when booking.

createStore

Shared across components, complex mutations. createStore is a thin wrapper around Zustand.

import { createStore } from "skybridge/web";

const useCartStore = createStore<CartState>((set) => ({
  cart: [],
  add: (item) => set((s) => ({ cart: [...s.cart, item] })),
  remove: (id) => set((s) => ({ cart: s.cart.filter(i => i.id !== id) })),
}));

// ProductCard.tsx
function ProductCard({ product }) {
  const add = useCartStore((s) => s.add);
  return <button onClick={() => add(product)}>Add to Cart</button>;
}

// CartSummary.tsx
function CartSummary() {
  const cart = useCartStore((s) => s.cart);
  return <span>{cart.length} items</span>;
}

Why createStore: Cart accessed by multiple components. View or LLM reads items at checkout.

data-llm

Tell the LLM what user is viewing/doing. One-way—view doesn't read it back. These are annotations—don't put complex objects here.

function ProductDetail({ product }) {
  return (
    <div data-llm={`Viewing: ${product.name}, $${product.price}, ${product.inStock ? "in stock" : "out of stock"}`}>
      <h1>{product.name}</h1>
      <p>${product.price}</p>
    </div>
  );
}

Why data-llm: When user asks "Is this one good?" or "Add this to cart", LLM knows what "this" refers to.

Common mistakes

// DON'T: useState is not persisted, LLM can't see it
const [selected, setSelected] = useState(null);

// DO: useViewState persists and LLM sees it
const [{ selected }, setState] = useViewState({ selected: null });

// DON'T: Complex object in data-llm
<div data-llm={JSON.stringify(cart)}>

// DO: Human-readable summary
<div data-llm={`Cart: ${cart.length} items, $${total}`}>

Combined example

Todo list. User checks off tasks, asks "what should I prioritize?"

function TaskList() {
  // PERSIST: All tasks with completed status
  const [{ tasks }, setState] = useViewState({
    tasks: [
      { id: 1, title: "Buy groceries", completed: false },
      { id: 2, title: "Call mom", completed: true },
    ]
  });

  // EPHEMERAL: Task user is viewing — reset on reopen
  const [viewing, setViewing] = useState(null);

  return (
    // CONTEXT: What user is looking at — LLM answers "how should I handle this task?"
    <div data-llm={viewing
      ? `Viewing: "${viewing.title}"`
      : `${tasks.filter(t => !t.completed).length} tasks remaining`
    }>
      {tasks.map(t => (
        <Task
          key={t.id}
          task={t}
          onView={() => setViewing(t)}
          onToggle={() => setState((prev) => ({
            ...prev,
            tasks: prev.tasks.map(task =>
              task.id === t.id ? { ...task, completed: !task.completed } : task
            )
          }))}
        />
      ))}
    </div>
  );
}

Why each?

UI Guidelines

Contents

• Display Modes — inline, fullscreen, PiP, switching
• Modal — overlay on top of any display mode
• Adapting to Host — layout constraints, theme
• Adapting to User — device, locale

Display Modes

Views render inline by default. Add fullscreen and/or PiP when the use case benefits from it—implement triggers (button, gesture) to let users switch.

Inline (default)

View appears embedded in conversation above the model response.

Use for: Single result display, quick actions, browsing items.

Constraints:

• Max 2 CTAs (one primary, one secondary)
• No overflow: scroll/auto—content must fit within available space
• No tabs or deep navigation

Patterns:

• Card — Single-purpose view (order confirmation, weather, status)
• Carousel — 3-8 browsable items with image + title + max 3 lines metadata

Fullscreen

Immersive experience for complex tasks. Host composer remains overlaid at bottom.

Use for: Multi-step workflows, rich editing, explorable content, detailed comparisons.

Constraints:

• Composer overlay always visible at bottom
• User can still chat while in fullscreen

Picture-in-Picture (PiP)

Persistent floating window that stays visible during conversation.

Use for: Live sessions (timers, streams), games, real-time status.

Constraints:

• Must update/respond to user interaction—don't use for static content
• Minimal controls—this is a glanceable surface
• On mobile, PiP coerces to fullscreen

Switching Modes

Use useDisplayMode to read current mode and request changes.

Constraints:

• User-triggered only—never switch programmatically
• Host may reject the request

import { useDisplayMode } from "skybridge/web";

function ExpandableView() {
  const [displayMode, setDisplayMode] = useDisplayMode();
  const isFullscreen = displayMode === "fullscreen";

  if (isFullscreen) {
    return (
      <div className="fullscreen-view">
        {/* Expanded layout */}
        <button onClick={() => setDisplayMode("inline")}>Collapse</button>
      </div>
    );
  }

  return (
    <div className="inline-view">
      {/* Compact layout */}
      <button onClick={() => setDisplayMode("fullscreen")}>Expand</button>
    </div>
  );
}

Modal

Overlay rendered outside the view iframe, on top of the current display mode.

Use for: Confirmations, additional input before an action.

Constraints:

• Triggered by user interaction only
• Host injects close controls

import { useRequestModal } from "skybridge/web";

function SettingsView() {
  const { isOpen, open, params } = useRequestModal();

  if (isOpen) {
    return (
      <div className="modal">
        <h2>Are you sure?</h2>
        <p>This will delete item {params.itemId}</p>
        <button onClick={() => console.log("Confirmed")}>Yes, Delete</button>
        <button onClick={() => console.log("Cancelled")}>Cancel</button>
      </div>
    );
  }

  return (
    <button onClick={() => open({ title: "Confirm", params: { itemId: "123" } })}>
      Delete Item
    </button>
  );
}

Adapting to Host

Use useLayout to read host environment constraints.

Layout Constraints

• maxHeight: Maximum height available for the view in pixels
• safeArea.insets: Padding to avoid device notches, composer overlay, and navigation bars

import { useLayout } from "skybridge/web";

function Container({ children }) {
  const { maxHeight, safeArea } = useLayout();
  const { top, right, bottom, left } = safeArea.insets;

  return (
    <div style={{ maxHeight, padding: `${top}px ${right}px ${bottom}px ${left}px` }}>
      {children}
    </div>
  );
}

Theme

Match the host color scheme using theme from useLayout.

import { useLayout } from "skybridge/web";

function Container({ children }) {
  const { theme } = useLayout();
  const isDark = theme === "dark";

  return <div className={isDark ? "bg-surface-dark" : "bg-surface-light"}>{children}</div>;
}

Adapting to User

Use useUser to read user context.

Device

• device.type: "mobile" | "tablet" | "desktop" | "unknown"
• capabilities.hover: true if device supports hover (mouse)
• capabilities.touch: true if device supports touch

import { useUser } from "skybridge/web";

function ProductCard({ product }) {
  const { userAgent } = useUser();
  const { device, capabilities } = userAgent;

  return (
    <div className={capabilities.hover ? "hover:shadow-lg" : ""}>
      <img src={product.image} alt={product.name} />
      <h3>{product.name}</h3>
      {device.type === "mobile" && <button>Add to Cart</button>}
      {capabilities.touch && <p className="hint">Swipe for more</p>}
    </div>
  );
}

Locale

Use locale from useUser to adapt content to user's language.

import { useUser } from "skybridge/web";

function LocalizedGreeting() {
  const { locale } = useUser();

  const greetings = {
    en: "Hello!",
    fr: "Bonjour!",
    zh: "你好!",
  };

  const language = locale.split("-")[0];
  const greeting = greetings[language] || greetings.en;

  return <h1>{greeting}</h1>;
}