Create Views

Craft interactive UIs rendered in conversation

Views are the face of your app: UI components the host mounts inline when the tool they’re bound to returns. A view reads what the tool produced, calls tools back when the user acts, and manages the state shared with the model. It’s plain React, running in a sandboxed iframe inside the host.

Here’s a complete view, the carousel mounted by search-products, next to a minimal version of the tools it talks to:

views/carousel.tsx

import { useCallTool, useToolInfo } from "../helpers.js"; // generated, type-safe from server schema

export default function Carousel() {
  const { input, output, responseMetadata, isPending } = useToolInfo<"search-products">();
  const { callTool: checkout, isPending: isCheckingOut, isSuccess: hasCheckedOut, data } = useCallTool("create-checkout");

  if (isPending) {
    return <SearchSkeleton query={input?.query} />;
  }

  if (hasCheckedOut) {
    return <a href={data.structuredContent.url}>Pay now</a>;
  }

  return (
    <ProductGrid
      products={output.products}
      images={responseMetadata.images}
      disabled={isCheckingOut}
      onCheckout={(ids) => checkout({ productIds: ids })}
    />
  );
}

The sections below walk through it: the component itself, reading the tool, calling tools back, the typed helpers binding views to the server, matching the host’s styles, and opening the sandbox to external domains.

The Component

A view is a .tsx file with a default-exported React component in views/. The binding happens when you register the tool:

server.ts

server.registerTool(
  {
    name: "search-products",
    description: "Show products matching a query in a carousel.",
    inputSchema: { query: z.string() },
    view: { component: "carousel" }, // resolves to views/carousel.tsx
  },
  async ({ query }) => {
    /* … */
  },
);

Beyond that, it’s regular React: hooks, sub-components, any library you like. Each tool call mounts a fresh instance in a sandboxed iframe, so think in instances, not singletons: two carousels in one conversation are two separate mounts.

Read the Tool Call

The host mounts the view as soon as the model calls the tool, often before your handler returns. useToolInfo tracks that lifecycle: status moves from "pending" to "success", with isPending and isSuccess as shortcuts.

views/carousel.tsx

import { useToolInfo } from "../helpers.js"; // generated, type-safe from server schema

export default function Carousel() {
  const { input, output, responseMetadata, isPending } = useToolInfo<"search-products">();

  if (isPending) {
    return <SearchSkeleton query={input?.query} />;
  }

  return (
    <ProductGrid
      products={output.products}
      images={responseMetadata.images}
    />
  );
}

The rest of the hook is the exchange itself: what the model sent in, and the two halves of what your handler sent back:

• input: the tool call arguments, validated
• output: the response structuredContent, also surfaced to the model
• responseMetadata: the response _meta, not surfaced to the model

Call Tools Back

useCallTool lets the view call any tool on your server without involving the model. It returns the trigger and the mutation state:

views/carousel.tsx

import { useCallTool, useToolInfo } from "../helpers.js"; // generated, type-safe from server schema

export default function Carousel() {
  const { input, output, responseMetadata, isPending } = useToolInfo<"search-products">();
  const { callTool: checkout, isPending: isCheckingOut, isSuccess: hasCheckedOut, data } = useCallTool("create-checkout");

  if (isPending) {
    return <SearchSkeleton query={input?.query} />;
  }

  if (hasCheckedOut) {
    return <a href={data.structuredContent.url}>Pay now</a>;
  }

  return (
    <ProductGrid
      products={output.products}
      images={responseMetadata.images}
      disabled={isCheckingOut}
      onCheckout={(ids) => checkout({ productIds: ids })}
    />
  );
}

status runs idle, pending, then success (read the result on data) or error.

Tool calls initiated from a view happen outside the conversation: the model sees neither the call nor its result, and no view gets mounted. The response goes to the calling view alone.

Generate Type-Safe Hooks

The hooks above aren’t imported from skybridge/web directly: they come from helpers.ts, a bridge file that infers every type from your server. Projects scaffolded with npx skybridge create include it out of the box:

helpers.ts

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

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

Import useToolInfo and useCallTool from helpers.ts everywhere, and you get autocomplete on tool names, plus typed inputs, outputs, and metadata on both hooks.

Type-safe hooks are generated using generateHelpers.

Match the Host Styles

A view feels native when it borrows the host’s own look: its palette, typography, and light or dark theme. On the MCP Apps runtime, hosts like Claude can hand your view a set of design tokens for exactly this. Opt in with the hostStyles option on the Vite plugin:

vite.config.ts

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { skybridge } from "skybridge/vite";

export default defineConfig({
  plugins: [react(), skybridge({ hostStyles: true })],
});

With it on, Skybridge applies whatever the host provides, and keeps it in sync when the user toggles their theme:

• CSS variables on :root, a standardized set you reference with var(…), covering colors (--color-background-primary, --color-text-primary, --color-border-primary, and info / danger / success / warning variants), typography (--font-sans, --font-mono, --font-weight-medium, --font-text-md-size…), radii (--border-radius-sm … --border-radius-full), and shadows (--shadow-sm … --shadow-lg).
• color-scheme on the document, so the host’s light-dark() color values resolve to the right branch and native controls (scrollbars, form fields) match the theme.
• Fonts the host ships, injected so var(--font-sans) renders in the host’s typeface.

views/carousel.tsx

export default function ProductCard({ product }) {
  return (
    <div
      style={{
        background: "var(--color-background-primary)",
        color: "var(--color-text-primary)",
        border: "1px solid var(--color-border-primary)",
        borderRadius: "var(--border-radius-lg)",
        boxShadow: "var(--shadow-md)",
        fontFamily: "var(--font-sans)",
      }}
    >
      {product.name}
    </div>
  );
}

hostStyles is off by default. Turning it on lets the host set those variables on :root and flip color-scheme, restyling your view. Because the variables are applied inline on the document root, a :root { --color-text-primary: … } of your own is overridden by the host’s value; scope your overrides below the root (on a wrapper element) if you need them to win. Opt in once your view is ready to inherit the host’s styling.

Host styles are an MCP Apps feature. Under the ChatGPT Apps SDK runtime the host sends no tokens, so the option is a no-op there, and not every MCP host provides a full set. Read the current theme directly with useLayout when you need to branch in code.

Open the Sandbox

The iframe ships with a strict Content Security Policy: your server’s domain is allowed automatically, and everything else is blocked. If the view fetches from an external API or loads assets from the outside world, declare the domains on the view config, server side:

server.ts

server.registerTool(
  {
    name: "search-products",
    description: "Show products matching a query in a carousel.",
    inputSchema: { query: z.string() },
    view: {
      component: "carousel",
      csp: {
        connectDomains: ["https://api.myshop.com"],   // fetch / XHR targets
        resourceDomains: ["https://cdn.myshop.com"],  // images, fonts, scripts
      },
    },
  },
  async ({ query }) => {
    /* … */
  },
);

frameDomains (embedded iframes) and redirectDomains (external redirects) follow the same pattern. See Configure CSP for the full walkthrough.

All done!

You now know how to create views. Learn what the view holds between tool calls, and who sees it, in the next chapter.

Go Further

Register Tools

Define what humans and agents can do

Manage State

Decide what the model sees

Authenticate Users

Know who’s behind every tool call