` | Server-level MCP instructions preset (the string injected into the LLM’s system prompt above the tool catalog). Presets: `default`, `aggressive`, `always`, `minimal`, `off`. Also accepts `GGUI_MCP_INSTRUCTIONS` env (CLI flag wins). | ## Agent runtime supervision [Section titled “Agent runtime supervision”](#agent-runtime-supervision) By default, `ggui serve` boots your agent alongside MCP. The entry file comes from `ggui.json`: ```json { "agent": { "entry": "./agent.ts" } } ``` Supported extensions: * `.js` / `.mjs` / `.cjs` — runs as `node ` * `.ts` / `.tsx` / `.mts` — runs as `node --import=tsx ` (`tsx` must be resolvable in your project) Failure modes: * **No `ggui.json`** or **no `agent.entry`** — falls back to MCP-only with a warning. Useful when you want to point an external agent runtime at the server. * **Malformed `ggui.json`** or **unsupported entry extension** — hard error, exits 1 before binding. * **Agent crashes after startup** — logged, MCP keeps running. No auto-restart — compose that with your own supervisor (systemd, pm2, Docker restart policy). ## Generation (bring your own key) [Section titled “Generation (bring your own key)”](#generation-bring-your-own-key) Component-code generation on a self-hosted server uses **your** LLM provider key (BYOK). At boot, `ggui serve` resolves a key in this order: 1. **Provider env vars** — `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_API_KEY` (falling back to `GEMINI_API_KEY`), `OPENROUTER_API_KEY`. The env layer always wins. 2. **`~/.ggui/credentials.json`** — keys pasted at `/settings` land here (plaintext, `0600`). The model comes from `ggui.json#generation.model`, in either `provider:model` (canonical) or `provider/model` (LiteLLM) form: ```json { "generation": { "model": "anthropic:claude-haiku-4-5-20251001" } } ``` `GGUI_GENERATION_MODEL` env overrides the manifest model — the precedence is **`GGUI_GENERATION_MODEL` env > `ggui.json#generation.model` > per-provider default**. The env value accepts both `provider:model` (canonical) and `provider/model` (LiteLLM) forms; a malformed value is a hard boot error, not a silent fallback. It’s the ops escape hatch for pointing one `ggui serve` instance at a different model without editing the manifest. When neither env nor manifest sets a model, the per-provider default applies (anthropic `claude-haiku-4-5`, openai `gpt-5.5-2026-04-23`, google `gemini-3.1-flash-lite`). Rules: * **A key without a model is a hard error** — if a boot key resolves but `generation.model` is unset, `ggui serve` exits with an actionable message showing both accepted model-string forms. * **Bedrock routes are rejected** on the OSS path (IAM-only; supported via the hosted runtime only). * **No key at all is not fatal** — the banner prints `⚠ no LLM key configured`, and renders fall back to a Connect-a-key card pointing at `/settings`. Pasting a key there takes effect without a restart. ## Persistent storage [Section titled “Persistent storage”](#persistent-storage) By default, `ggui serve` writes a cross-restart bundle under `.ggui/persistent/` (project-local when a `ggui.json` was resolved, else `~/.ggui/persistent/`) so HMAC secrets, renders, vectors, short-codes, and paired bearers survive a restart. claude.ai chat-history revisits keep working without re-pairing. Bundle layout: ```text .ggui/persistent/ ├── ws-token-secret.hex (HMAC, 0600) ├── render-signer-secret.hex (HMAC, 0600) ├── short-codes.sqlite (signed render-URL resolution — backs the /r/ viewer) ├── sessions.sqlite (GguiSessionStore — renders + event history) ├── vectors.sqlite (RAG corpus) └── keys.json (paired bearers) ``` Override the directory with `GGUI_PERSISTENT_DIR`. Pass [`--ephemeral`](#operator-config) to skip the bundle entirely. Explicit `ggui.json#storage` declarations always win. Declare them to override paths or swap a single surface back to memory while keeping the rest persistent: ```json { "storage": { "renders": { "driver": "sqlite", "path": "./ggui-sessions.sqlite" }, "vectors": { "driver": "sqlite", "path": "./ggui-vectors.sqlite" }, "threads": { "driver": "sqlite", "path": "./ggui-threads.sqlite" } } } ``` | Store | Default | sqlite driver requires | | --------- | -------------------------------------------------------------------------------------------------------- | ------------------------- | | `renders` | sqlite under `.ggui/persistent/sessions.sqlite` (opt out with `--ephemeral` or `{ "driver": "memory" }`) | `better-sqlite3` peer dep | | `vectors` | sqlite under `.ggui/persistent/vectors.sqlite` (opt out with `--ephemeral` or `{ "driver": "memory" }`) | `better-sqlite3` peer dep | | `threads` | **routes unmounted unless declared** (opt-in) | `better-sqlite3` peer dep | Paths in `ggui.json#storage` resolve relative to the `ggui.json` directory, regardless of where `ggui serve` was invoked from. For threads specifically, `driver: "memory"` mounts the routes but data resets on restart (`/ggui/health` reports `threads.durability: "ephemeral"`); `driver: "sqlite"` is durable. ## Recommended setups [Section titled “Recommended setups”](#recommended-setups) **Local-only smoke (no tunnel, no remote MCP host):** ```bash ggui serve ``` **claude.ai custom connector (over a public tunnel):** ```bash # Terminal 1: tunnel cloudflared tunnel --url http://localhost:6781 # Terminal 2: serve ggui serve --oauth \ --public-base-url https://.trycloudflare.com ``` Note the `PAIR_CODE` from the boot banner. Visit the public URL, complete pairing, save the bearer. Then in claude.ai → Settings → Connectors → Add custom connector, point it at `https://.trycloudflare.com/mcp`, leave Client ID / Secret empty (the server uses Dynamic Client Registration), click Connect, and paste the bearer when prompted. **Quick local-dev without auth (NEVER over a public tunnel):** ```bash ggui serve --dev-allow-all ``` For the full pairing walkthrough, see [Self-hosted pairing](/self-hosted/pairing/). ## Production hardening [Section titled “Production hardening”](#production-hardening) The default auth shape is dev-mode pairing. For production, swap in a real `AuthAdapter` by composing `createGguiServer()` directly in your agent entrypoint instead of running the CLI: ```typescript import { createGguiServer } from "@ggui-ai/mcp-server"; const server = createGguiServer({ auth: { /* your AuthAdapter — OIDC, Cognito, custom */ }, }); ``` The adapter gates both `/mcp` and the live-channel `/ws` upgrade. See [Reference deploys](/self-hosted/reference-deploys/) for Docker / Fly / Render manifests. ## Current limits [Section titled “Current limits”](#current-limits) * Strict-auth only — `/mcp` rejects any bearer not pair-minted (or relaxed via `--dev-allow-all` / `--public-demo`). * Single-tenant by default — every request scopes to one `builder` app ID. Use `--multi-tenant` to scope per authenticated user. * No auto-restart on agent crash — compose with your own supervisor. ## See also [Section titled “See also”](#see-also) * [`ggui` CLI overview](/cli/) — the full command surface. * [`ggui login`](/cli/login/) — sign into `api.ggui.ai` for `ggui_user_*` connector keys *(Preview — managed cloud, coming soon; separate from `ggui serve`’s pairing flow)*. * [Self-hosted pairing](/self-hosted/pairing/) — pair a viewer client to a `ggui serve` instance. * [Reference deploys](/self-hosted/reference-deploys/) — Docker, Fly, Render manifests for `ggui serve`. # Connect Claude Desktop > Connect Claude Desktop to a ggui server over MCP with OAuth and render generative UI inline. `mcp.ggui.ai` speaks the [MCP Apps](/api/mcp-apps/) protocol, so any MCP-Apps-aware host renders ggui-generated UIs inline. Claude Desktop is the most polished client today; this page walks install and first use end to end. The same procedure works for **claude.ai**, **Goose**, and **VS Code Copilot** — anywhere you can add a remote MCP server and the host implements OAuth 2.1 + Dynamic Client Registration. See [Other clients](#other-clients). ## Available now: connect your own server [Section titled “Available now: connect your own server”](#available-now-connect-your-own-server) The hosted `mcp.ggui.ai` endpoint is part of the managed cloud (Preview — coming soon). The identical “Add custom connector” flow already works against a self-hosted server today: 1. Run your server with OAuth enabled, on a URL Claude’s browser can reach: ```bash ggui serve --oauth --public-base-url https:// ``` 2. In Claude Desktop, **Settings → Connectors → Add custom connector**, paste `https:///mcp`. 3. On first use the consent page asks you to paste a locally-minted `ggui_user_*` key — that key becomes the OAuth access token. See [CLI: serve](/cli/serve/) for the flags and [Pairing](/self-hosted/pairing/) for minting keys. ## Step 1: Add the server [Section titled “Step 1: Add the server”](#step-1-add-the-server) In Claude Desktop, open **Settings → Connectors → Add custom connector** and paste: ```plaintext https://mcp.ggui.ai ``` Leave authentication blank — the server drives Claude through the OAuth ceremony on first use. Save. ## Step 2: Approve the connection [Section titled “Step 2: Approve the connection”](#step-2-approve-the-connection) The first time Claude calls a ggui tool (or you click **Connect** on the connector card), Claude pops a browser window to `console.ggui.ai/oauth/consent`. 1. Sign in to ggui (email + password — same account that holds your connector keys). 2. Click **Approve** on the consent card. The console mints a fresh `ggui_user_*` API key labelled `Claude Desktop` and hands it to the client through the OAuth flow. 3. The browser closes. Claude shows the connector as connected. Under the hood, no manual `client_id` to copy: * Auth-server discovery via [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) (`/.well-known/oauth-protected-resource`) and [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414). * Client registration via [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591) Dynamic Client Registration. * [OAuth 2.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1) + [PKCE](https://datatracker.ietf.org/doc/html/rfc7636); the `ggui_user_*` key becomes the access token. Full protocol details: [OAuth on mcp.ggui.ai](/api/oauth/). ## Step 3: Generate a UI [Section titled “Step 3: Generate a UI”](#step-3-generate-a-ui) In a new chat, ask Claude to do something concrete enough to need a form: > Help me triage 12 incoming product-support tickets. Show me a sortable table with severity, age, and a “draft reply” action per row. Claude calls the `ggui_render` tool with that intent. The MCP Apps capability advertised by `mcp.ggui.ai` tells Claude Desktop to render the result inline — the table appears directly in the chat, not as an external link. Submit a row and the data flows back to Claude as if you’d typed it. The first such call also seeds a blueprint cache: subsequent matching requests skip the generation step and return the cached gadget instantly. ## Tool-call budget and credits [Section titled “Tool-call budget and credits”](#tool-call-budget-and-credits) Each `ggui_render` burns a small amount of credit (LLM time + render storage). New accounts get **$5 free credit** out of the gate; top up at [`console.ggui.ai/credits`](https://console.ggui.ai/credits) when you run low. Prefer your own model account? Paste a provider key into [`console.ggui.ai/keys/providers`](https://console.ggui.ai/keys/providers) (BYOK — Anthropic, OpenAI, Google, OpenRouter). When a BYOK key is on file for the model the request would have used, ggui calls the model on your tab and only charges for orchestration. ## Revoke the connection [Section titled “Revoke the connection”](#revoke-the-connection) Two surfaces, both authoritative: * **Claude Desktop** — Settings → Connectors → ggui → **Disconnect**. Drops the cached token locally; the underlying API key on the ggui side is unaffected. * **console.ggui.ai** — on the home page, find the key labelled `Claude Desktop` (or whatever the client called itself) and click **Revoke**. The next request from any client holding that token returns `401`. The keys table at [`console.ggui.ai/keys/connector`](https://console.ggui.ai/keys/connector) is the authoritative revocation surface — every MCP-Apps client lands as one row, labelled with its DCR `client_name`. (A dedicated **Connected apps** view at `/connections` is a placeholder today; the keys table is what to use.) ## Other clients [Section titled “Other clients”](#other-clients) The same `mcp.ggui.ai` URL works in any host that ships MCP Apps + OAuth-DCR: * **claude.ai (web)** — Settings → Connectors → Add custom connector. Same flow, browser-only. * **Goose** — `goose configure`, then add a remote MCP server pointing at `https://mcp.ggui.ai`. * **VS Code Copilot** — drop into `.vscode/mcp.json`: `{ "servers": { "ggui": { "type": "http", "url": "https://mcp.ggui.ai" } } }`. Copilot triggers OAuth on first tool call. * **Anything that speaks RFC 7591 + RFC 9728** — drop the URL in; the server’s discovery metadata bootstraps the rest. Hosts that don’t speak MCP Apps yet (most CLI agents at time of writing) can still hit the endpoint with a static `Authorization: Bearer ggui_user_*` header. They lose inline rendering — `ggui_render` still works and returns the render as a `ui://ggui/render/` resource, but without MCP-Apps support there’s nothing to mount it (the agent receives no URL to open). ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) **“Failed to connect” after approving** — stale token cache. Disconnect from Claude Desktop’s connector panel and reconnect; OAuth re-runs and mints a fresh key. **OAuth browser window never opens, or closes with an error** — most often a popup blocker on `console.ggui.ai`, or you were already signed into a different ggui account in that browser profile. Allow popups for `console.ggui.ai`, sign out of the wrong account, and click **Connect** on the connector card again to restart the ceremony. To inspect what was minted, open [`console.ggui.ai/keys/connector`](https://console.ggui.ai/keys/connector) — a successful ceremony shows up as a new row labelled with the client name. **“This MCP server has not been activated”** — your account has zero credits and no BYOK key on file. Top up at [`console.ggui.ai/credits`](https://console.ggui.ai/credits) or paste a provider key into [`console.ggui.ai/keys/providers`](https://console.ggui.ai/keys/providers). **No inline rendering, only a link** — the host doesn’t advertise MCP Apps capability. Upgrade to a current Claude Desktop build (MCP Apps support shipped late 2025) or open the link manually; the underlying session works either way. **Anything else** — see [Troubleshooting](/troubleshooting/). # Connect other MCP hosts > Wire Cursor, VS Code Copilot, claude.ai, Goose, Cline, Continue, or Windsurf into a ggui server over MCP HTTP. A ggui server is a plain remote MCP server. Any host that can be pointed at an MCP HTTP URL can use it — Claude Desktop is just the most polished today. This page is the “everything else” companion to [Connect Claude Desktop](/clients/claude-desktop/), which stays the deep-dive for that one client. Each section below covers WHAT to paste, WHERE to paste it, the expected OAuth flow, and any inline-rendering caveat. If your host isn’t listed but speaks MCP over HTTP, jump to [Other / static-key fallback](#other--static-key-fallback). ## claude.ai (web) [Section titled “claude.ai (web)”](#claudeai-web) Anthropic’s web client gained MCP Apps support late 2025; the flow mirrors Claude Desktop exactly. 1. **Settings → Connectors → Add custom connector**. 2. Paste `https://mcp.ggui.ai`. Leave auth blank. 3. On first tool call, claude.ai opens an OAuth tab to `console.ggui.ai/oauth/consent`. Approve. Inline rendering works — generated UIs appear directly in the chat. ## Cursor [Section titled “Cursor”](#cursor) Cursor reads MCP server config from `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per-project, takes precedence). ```json { "mcpServers": { "ggui": { "url": "https://mcp.ggui.ai" } } } ``` Restart Cursor. The first time the agent calls a ggui tool, Cursor opens the browser OAuth flow. Approve at `console.ggui.ai/oauth/consent` and the agent picks up the minted token automatically. Caution Cursor’s MCP Apps inline-rendering support is partial and moves quickly — verify against your installed build. If your build doesn’t render inline, the tool call still succeeds and returns a `ui://ggui/render/` resource, but there is no URL to open manually — the session round-trip works, the UI just can’t be mounted. ## VS Code Copilot (and Cline, Continue, Codeium) [Section titled “VS Code Copilot (and Cline, Continue, Codeium)”](#vs-code-copilot-and-cline-continue-codeium) VS Code’s native MCP support shipped in 2025. Drop into either `.vscode/mcp.json` (per-project) or your User Settings JSON: ```json { "servers": { "ggui": { "type": "http", "url": "https://mcp.ggui.ai" } } } ``` Reload the window. Copilot triggers OAuth on first tool call. **Cline**, **Continue**, and **Codeium** are VS Code extensions that ship their own MCP config surfaces. The JSON shape is the same `mcpServers`-style object with minor key naming differences per extension — drop the same URL into whichever `mcp.json` the extension reads: * **Cline** — extension settings → MCP Servers → Edit config. * **Continue** — `~/.continue/config.json` under `mcpServers`. * **Codeium** — extension settings → MCP integration. Consult each extension’s docs for the exact path; the URL itself is unchanged. ## Goose [Section titled “Goose”](#goose) Block’s open-source agent has full MCP Apps support, so inline rendering works in the Goose Desktop UI out of the box. ```plaintext goose configure ``` Choose **Add extension → Remote MCP Server**, give it a name (`ggui`), and paste: ```plaintext https://mcp.ggui.ai ``` Goose drives the OAuth ceremony in the terminal flow — it prints a URL, you sign in at `console.ggui.ai`, and Goose stores the resulting token. ## Windsurf [Section titled “Windsurf”](#windsurf) Codeium’s IDE supports remote MCP servers via Settings → MCP Servers → Add. Paste `https://mcp.ggui.ai` and save; OAuth runs on first tool call. The config-file location varies by OS and Windsurf build. Settings UI is the safest path. Caution Verify against your current Windsurf build — MCP Apps capability advertisement and inline-rendering behavior have changed across releases. ## Other / static-key fallback [Section titled “Other / static-key fallback”](#other--static-key-fallback) Any host that can be pointed at an MCP HTTP URL with a bearer token can hit `mcp.ggui.ai`. For hosts that don’t yet implement OAuth 2.1 + DCR — most CLI agents and home-grown clients — use a static API key instead: 1. Sign in at [`console.ggui.ai/keys/connector`](https://console.ggui.ai/keys/connector). 2. Click **Mint**. Label it after the client. 3. Configure the host to send the key as a bearer header: ```plaintext Authorization: Bearer ggui_user_xxxxxxxxxxxx ``` That’s the full setup. See [`ggui keys create`](/cli/login/#manage-keys) for minting a connector key from the terminal instead of the console. ## Things every host needs [Section titled “Things every host needs”](#things-every-host-needs) Everything on this page also works against a self-hosted `ggui serve` — substitute your server URL; add `--oauth` for hosts that drive the browser ceremony, or use a pair-minted bearer for the static-key path. For a working connection: * **MCP over HTTP** — `mcp.ggui.ai` is HTTP-only. Stdio-only hosts can’t connect directly. * **Bearer authentication** — either via the OAuth flow below, or a static `ggui_user_*` key in an `Authorization` header. For the seamless one-click flow: * **OAuth 2.1 + Dynamic Client Registration** ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591), [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414), [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728), [PKCE](https://datatracker.ietf.org/doc/html/rfc7636)). The host discovers, registers, and exchanges tokens with zero manual `client_id` paste. Details: [OAuth on mcp.ggui.ai](/api/oauth/). For inline rendering: * **MCP Apps capability** — the host advertises that it can render `ui://` resources in-line. Without it, the render is still produced (as a `ui://ggui/render/` resource) but can’t be mounted; with it, generated UIs appear inside the chat or agent surface. Details: [MCP Apps capability](/api/mcp-apps/). Anything else: see [Troubleshooting](/troubleshooting/). # console.ggui.ai > User dashboard for the hosted mcp.ggui.ai server — apps, orgs, connector keys, blueprints, credits, BYOK provider keys, and OAuth/CLI consent. Coming soon This page describes the **managed hosted path** (`mcp.ggui.ai` / `console.ggui.ai`), which is **not yet live** — it is not part of GGUI Preview 0.1.0. The self-hosted path is available today — start with the [Quickstart](/oss-quickstart/). This page is kept as a preview of the managed path and goes live when hosted ggui ships. [`console.ggui.ai`](https://console.ggui.ai) is the user-facing dashboard for the [`mcp.ggui.ai`](/clients/claude-desktop/) hosted MCP server. Sign in with email + password (Cognito). The left-sidebar nav surfaces seven top-level screens; three more screens are deep-linked into by the OAuth ceremony, the CLI device flow, and org-invite emails. | Screen | Path | What lives here | | -------------- | --------------------- | ---------------------------------------------------------------------- | | Apps | `/apps` | Per-app surfaces — keys, blueprints, theme, marketplace, settings. | | Orgs | `/orgs` | Organizations you belong to; org-scoped wallets, invites, members. | | Connector keys | `/keys/connector` | Mint, list, and revoke `ggui_user_*` API keys. | | Connected apps | `/connections` | OAuth clients that have access to your account (placeholder today). | | Credits | `/credits` | Balance, transaction log, coupon redeem. (Stripe top-up: coming soon.) | | Provider keys | `/keys/providers` | BYOK — paste your Anthropic / OpenAI / Google / OpenRouter keys. | | Account | `/account` | Email, default app, sign out. | | OAuth consent | `/oauth/consent` | Approval landing for MCP-Apps-aware clients (Claude Desktop, etc.). | | CLI sign-in | `/cli-confirm/[code]` | Approval landing for the [`ggui` CLI’s](/cli/login/) device flow. | | Org invite | `/invites/[inviteId]` | Auto-accept landing for an org-invite email link. | The home path `/` redirects to `/apps` — apps are the primary primitive in the current IA (post-2026-05 apps pivot). You don’t visit `/oauth/consent` or `/cli-confirm/*` directly — the MCP host or the CLI navigates you there at the right moment. ## Apps (`/apps`) [Section titled “Apps (/apps)”](#apps-apps) Apps are the primary primitive. Each app is a scope that owns its own blueprints, theme, marketplace installs, and per-app API keys. New accounts land here with a single default app already provisioned; create more from this page. Per-app sub-routes (under `/apps/[appId]/`): * **Keys** (`/keys`) — per-app connector keys (`ggui_user_*` rows bound to this `appId`, so the pod locks the session to this app) **and** per-app BYOK provider-key overrides (precedence over the user-pool BYOK keys for renders bound to this app). * **Blueprints** (`/blueprints`) — the app’s blueprint library: view source, rename, edit metadata, delete. * **Marketplace** (`/marketplace`) — browse + install published blueprints. * **Theme** (`/theme`) — per-app theme overrides. * **Settings** (`/settings`) — app-level config. Blueprints are matched during `ggui_handshake`, before any generation. Curated app blueprints match deterministically when the agent’s declared tools cover the blueprint’s `dataTools` (instant, zero-LLM); other cached blueprints are reused by contract similarity. Either way, a hit renders with zero generation cost. See the [generation pipeline](/architecture/overview/#generation-pipeline) for the matching flow and [Marketplace](/sdk/marketplace/) for authoring + distribution. ## Orgs (`/orgs`) [Section titled “Orgs (/orgs)”](#orgs-orgs) Organizations you belong to. Each org has its own credit wallet, member list, and invite flow. Coupons can be redeemed into an org wallet from the Credits page (next section). Per-org detail lives under `/orgs/[orgId]`. Invite-email links land at `/invites/[inviteId]` and auto-accept once you’re signed in (lookup is by Cognito email, so a newly-signed-up invitee sees every pending invite at `/invites`). Org-scoped agent infrastructure (production hosting, shared dashboards) is the domain of the separate **guuey** platform — same protocol underneath. ## Connector keys (`/keys/connector`) [Section titled “Connector keys (/keys/connector)”](#connector-keys-keysconnector) The connector-keys table. One row per active key: prefix, name, status, last-used timestamp, **Revoke** action. **Mint** opens a dialog with one optional field (a friendly label). Submit, the key reveals exactly once — copy it before dismissing the dialog. Lose it and you mint a new one; there’s no recovery. Every authentication path lands here as one row: * The console UI mint dialog → row labelled whatever you typed. * An OAuth ceremony from Claude Desktop / claude.ai / Goose / VS Code → row labelled `MCP — — ` by default (with an ` — `prefix when the host requested per-app scope via RFC 8707 `resource`); the consent screen’s optional **Key name** field overrides the default before approval. * The [`ggui keys create`](/cli/login/#manage-keys) CLI command → row labelled with whatever `--name` you passed. This unification is deliberate. The keys list IS the authoritative list of “things that can talk to ggui as you” — there’s no separate “connected clients” surface. Revoke a row and the corresponding client’s next request returns `401`. ## Connected apps (`/connections`) [Section titled “Connected apps (/connections)”](#connected-apps-connections) OAuth clients (Claude Desktop, claude.ai, Goose, …) that have registered against your account via Dynamic Client Registration. Currently a placeholder — the full client list + per-row revoke is planned. For now, run the in-Claude `ggui_status` tool to see connected apps from inside your MCP host. ## Credits (`/credits`) [Section titled “Credits (/credits)”](#credits-credits) Balance, transaction log, and coupon redemption. New accounts get **$5 of free credit** (Anthropic-pool) on first sign-in. Each `ggui_render` burns credit proportional to the LLM call (prompt tokens × model rate) plus a small render-storage allocation. Blueprint-matched renders skip the LLM and cost \~nothing. The transaction log shows every charge with model + token breakdown. **Top up:** the button is present but currently disabled with a “coming soon” badge — Stripe top-up is post-launch. Until then, top up via the **Redeem coupon** card (codes can be applied to your personal wallet or to any org wallet you’re a member of). To bypass the credit pool entirely, paste a **provider key** at `/keys/providers` (next section). When a BYOK key is on file for the model the request would have used, ggui calls the model on your tab and only charges credit for orchestration overhead. ## Provider keys / BYOK (`/keys/providers`) [Section titled “Provider keys / BYOK (/keys/providers)”](#provider-keys--byok-keysproviders) Paste your own provider API keys to bypass the credit pool for model calls. The four supported providers, with the get-a-key link the dialog surfaces: * **Anthropic** — Claude models. Get a key at `console.anthropic.com` → Settings → API Keys. * **OpenAI** — GPT models. Get a key at `platform.openai.com` → API Keys. * **Google** — Gemini models. Get a key at `aistudio.google.com` → Get API key. * **OpenRouter** — multi-provider routing. Get a key at `openrouter.ai` → Settings → Keys. Keys are KMS-encrypted at rest and only decrypted in-memory in the per-request Lambda. The console only ever shows the key prefix once it’s been saved — submit the form once, the plaintext is consumed. Resolution at request time is per-provider: Anthropic call → check Anthropic BYOK key → if present, use it; if not, fall back to credit pool. Mixing is fine — you can BYOK Anthropic and pay-as-you-go for everything else. Revoke at any time. The next request that would have used the key falls back to the credit pool. ## Account (`/account`) [Section titled “Account (/account)”](#account-account) Email, default app selection (used by legacy redirects like `/blueprints` → `/apps/{defaultAppId}/blueprints`), and sign out. ## OAuth consent (`/oauth/consent`) [Section titled “OAuth consent (/oauth/consent)”](#oauth-consent-oauthconsent) The browser landing for MCP-Apps-aware clients running through the [OAuth ceremony](/api/oauth/). When Claude Desktop (or any compatible host) asks `mcp.ggui.ai` to authorize, the server 302s the browser here with the OAuth params. You see: * The requesting client’s name (from DCR `client_name`). * The scope being requested (`mcp`). * Two buttons: **Approve** / **Cancel**. **Approve** mints a fresh `ggui_user_*` key (default label `MCP — — `, editable via the Key-name field; per-app flows that carried an RFC 8707 `resource` get the `appId` bound on the row so the session locks to that app) and posts it back to the MCP server through a cross-origin form POST. The server completes the OAuth flow and the client’s next `/mcp` request authenticates with the new key. **Cancel** redirects back to the client with `error=access_denied` per [RFC 6749 §4.1.2.1](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1). The MCP server is never contacted; nothing is minted. You don’t visit this URL directly — the MCP host sends you here at OAuth time. ## CLI sign-in (`/cli-confirm/[user_code]`) [Section titled “CLI sign-in (/cli-confirm/\[user\_code\])”](#cli-sign-in-cli-confirmuser_code) The browser landing for the [`ggui login`](/cli/login/) device flow. The CLI prints a URL like: ```plaintext https://console.ggui.ai/cli-confirm/AB12-CD34 ``` Open it, sign in if you aren’t already, confirm the codes match, click **Approve**. The CLI’s polling on `/v1/auth/poll` flips to `approved` and tokens land at `~/.ggui/auth.json`. Same trust model as the OAuth consent screen — confirm the code matches what the CLI printed before approving. ## Account model [Section titled “Account model”](#account-model) One Cognito user owns one ggui account. User-scoped data on the dashboard (your keys, your blueprints, your personal credit balance, your provider keys) is visible only to you via owner-auth on every model. Org-scoped data (org wallet, org members, org-scoped blueprints) is gated by org membership. # Million-Dollar Homepage playground > Hosted MCP service at mcp.ggui.ai/playground/mdh — shared 1000×1000 pixel grid. Demo of generative UI rendering globally shared mutable state. Coming soon This page describes the **managed hosted path** (`mcp.ggui.ai` / `console.ggui.ai`), which is **not yet live** — it is not part of GGUI Preview 0.1.0. The self-hosted path is available today — start with the [Quickstart](/oss-quickstart/). This page is kept as a preview of the managed path and goes live when hosted ggui ships. `mcp.ggui.ai/playground/mdh` is a first-party hosted MCP service that exposes a globally shared 1000×1000 pixel grid — a tribute to [Alex Tew’s 2005 Million-Dollar Homepage](https://en.wikipedia.org/wiki/The_Million_Dollar_Homepage). Every signed-in user reads and writes the same canvas. Where the [Todos playground](/clients/playground-todos/) demonstrates per-user persistent state, MDH demonstrates **globally shared mutable state** rendered as generative UI. Three tools, one canvas, last-write-wins semantics. The agent claims a pixel, the host renders the new region inline, the next user can claim right over the top. ## What it demonstrates [Section titled “What it demonstrates”](#what-it-demonstrates) * **Shared mutable state across users**: every claim is visible to every other signed-in caller immediately. * **Generative UI over a sparse data shape**: `mdh_read_region` returns only claimed cells, so the host renders a sparse grid — pure data, no markup decisions baked into the tool. * **Attribution without ownership**: each claimed cell records the writer’s `userId`, but anyone can overwrite. Identity is recorded; tenure is not. If you want the deep “why” of the service model behind this, see [MCP services](/architecture/mcp-services/) — `playground-mdh` is one of three reference services in `cloud/mcp-services/`. ## The three tools [Section titled “The three tools”](#the-three-tools) All three are Cognito-gated. Anonymous calls (no bearer token) return an explicit `authentication required` error. | Tool | Input | Output | Notes | | ----------------- | ------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------- | | `mdh_read_region` | `{ x, y, width, height }` | `{ pixels: Pixel[] }` | Sparse — unclaimed cells omitted. Region capped at 100×100 cells per call. | | `mdh_claim_pixel` | `{ x, y, color }` | `{ pixel }` | Single-cell write. `color` is `#RRGGBB` hex. Last-write-wins (see warning below). | | `mdh_get_stats` | `{}` | `{ totalClaimed, uniqueUsers, gridWidth, gridHeight }` | Cheap aggregate read. `gridWidth` and `gridHeight` are always 1000. | A `Pixel` row is `{ x, y, color, userId, claimedAt }`. Coordinates are integers, `0 <= x < 1000` and `0 <= y < 1000`. `claimedAt` is ISO-8601. The region cap exists to bound payload size: a 100×100 fully-claimed read returns 10,000 entries. Agents wanting a wider view issue multiple reads — the sparse response means the cost scales with claimed density, not region size. Last-write-wins, no permanent ownership `mdh_claim_pixel` REPLACES any existing claim on that cell. The most recent writer’s `userId` overwrites the previous one. There is no “owned forever”, no allow-list, no first-claim precedence. Anyone signed in can paint over anything. The wire description on the tool itself spells this out so agents surface it before the user buys in. ## Auth model [Section titled “Auth model”](#auth-model) Cognito-gated. Every handler resolves `ctx.userId` from the bearer key minted by [console.ggui.ai](/clients/console/) and rejects calls without one. On `mdh_claim_pixel`, that same `userId` is stamped on the resulting pixel row — that’s the attribution surface visible to subsequent `mdh_read_region` callers. Reads are gated too. The canvas is end-user surface, not a public dataset; anonymous reads are deliberately not exposed at this slice. ## Try it [Section titled “Try it”](#try-it) The wiring is identical to the [Todos playground](/clients/playground-todos/) — same auth header, same OAuth ceremony from MCP-Apps-aware hosts, different URL. **Claude Desktop**: Settings → Connectors → Add custom connector, paste: ```plaintext https://mcp.ggui.ai/playground/mdh ``` Approve the OAuth ceremony at `console.ggui.ai`; a new `ggui_user_*` row appears in [`/keys/connector`](https://console.ggui.ai/keys/connector). Then try prompts like: > Show me a 50×50 region around the center of the canvas. > Claim the pixel at (500, 500) in red. > How many pixels have been claimed total, and by how many users? **Claude Agent SDK** (or any host that takes a remote MCP URL): ```typescript import { query } from "@anthropic-ai/claude-agent-sdk"; const apiKey = process.env.GGUI_USER_KEY!; // ggui_user_* const mcpServers = { mdh: { type: "http" as const, url: "https://mcp.ggui.ai/playground/mdh", headers: { Authorization: `Bearer ${apiKey}` }, }, }; for await (const msg of query({ prompt: "Claim (500, 500) in #ff0044, then show me a 20×20 region around it.", options: { model: "claude-sonnet-4-6", mcpServers, allowedTools: [ "mcp__mdh__mdh_read_region", "mcp__mdh__mdh_claim_pixel", "mcp__mdh__mdh_get_stats", ], }, })) { // consume the SDK message stream } ``` The Claude Agent SDK namespaces every MCP tool as `mcp____` — with `serverName: "mdh"` here, the tool ids land as `mcp__mdh__mdh_read_region`, `mcp__mdh__mdh_claim_pixel`, and `mcp__mdh__mdh_get_stats`. For the full agent-side wiring (system prompt, error handling, streaming), see the [Claude Agent example](/examples/claude-agent/) and swap the URL + tool whitelist. ## How it’s built [Section titled “How it’s built”](#how-its-built) The service is closed-source (`@ggui-private/mcp-playground-mdh` — not published or mirrored), but its shape is simple enough to describe: * a package entry exporting a `createPlaygroundMdhHandlers({ grid })` convenience factory, * one file per tool (read-region / claim-pixel / get-stats), * a `PixelGrid` interface with an in-memory implementation. The grid is the single source of truth for its own dimensions and surfaces them on the wire via `mdh_get_stats`. To build your own globally shared state surface in this shape, use the OSS **`McpService` mount primitive** in [`@ggui-ai/mcp-server`](/architecture/mcp-services/) — the same seam this service mounts through. The [MCP services architecture](/architecture/mcp-services/) page covers mount points, the `AuthAdapter` contract, and how `ctx.userId` flows from the bearer header to the handler. # Todos playground > Hosted MCP service at mcp.ggui.ai/playground/todos — a per-user persistent todo list demo. Try generative UI rendering shared state. Coming soon This page describes the **managed hosted path** (`mcp.ggui.ai` / `console.ggui.ai`), which is **not yet live** — it is not part of GGUI Preview 0.1.0. The self-hosted path is available today — start with the [Quickstart](/oss-quickstart/). This page is kept as a preview of the managed path and goes live when hosted ggui ships. `mcp.ggui.ai/playground/todos` is a first-party hosted MCP service that exposes a per-user persistent todo list. Sign in to [console.ggui.ai](/clients/console/), point your agent at the URL, and watch the agent call a tool while ggui renders the list inline as generative UI. State survives refresh, re-login, and host swaps — todos are pinned to your Cognito identity, not the session. This is the smallest “real” MCP-driven surface we ship. No code to write, no schema to learn — the four tools are described by the server’s `tools/list` response, and the host (Claude Desktop, Goose, your own agent) drives them. ## What it demonstrates [Section titled “What it demonstrates”](#what-it-demonstrates) * **Agent → tool → generative UI**: the agent calls a tool, the runtime feeds the result into a blueprint, the host renders the resulting list inline. * **Per-user persistence**: log out, come back tomorrow from a different host — same todos. * **Cognito identity at the MCP edge**: tool handlers read `ctx.userId` directly. No second auth layer; the `Authorization: Bearer ggui_user_*` header that authenticated the MCP session also scopes the data. If you want the deep “why” of the service model that makes this work, see [MCP services](/architecture/mcp-services/) — `playground-todos` is one of three reference services in `cloud/mcp-services/`. ## The four tools [Section titled “The four tools”](#the-four-tools) All four are scoped to the caller’s `ctx.userId`. Anonymous calls (no bearer token) return an explicit `authentication required` error. | Tool | Input | Output | Notes | | -------------- | ---------- | -------------------------------------- | ---------------------------------------------------------------------------------- | | `todos_list` | `{}` | `{ todos: Todo[] }` | Oldest-first by `createdAt`. Empty array when the user has none — never `null`. | | `todos_add` | `{ text }` | `{ todo }` | `text` trimmed; empty or 500+ char bodies rejected at the schema boundary. | | `todos_toggle` | `{ id }` | `{ found: boolean, todo: Todo\|null }` | Flips `done`. Missing id and cross-user id collapse to one shape (see Auth model). | | `todos_delete` | `{ id }` | `{ ok: boolean }` | `ok: true` only when the caller owned a todo with that id. | A `Todo` row is `{ id, text, done, createdAt }`. `createdAt` is an ISO-8601 string; `id` is opaque (treat it as a black-box handle returned by `todos_add` or `todos_list`). ## Auth model [Section titled “Auth model”](#auth-model) Cognito-gated. Every handler resolves `ctx.userId` from the bearer key minted by [console.ggui.ai](/clients/console/) and rejects calls without one. The console is the only place those keys come from — either through an OAuth ceremony from an MCP-Apps-aware host or by minting one manually at `/keys/connector`. Cross-user probing is structurally prevented. `todos_toggle` and `todos_delete` collapse two failure modes into one wire shape: * The id doesn’t exist. * The id exists but belongs to a different user. Both return the same negative response (`found: false` / `ok: false`). A caller can’t enumerate other users’ id space. ## Try it from Claude Desktop [Section titled “Try it from Claude Desktop”](#try-it-from-claude-desktop) If you’ve already connected `mcp.ggui.ai` from the [Claude Desktop walkthrough](/clients/claude-desktop/), Claude Desktop will pick up `playground-todos` once you add the second connector. In Settings → Connectors → Add custom connector, paste: ```plaintext https://mcp.ggui.ai/playground/todos ``` The OAuth ceremony runs again against `console.ggui.ai`; approve it the same way you did for the main `mcp.ggui.ai` connector. A new `ggui_user_*` row appears in [`/keys/connector`](https://console.ggui.ai/keys/connector) labelled with the connector name. Once connected, try prompts like: > What’s on my todo list? > Add “ship the launch post” to my todos, then show me everything pending. > Mark the first todo as done. Claude calls `todos_list` / `todos_add` / `todos_toggle`, and the table updates in the chat. Refresh Claude Desktop, ask again — same list comes back. ## Try it from your own agent [Section titled “Try it from your own agent”](#try-it-from-your-own-agent) The Todos playground is a vanilla remote MCP server. Anything that speaks `streamable-http` MCP + bearer auth works. For Claude Agent SDK: ```typescript import { query } from "@anthropic-ai/claude-agent-sdk"; const apiKey = process.env.GGUI_USER_KEY!; // ggui_user_* const mcpServers = { todos: { type: "http" as const, url: "https://mcp.ggui.ai/playground/todos", headers: { Authorization: `Bearer ${apiKey}` }, }, }; for await (const msg of query({ prompt: "Add 'try the playground' to my todos, then list everything.", options: { model: "claude-sonnet-4-6", mcpServers, allowedTools: [ "mcp__todos__todos_list", "mcp__todos__todos_add", "mcp__todos__todos_toggle", "mcp__todos__todos_delete", ], }, })) { // consume the SDK message stream } ``` The Claude Agent SDK namespaces every MCP tool as `mcp____` — with `serverName: "todos"` here, the tool ids land as `mcp__todos__todos_list`, `mcp__todos__todos_add`, and so on. The pattern is the same for any other host that takes an MCP-server URL. For the full agent-side wiring (system prompt, error handling, streaming), see the [Claude Agent example](/examples/claude-agent/). The same pattern applies — swap `mcp.ggui.ai` for `mcp.ggui.ai/playground/todos`, narrow the tool whitelist to the four todos tools. ## How it’s built [Section titled “How it’s built”](#how-its-built) The service is closed-source (`@ggui-private/mcp-playground-todos` — not published or mirrored), but its shape is simple enough to describe: * a package entry exporting a `createPlaygroundTodosHandlers({ store })` convenience factory, * one file per tool (list / add / toggle / delete), each \~50 lines, * a `TodoStore` interface with an in-memory implementation for tests; production swaps in a DynamoDB-backed store against the same interface. To build your own service in this shape, use the OSS **`McpService` mount primitive** in [`@ggui-ai/mcp-server`](/architecture/mcp-services/) — the same seam this service mounts through. The [MCP services architecture](/architecture/mcp-services/) page covers mount points, the `AuthAdapter` contract, and how `ctx.userId` is resolved end-to-end. # Auth-Gated UI > Gate ggui renders behind your app's auth with a bearer token on useMcpAppsChat — and understand why OAuth tool-consent is the client's job, not ggui's. ggui is a renderer, not an identity provider. Your app already knows who the user is. There are **two separate auth concerns**, and only the first is yours to wire: 1. **Authenticating your app → agent backend.** Every request `useMcpAppsChat` makes (prompt POST, snapshot GET, the iframe → MCP tool-call relay) carries a bearer token your app supplies. The backend gates chat ownership on the principal that token identifies. **This is the recipe below.** 2. **OAuth consent for tools the *agent* calls.** When a tool the agent calls needs the end-user to authorize a third-party service (Google, Slack), that consent flow is **not** ggui’s responsibility — it belongs to MCP’s OAuth standard, the hosting agent, and your client app. ggui only surfaces an optional signal. See [OAuth tool-consent is the client’s job](#oauth-tool-consent-is-the-clients-job). ## Gate the chat behind a bearer token [Section titled “Gate the chat behind a bearer token”](#gate-the-chat-behind-a-bearer-token) `useMcpAppsChat` takes two auth hooks: * **`getAuthToken()`** — called before every request; return the bearer token to send as `Authorization: Bearer ` (or `undefined` for none). * **`onUnauthenticated()`** — called on a `401`; refresh/re-mint your token, return `true` to retry the request once, `false` to surface the error. The [`ggui-basic-web`](https://github.com/ggui-ai/ggui/tree/main/samples/apps/ggui-basic-web) sample uses these for a **guest-token** flow: it mints an anonymous token from the backend’s `POST /auth/guest` mount, caches it, and re-mints on `401`. Swap that mint for your own user-session token and the same wiring gates renders behind a signed-in user: ```tsx import { useCallback, useRef } from "react"; import { useMcpAppsChat } from "@ggui-ai/react/chat-helpers"; function Chat({ agentEndpoint }: { agentEndpoint: string }) { const { user, getAccessToken, refreshSession } = useAuth(); // your auth provider // Read the current token per-request (kept in a ref so the callback // always sees the latest after a refresh). const tokenRef = useRef(getAccessToken()); const getAuthToken = useCallback(() => tokenRef.current, []); // 401 → refresh once, then retry. Return false to give up. const onUnauthenticated = useCallback(async () => { const fresh = await refreshSession(); if (!fresh) return false; tokenRef.current = fresh; return true; }, [refreshSession]); const { entries, sessions, send, handleAppMessage } = useMcpAppsChat({ chatEndpoint: `${agentEndpoint}/agent`, snapshotEndpoint: `${agentEndpoint}/agent`, getAuthToken, onUnauthenticated, }); // render `entries` + mount `sessions` with as usual } ``` The token rides every hook request automatically. The backend authenticates it and scopes the conversation (its `chatId` snapshot + resume state) to that principal — clear the session and you’re a different principal with different chats. ### Mount-time gate [Section titled “Mount-time gate”](#mount-time-gate) Don’t open the chat until your provider says the user is signed in — a plain conditional render, exactly how the sample guards on `guestTokenReady`: ```tsx function App({ agentEndpoint }: { agentEndpoint: string }) { const { isAuthenticated, isLoading } = useAuth(); if (isLoading) return

Loading…

; return ; } ``` ### The tool-call relay carries the token too [Section titled “The tool-call relay carries the token too”](#the-tool-call-relay-carries-the-token-too) When the iframe dispatches a tool call, your host relays it to the agent backend’s `POST /agent` (`kind: "tool-call"`) inside ``. Send the **same** bearer token on that relay so the MCP call runs as the signed-in user — the sample’s `onCallTool` reads `getAuthToken()` and sets `Authorization: Bearer ` on the relay fetch. Don’t trust anything the iframe puts in the payload as identity; the token on the relay is the credential. ## OAuth tool-consent is the client’s job [Section titled “OAuth tool-consent is the client’s job”](#oauth-tool-consent-is-the-clients-job) A different situation: the agent wants to call a tool that needs the **end-user** to authorize a third-party service first (read their Google Calendar, post to Slack). That consent flow is deliberately **outside** the ggui protocol. It is owned by: * **MCP’s OAuth standard** — the spec defines how an MCP server advertises that a tool needs authorization and how the consent/token exchange happens. * **The hosting agent** (e.g. `@anthropic-ai/claude-agent-sdk`) — follows that spec to handle tool authorization. * **Your end-user client app** — the surface actually talking to the agent backend pops its own consent UI and drives the redirect. Consent is a client decision, not something ggui’s runtime or protocol renders. * **Guuey’s MCP proxy** — captures an OAuth credential once so multiple agents can reuse it (coming soon — part of the hosted Guuey platform, not the open ggui protocol). So ggui itself renders no consent screen. What it *does* provide is an **optional helper signal**: when the server emits a `system` frame with `action: "auth_required"`, the iframe-runtime projects it to a typed `AuthRequiredEvent` on the `ggui:observe` postMessage channel (`{ type: "ggui:observe", event }`). A host that wants to surface a consent prompt can listen for it and open `authUrl` in a popup — but rendering that prompt, and the OAuth exchange itself, are your client’s job: ```ts import type { AuthRequiredEvent } from "@ggui-ai/react"; // AuthRequiredEvent shape (kind: "auth-required"): // provider — canonical service id ("google", "slack") // authUrl — URL to open to start the OAuth consent flow // displayName? — human-readable service name // scopes? — requested OAuth scopes // message? — why access is needed ``` It’s a projection of the protocol’s `SystemPayload`, not a new ggui surface — surfacing it is opt-in, and ggui draws nothing itself. See [Error Handling → renderer-side faults](/cookbook/error-handling/#renderer-side-faults-stay-inside-the-iframe) for the full observability catalog. ## See also [Section titled “See also”](#see-also) * [React SDK](/sdk/react/) — `useMcpAppsChat` (`getAuthToken` / `onUnauthenticated`) + `` * [`ggui-basic-web` sample](https://github.com/ggui-ai/ggui/tree/main/samples/apps/ggui-basic-web) — the runnable guest-token reference (`Chat.tsx`) * [Error Handling](/cookbook/error-handling/) — HTTP `401`, JSON-RPC auth codes, and the `auth-required` observability event * [Getting Started](/getting-started/) — the agent-side handshake → render → consume loop # Chat with Your Own Storage > Build a ggui-powered chat UI on top of your existing persistence layer using @ggui-ai/react and the pure helpers in @ggui-ai/react/chat-helpers. You own the UI, you own the storage. ggui gives you the streaming protocol (`useInvoke`) plus pure helpers for persistence shape (`@ggui-ai/react/chat-helpers`). Where messages live, how threads are indexed, what your composer looks like — that’s yours. ## When to use this pattern [Section titled “When to use this pattern”](#when-to-use-this-pattern) Pick this pattern when **at least one** holds: * You already have a persistence layer (Postgres, Firestore, IndexedDB, your Redux store) and don’t want a second one. * You need full control of the message schema — custom attachments, per-message ACLs, server-side fan-out. * You’re integrating ggui into an existing chat surface, not building a new one. If none apply and you just want “a chat UI that works”, reach for `useChatThread` in `@ggui-ai/react/chat-thread` — same flow behind a single hook with a pluggable `MessageStorageAdapter` and a `ChatThreadProvider`. ## 60-line example [Section titled “60-line example”](#60-line-example) The file below is the complete working integration — streaming, persistence, card rendering, send — in \~60 lines. ```tsx import { useEffect } from "react"; import { GguiProvider, useInvoke } from "@ggui-ai/react"; import { useRafThrottled, invokeMessageToContentGroups, extractRenderFromToolResult, type ContentGroup, } from "@ggui-ai/react/chat-helpers"; // Replace with any storage: localStorage, fetch, IndexedDB, Firestore, … const store: Array<{ threadId: string; group: ContentGroup }> = []; function persist(threadId: string, messages: ReturnType["messages"]) { const seen = new Set(store.filter((e) => e.threadId === threadId).map((e) => e.group.key)); for (const msg of messages) { for (const group of invokeMessageToContentGroups(msg)) { if (!seen.has(group.key)) store.push({ threadId, group }); } } } function Chat({ threadId, endpointUrl }: { threadId: string; endpointUrl: string }) { const { messages, send, isStreaming } = useInvoke({ endpointUrl }); const throttled = useRafThrottled(messages); useEffect(() => { persist(threadId, messages); }, [threadId, messages]); return (

{throttled.map((m) => (

{m.role}: {m.content.map((b, i) => { if (b.type === "text") return

{b.text}

; if (b.type === "tool_result") { const render = extractRenderFromToolResult(b); return

{JSON.stringify(render, null, 2)}

; } return null; })}

))} send("hello", { clientMessageId: crypto.randomUUID() })} > Send hello

); } export default function App() { return ( ); } ``` ## The `ContentGroup` contract [Section titled “The ContentGroup contract”](#the-contentgroup-contract) `invokeMessageToContentGroups(message)` splits a finalized invoke message into `ContentGroup`s — the durable unit you persist: ```ts interface ContentGroup { key: string; // `${message.id}-${startBlockIdx}` — see invariant below kind: "text" | "card" | "other"; authorRole: "user" | "agent"; blocks: ContentBlock[]; // a contiguous run of text, or a tool_use + tool_result pair cardSnapshot: unknown | null; // frozen GguiSession for kind="card" textPreview: string; // ~160-char preview for chat-list tiles } ``` **The `key` invariant.** `key` is deterministic from `message.id` plus the block index where the group starts. Two consequences: 1. **Idempotency.** Re-persisting the same group with the same key is a no-op. If your storage uses `key` as primary key (recommended), the `persist()` loop above can run after every token delta without producing duplicates. 2. **Streaming messages are excluded.** A message whose `isStreaming` is `true` returns `[]` — groups appear only after the turn finalizes. That’s why `persist()` doesn’t need a separate “on end\_turn” callback. ## Reloading a thread [Section titled “Reloading a thread”](#reloading-a-thread) On thread reopen, rebuild the `ConversationMessage[]` your store remembers and seed the hook via `initialMessages`. `contentGroupsToConversationMessages` collapses groups sharing the same `message.id` prefix back into one message: ```tsx import { contentGroupsToConversationMessages } from "@ggui-ai/react/chat-helpers"; function useSeededInvoke(threadId: string, endpointUrl: string) { // Resolve before render — useInvoke captures initialMessages on mount. const groups = store.filter((e) => e.threadId === threadId).map((e) => e.group); const seed = contentGroupsToConversationMessages(groups); return useInvoke({ endpointUrl, initialMessages: seed }); } ``` `initialMessages` is a **seed on mount**. Changing it on re-render does *not* reset hook state — intentional; the hook owns the conversation after mount. To switch threads, unmount the `` subtree (set `key={threadId}`) and let the new instance seed from that thread’s store. ## Why `send({ clientMessageId })` matters [Section titled “Why send({ clientMessageId }) matters”](#why-send-clientmessageid--matters) `useInvoke` accepts an optional `clientMessageId` the caller controls: ```tsx send("hello", { clientMessageId: crypto.randomUUID() }); ``` The rendered user message’s `id` becomes that value, which buys: * **Retry without duplicates.** Retrying the same send after a network failure produces the same `clientMessageId` → same `ContentGroup.key` → the outbox is idempotent by construction. * **Cross-device continuity.** Persist user messages optimistically on the sending device; when the agent turn later replays on another device, the same `clientMessageId` collapses both into one thread entry. Without `clientMessageId`, `useInvoke` falls back to a random `user_` id — fine for ephemeral chats, wrong for durable storage. ## What you still have to do [Section titled “What you still have to do”](#what-you-still-have-to-do) The helpers stop at *shape*. You still own: * **Transport to storage.** `store.push(...)` above is an in-memory array for brevity. Replace it with `fetch('/persist')`, an IndexedDB write, a Firestore batch — whatever fits your stack. * **Thread indexing.** `ContentGroup.textPreview` is the building block for chat-list tiles; wiring it into a sidebar is yours. * **Reconnect + resume.** `useInvoke` does not replay an interrupted stream. If the page reloads mid-turn, the in-flight assistant message is lost — only finalized groups persist. `useChatThread` (next segment up) closes this gap. When those boundaries start to hurt, reach for `useChatThread`: same primitives, plus a `MessageStorageAdapter` interface, a `ChatThreadProvider`, the outbox, seed-on-reopen wiring, and the optimistic-send UX. ## See also [Section titled “See also”](#see-also) * [React SDK reference](/sdk/react/) — `useInvoke`, `useChatThread`, and the `` render host * [Glossary](/glossary/) — gadget, tool, blueprint, render * [Self-hosted registry](/sdk/self-hosted-registry/) — point `endpointUrl` at your own server # Custom Theming > Match ggui-generated UIs to your brand with two-layer theming — design-token CSS variables for your host chrome, plus the operator's ggui.json theme preset for the generated iframe content. ggui theming has **two independent layers**, and they live on opposite sides of the iframe boundary. Keep them straight: 1. **Your host chrome** — the React app *around* the render (the chat panel, the surrounding page). You theme this with `@ggui-ai/design` tokens: a `` injects `--ggui-*` CSS variables on `:root` and your CSS references them. 2. **The generated UI inside the iframe** — the component the agent rendered. You never style this from the host (it’s sandboxed on a different origin). Its palette comes from the operator’s `ggui.json` `theme` preset, resolved per render and applied as a runtime CSS-variable overlay. The two are matched by convention: the [`ggui-basic-web`](https://github.com/ggui-ai/ggui/tree/main/samples/apps/ggui-basic-web) sample picks the **same** preset for its host chrome that the demo `ggui.json` picks for the iframe, so the chat shell and the generated card share one palette. For the full token reference (palettes, scales, semantic colors), see [Design Tokens](/design/tokens/). ## Layer 1 — host chrome via `` [Section titled “Layer 1 — host chrome via \”](#layer-1--host-chrome-via-themeprovider) `` (from `@ggui-ai/design/themes`) takes a raw [DTCG](https://design-tokens.github.io/community-group/format/) token tree and a color mode, injects every token as a `--ggui-*` CSS variable on `:root`, and wires the base `html, body` font + surface colors. Pull a registered preset with `getRawTheme(id, mode)`: ```tsx import { ThemeProvider, getRawTheme } from "@ggui-ai/design/themes"; // Resolve the raw DtcgTheme token tree for a registered preset. const INDIGO_DARK = getRawTheme("indigo", "dark"); function App() { return ( {/* Your chat panel / page chrome. Every CSS rule that references a --ggui-* variable now resolves against the indigo/dark tokens. */} ); } ``` Your stylesheet then references the injected variables — exactly how the sample’s `globals.css` maps semantic chat-shell roles onto ggui tokens: ```css :root { --bg-app: var(--ggui-color-background); --bg-chat: var(--ggui-color-surface); --accent: var(--ggui-color-primary-500); --fg: var(--ggui-color-onSurface); --fg-muted: var(--ggui-color-onSurfaceVariant); } .chat { background: var(--bg-chat); color: var(--fg); font-family: var(--ggui-font-family-sans); } ``` ### Discovering presets [Section titled “Discovering presets”](#discovering-presets) `@ggui-ai/design/themes` ships a registry — list what’s available at runtime (e.g. to build a theme picker): ```tsx import { getThemeIds, listThemes, getDefaultThemeId } from "@ggui-ai/design/themes"; getThemeIds(); // ['ggui', 'indigo', 'claudic', …] — every registered id listThemes(); // [{ id, name, description, modes }, …] — metadata for a picker getDefaultThemeId(); // 'ggui' ``` ## Layer 2 — generated iframe content via `ggui.json` [Section titled “Layer 2 — generated iframe content via ggui.json”](#layer-2--generated-iframe-content-via-gguijson) You can’t reach into the sandboxed iframe with CSS. Instead, the operator’s `ggui.json` `theme` block sets the app’s default preset. At each render the server resolves the theme (per-render `themeId` override → App default → server fallback), snapshots it onto the GguiSession, and the iframe-runtime applies it as a `--ggui-*` CSS-variable overlay on the iframe’s `:root` — generated components reference the same token variables your host chrome does, so the palette is a runtime overlay, not generated code: ```json { "schema": "1", "protocol": "draft-2026-06-12", "app": { "slug": "my-app", "name": "My App" }, "theme": { "preset": "indigo", "mode": "dark" } } ``` `theme` also accepts a bare string preset shorthand (`"theme": "indigo"`), an `overrides` map of flat dot-path token tweaks on top of a preset (`{ "preset": "indigo", "mode": "dark", "overrides": { "color.primary.500": "#8b5cf6" } }` — no custom theme file needed), and a `{ "file": "./theme.json", "mode": "dark" }` form pointing at a DTCG theme file. Lint a theme file before serving with `ggui theme validate `. Match `theme.preset` / `theme.mode` here to the `getRawTheme(...)` you pass to `` in your host, and the chat shell and the rendered card render in one cohesive palette — the sample does exactly this. ### Per-render theme override [Section titled “Per-render theme override”](#per-render-theme-override) The preset isn’t fixed per app. Agents can list the available presets with the `ggui_list_themes` tool (each entry is `{ id, name, description, modes }`) and pick one for a single render via the `themeId` input on `ggui_render` — the override wins over the app default for that render only. `App.availableThemeIds` allowlists which presets agents may pick. ## Ad-hoc CSS token overrides [Section titled “Ad-hoc CSS token overrides”](#ad-hoc-css-token-overrides) The token layer is just CSS custom properties with hardcoded fallbacks, so you can also override individual variables without a registered preset — useful for a quick rebrand on top of a chosen theme, or for scoping one subtree. ### Global override [Section titled “Global override”](#global-override) Set tokens on `:root` to restyle every host-chrome surface in the page: ```css :root { /* Primary brand color (50 → 900 scale) */ --ggui-color-primary-50: #eff6ff; --ggui-color-primary-500: #3b82f6; --ggui-color-primary-600: #2563eb; --ggui-color-primary-900: #1e3a8a; /* Typography */ --ggui-font-family-sans: "Inter", system-ui, sans-serif; --ggui-font-family-mono: "JetBrains Mono", ui-monospace, monospace; /* Shape + density */ --ggui-spacing-md: 16px; --ggui-shape-radius-md: 8px; --ggui-shape-shadow-md: 0 8px 16px -4px rgba(15, 23, 42, 0.1); } ``` These run on top of whatever `` injected — the provider writes the `:root` block first, your stylesheet’s later `:root` rules win on equal specificity. ### Scoped theming [Section titled “Scoped theming”](#scoped-theming) CSS custom properties cascade — wrap any subtree to give it its own accent without leaking to siblings: ```tsx

{/* Everything in here picks up the purple primary + softer corners */}

``` ## Token reference [Section titled “Token reference”](#token-reference) | Category | Pattern | Example | | ------------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------- | | Colors (primary) | `--ggui-color-primary-{50-900}` | `--ggui-color-primary-600` | | Colors (neutral) | `--ggui-color-neutral-{50-900}` | `--ggui-color-neutral-200` | | Colors (status) | `--ggui-color-{success,warning,error,info}-{50,100,200,500,600,700,800}` | `--ggui-color-success-500` | | Surface + content | `--ggui-color-{surface,onSurface,surfaceVariant,onSurfaceVariant,container,onContainer,outline,outlineVariant}` | `--ggui-color-onSurface` | | Typography | `--ggui-font-{family,size,weight,lineHeight}-*` | `--ggui-font-size-lg` | | Spacing | `--ggui-spacing-{xs,sm,md,lg,xl,2xl,3xl}` | `--ggui-spacing-md` | | Shape — radius | `--ggui-shape-radius-{none,sm,md,lg,xl,2xl,full}` | `--ggui-shape-radius-lg` | | Shape — shadow | `--ggui-shape-shadow-{none,xs,sm,md,lg,xl,2xl}` | `--ggui-shape-shadow-md` | | Motion — duration | `--ggui-motion-duration-{instant,fast,normal,slow,slower}` | `--ggui-motion-duration-normal` | | Motion — transition | `--ggui-motion-transition-{colors,opacity,transform,all}` | `--ggui-motion-transition-colors` | | Accessibility | `--ggui-accessibility-focusRing-{color,width,offset}` (plus `reducedMotion`, `highContrast`) | `--ggui-accessibility-focusRing-color` | | Z-Index | `--ggui-zIndex-{hide,base,docked,dropdown,sticky,banner,overlay,modal,popover,skipLink,toast,tooltip}` | `--ggui-zIndex-modal` | **Status colors are scales** — `success`, `warning`, `error`, and `info` each ship the full 50/100/200/500/600/700/800 stops (no singletons). **Material role pairs** (`surface`/`onSurface`, `surfaceVariant`/`onSurfaceVariant`, `container`/`onContainer`, `outline`/`outlineVariant`) keep contrast right across nested surfaces — override the pair together, never one half. See [Design Tokens](/design/tokens/) for live swatches and the complete scale. ## See also [Section titled “See also”](#see-also) * [Design Tokens](/design/tokens/) — full palette, scales, and live swatches * [React SDK](/sdk/react/) — `` + `useMcpAppsChat`, the web render-hosting surface * [`ggui-basic-web` sample](https://github.com/ggui-ai/ggui/tree/main/samples/apps/ggui-basic-web) — the runnable reference that matches host chrome to `ggui.json` # Error Handling > Classify ggui failures across HTTP, JSON-RPC, and the renderer's ggui:observe channel — and recover from each at its layer. ggui surfaces failures at three layers. Handle each at its layer: 1. **HTTP** — the MCP transport returns `401` / `403` / `429` / `5xx` before the JSON-RPC body is even parsed. 2. **JSON-RPC** — a `tools/call` reaches the server but the server returns a `-32xxx` error code (or a tool-level failure with `isError: true`). 3. **Live channel** — a failure *after* a successful render. Action-validation rejections ride the live-channel WebSocket as typed `error` frames carrying `code: 'CONTRACT_VIOLATION'` (numeric `-32020`) and surface in the renderer, not the agent; nothing lands on the consume buffer. ## Layer 1 — HTTP errors from the MCP transport [Section titled “Layer 1 — HTTP errors from the MCP transport”](#layer-1--http-errors-from-the-mcp-transport) These come back as `IsHttpError` / response status from whichever HTTP client your MCP SDK uses. Treat them as transport failures — the server hasn’t even looked at your JSON-RPC payload yet. | Status | Meaning | Retry? | | ------------- | ----------------------------------- | -------------------------------- | | `401` | Bad / expired API key | No — fix config | | `403` | Key valid but app not authorized | No — fix config | | `429` | Rate-limited (`Retry-After` header) | Yes, after `Retry-After` seconds | | `5xx` | Transient server failure | Yes, with exponential backoff | | network error | DNS / connection / TLS failure | Yes, with exponential backoff | The `Retry-After` header (when present) is authoritative — honor it verbatim. See [`/api/rate-limits/`](/api/rate-limits/) for the 429 response shape (body + header) and a raw-HTTP backoff recipe. ## Layer 2 — JSON-RPC errors from the server [Section titled “Layer 2 — JSON-RPC errors from the server”](#layer-2--json-rpc-errors-from-the-server) A 200 HTTP response can still carry a JSON-RPC error. The MCP SDKs surface these as thrown errors with a numeric `code`; raw HTTP callers see `{ "error": { "code": -32xxx, "message": "..." } }` in the response body. | Code | Name | When | Retry? | | -------- | ------------------- | -------------------------------- | ------------------------ | | `-32700` | Parse Error | Invalid JSON in request | No — fix the call | | `-32600` | Invalid Request | Not a valid JSON-RPC object | No — fix the call | | `-32601` | Method Not Found | Unknown tool name | No — fix the call | | `-32602` | Invalid Params | Missing / invalid tool arguments | No — fix the call | | `-32603` | Internal Error | Server-side failure | Yes, with backoff | | `-32001` | Unauthorized | Invalid token or app ID | No — fix config | | `-32002` | Session Not Found | Session expired or reaped | Re-handshake + render | | `-32003` | App Not Found | App ID does not exist | No — fix config | | `-32004` | Production Failed | UI generation failed | Yes — try simpler intent | | `-32005` | Capability Denied | Requested capability not allowed | No — fix config | | `-32013` | Rate Limit Exceeded | Platform rate limit hit | Yes, after backoff | Platform deployments also reserve the `-32010` range (`-32010` generation quota, `-32011` app limit, `-32012` concurrent-session limit, `-32020` contract violation). Full table with descriptions: [`/api/mcp-protocol/#error-codes`](/api/mcp-protocol/#error-codes). Tool-level failures (the tool ran but returned an error result) come back as a successful JSON-RPC response with `isError: true` on the `tools/call` result content. Inspect `result.content` for the failure detail. On the OSS server the `ggui_*` tools surface their domain failures this way — `isError` results whose typed error classes carry string codes like `handshake_not_found` and `session_not_found` — while the numeric `-32xxx` table above is the protocol-level canonical set. ### Retry with exponential backoff (raw `@modelcontextprotocol/sdk`) [Section titled “Retry with exponential backoff (raw @modelcontextprotocol/sdk)”](#retry-with-exponential-backoff-raw-modelcontextprotocolsdk) The SDK throws on HTTP failures and on JSON-RPC errors alike; you classify by `error.code` (JSON-RPC) or by reading the HTTP status off the underlying response. The pattern below works for both layers. ```typescript import { Client } from "@modelcontextprotocol/sdk/client/index.js"; import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"; const client = new Client({ name: "my-agent", version: "1.0.0" }); const transport = new StreamableHTTPClientTransport(new URL("http://127.0.0.1:6781/mcp"), { requestInit: { headers: { Authorization: "Bearer dev" } }, }); await client.connect(transport); async function callWithRetry( name: string, args: Record, maxRetries = 3 ): Promise { for (let attempt = 0; attempt <= maxRetries; attempt++) { try { const result = await client.callTool({ name, arguments: args }); if (result.isError) { // Tool-level failure — payload is in result.content. throw new Error(`Tool ${name} returned isError: ${JSON.stringify(result.content)}`); } return result.structuredContent as T; } catch (error) { if (attempt === maxRetries) throw error; // JSON-RPC error: error.code is a -32xxx number. const code = (error as { code?: number }).code; // Permanent — surface immediately. if (code === -32001 || code === -32003) throw error; // auth / app config if (code === -32600 || code === -32601 || code === -32602) throw error; // bad request // Render expired — caller replays at the render layer (see below). if (code === -32002) throw error; // Rate-limited (HTTP 429) — honor Retry-After if the SDK surfaces it. const retryAfter = (error as { retryAfter?: number }).retryAfter; if (retryAfter != null) { await sleep(retryAfter * 1000); continue; } // Transient (5xx, network, -32603, -32004) — exponential backoff. await sleep(Math.min(1000 * 2 ** attempt, 10_000)); } } throw new Error("unreachable"); } const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms)); ``` ### Recover from an expired render (`-32002`) [Section titled “Recover from an expired render (-32002)”](#recover-from-an-expired-render--32002) `-32002 Session Not Found` is the protocol-level canonical code for “the session is gone”. On the OSS server, though, expiry never surfaces as a numeric JSON-RPC error from the `ggui_*` tools — the call succeeds at the JSON-RPC layer and returns `isError: true` with the failure detail in the result content: * **`handshake_not_found`** (from `ggui_render`) — handshake records are single-use and TTL’d (10 minutes); the supplied `handshakeId` was unknown, already consumed, or expired. (A render *consumes* its handshake — handshakes aren’t bound to renders.) * **`session_not_found`** (from `ggui_consume` / `ggui_update` / `ggui_emit` / `ggui_get_session`) — the `sessionId` was never minted, expired via TTL, or belongs to another app. Recovery is the same in every case: re-run `ggui_handshake` → `ggui_render`, which mints a fresh `sessionId`. (Other `isError` results from `ggui_render` — contract violations, schema mismatches — leave the handshake **alive**: fix the arguments and retry on the *same* `handshakeId`.) ```typescript function errorText(result: { isError?: boolean; content?: unknown }): string { const blocks = (result.content ?? []) as Array<{ type: string; text?: string }>; return blocks .filter((b) => b.type === "text") .map((b) => b.text) .join(" "); } async function resilientRender(intent: string, contract: object, props: Record) { const mintHandshake = async () => { const hs = await client.callTool({ name: "ggui_handshake", arguments: { intent, blueprintDraft: { contract } }, }); return (hs.structuredContent as { handshakeId: string }).handshakeId; }; // Negotiate, then render. `ggui_render` takes { handshakeId, props } — // accept the suggestion as-is (no `override`). let result = await client.callTool({ name: "ggui_render", arguments: { handshakeId: await mintHandshake(), props }, }); // Expired / already-consumed handshake → mint a fresh // handshake → render pair (a fresh sessionId comes with it). if (result.isError && /handshakeId .* not found/i.test(errorText(result))) { result = await client.callTool({ name: "ggui_render", arguments: { handshakeId: await mintHandshake(), props }, }); } return result; } ``` ## Layer 3 — typed failures on the live channel [Section titled “Layer 3 — typed failures on the live channel”](#layer-3--typed-failures-on-the-live-channel) The transport- and JSON-RPC-level errors above fire when the **request** fails. A separate layer surfaces **after** a successful render: when the renderer dispatches an action that fails validation (undeclared action name, payload rejected by the declared `actionSpec[name].schema`), the server answers with a typed `error` frame carrying `code: 'CONTRACT_VIOLATION'` — and nothing lands on the consume buffer. These ride the live-channel WebSocket alongside the renderer — not the agent-side MCP poll — so there is no JSON-RPC error to catch on the agent. The renderer observes them and surfaces an error activity row. Earlier protocol drafts reserved a `_ggui:contract-error` channel carrying a `ContractErrorPayload` envelope, but it never gained a first-party emitter and was removed in `draft-2026-06-11` — the channel, payload shape, validator, and code union are all deleted. Contract failures now surface on the call that caused them: inbound action violations answer with a `CONTRACT_VIOLATION` (`-32020`) `error` frame on the live channel, and nothing reaches the consume buffer; `ggui_render` / `ggui_emit` validation failures reject the agent’s own tool call; push-time schema mismatches reject with `SCHEMA_MISMATCH_ERROR`. The reserved `_ggui:` namespace itself survives — the only first-party reserved channels today are `_ggui:lifecycle` and `_ggui:preview` — and your `streamSpec` MUST NOT declare reserved names. ### Translate errors to user-facing messages [Section titled “Translate errors to user-facing messages”](#translate-errors-to-user-facing-messages) Keep user-visible copy at one layer; never leak stack traces or JSON-RPC codes to end users. ```typescript function getUserMessage(error: unknown): string { const code = (error as { code?: number }).code; const status = (error as { status?: number }).status; if (status === 401 || code === -32001) return "Authentication failed — contact support."; if (status === 429) return "Too many requests — please slow down."; if (code === -32002) return "Your session expired."; if (code === -32004) return "We couldn't generate that UI — try a simpler request."; if (status && status >= 500) return "The server is temporarily unavailable."; return "Something went wrong."; } ``` *** ## Renderer-side: faults stay inside the iframe [Section titled “Renderer-side: faults stay inside the iframe”](#renderer-side-faults-stay-inside-the-iframe) The canonical web host mounts each render in a **sandboxed iframe** via `` (from `@mcp-ui/client`, driven by `useMcpAppsChat` — see [React SDK](/sdk/react/)). That sandbox is the fault boundary: an error thrown by LLM-generated component code is contained to its own iframe and **cannot crash your host React tree**. You don’t wrap renders in a host-side error boundary — the origin isolation does that structurally. Two host-observable failure surfaces matter. ### Transport faults — `` [Section titled “Transport faults — \”](#transport-faults--apprenderer-onerror) ``’s own `onError` fires for iframe/transport-level failures (the sandbox bundle failed to load, the runtime failed to boot). It receives a plain `Error`. Log it or show a placeholder in the frame: ```tsx console.warn("[render] AppRenderer error", err)} /> ``` (This is exactly what the [`ggui-basic-web`](https://github.com/ggui-ai/ggui/tree/main/samples/apps/ggui-basic-web) sample does.) ### Structured failures — the `ggui:observe` channel [Section titled “Structured failures — the ggui:observe channel”](#structured-failures--the-gguiobserve-channel) After a successful mount, ggui’s iframe-runtime emits a typed `ObservabilityEvent` to the parent on a dedicated postMessage channel — `{ type: "ggui:observe", event }`. This is where runtime health signals surface, so a host can show an activity row without parsing wire frames. The union is **extensibly-closed** — match the kinds you know, treat the unknown tail as generic: | `event.kind` | When | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | `subscribe-failed` | A non-fatal subscribe failure the reconnect ladder is handling. | | `schema-version-mismatch` | The protocol-version handshake rejected the connection. | | `auth-required` | A tool the agent calls needs OAuth consent — carries `provider` + `authUrl`. See [Auth-Gated UI](/cookbook/auth-gated-ui/). | The `ObservabilityEvent` union + its member types are re-exported from `@ggui-ai/react` (`import type { ObservabilityEvent } from "@ggui-ai/react"`). The `{ type: "ggui:observe", event }` envelope is specified in [Bootstrap handshake](/protocol/bootstrap-handshake/). *** ## See also [Section titled “See also”](#see-also) * [`/api/mcp-protocol/#error-codes`](/api/mcp-protocol/#error-codes) — full JSON-RPC error-code table, plus `CONTRACT_VIOLATION` (`-32020`) * [`/api/rate-limits/`](/api/rate-limits/) — HTTP `429` response shape, `Retry-After` semantics, raw-HTTP backoff recipe * [`@ggui-ai/react` SDK reference](/sdk/react/) — `` + `useMcpAppsChat`, the web render host * [Bootstrap handshake](/protocol/bootstrap-handshake/) — the `ggui:observe` channel + `ObservabilityEvent` catalog * [Troubleshooting](/troubleshooting/) — common errors and their root causes # Feedback Form > Configure an agent to render a feedback form via ggui's MCP server, then read the typed result — the smallest end-to-end ggui pattern. The smallest useful ggui interaction: an agent renders a form, the user submits, the agent reads the typed data. Following the **Zero Agent Code** principle, you don’t hand-call `handshake` / `render` / `consume` — you configure the agent host with ggui’s MCP server and the LLM autonomously drives the loop from a user prompt. Two flavors below — the canonical LLM-driven shape via the Claude Agent SDK, and a manual orchestration variant using `@modelcontextprotocol/sdk` when you need imperative control. ## Canonical: Claude Agent SDK + ggui MCP [Section titled “Canonical: Claude Agent SDK + ggui MCP”](#canonical-claude-agent-sdk--ggui-mcp) The developer’s job: define the typed contract, configure the host, write a user-facing prompt. The LLM autonomously calls `ggui_handshake` → `ggui_render` → `ggui_consume` and surfaces the typed payload. ```typescript import { query } from "@anthropic-ai/claude-agent-sdk"; import { defineContract } from "@ggui-ai/protocol"; // Typed contract — `actionData` for `submit` narrows to {rating, comments}. // The contract still lives in code: it's how you document the shape // the agent should negotiate during `ggui_handshake`. // NOTE: the intent string is NOT a contract field — it travels separately // as the flat `intent` argument of `ggui_handshake` (see the manual // orchestration variant below). const feedbackContract = defineContract({ propsSpec: { properties: { userName: { schema: { type: "string" } }, product: { schema: { type: "string" } }, }, }, actionSpec: { submit: { label: "Submit feedback", schema: { type: "object", properties: { rating: { type: "number", minimum: 1, maximum: 5 }, comments: { type: "string" }, }, required: ["rating", "comments"], }, }, }, } as const); async function collectFeedback(userName: string, product: string) { const result = query({ prompt: `Collect product feedback from ${userName} about ${product}. Render a feedback form with a 1–5 star rating, a comments text area, and a submit button. Greet the user by name. Wait for their submission, then report the rating and comments back to me as JSON: {"rating": number, "comments": string}.`, options: { mcpServers: { ggui: { type: "http", url: "http://127.0.0.1:6781/mcp", // ggui serve --dev-allow-all headers: { Authorization: "Bearer dev", }, }, }, allowedTools: [ "mcp__ggui__ggui_handshake", "mcp__ggui__ggui_render", "mcp__ggui__ggui_consume", ], }, }); // The LLM drives ggui_handshake → ggui_render → ggui_consume on its own. // The render surfaces as an MCP-Apps resource the host mounts; // the typed payload comes back in the final message. for await (const message of result) { if (message.type === "assistant") { console.log(message.message.content); } } } ``` For a complete runnable example (including streaming partial events, multi-turn refinement, and the host’s MCP wiring), see [Examples → Claude Agent](/examples/claude-agent/). ## Manual orchestration: `@modelcontextprotocol/sdk` [Section titled “Manual orchestration: @modelcontextprotocol/sdk”](#manual-orchestration-modelcontextprotocolsdk) Use this shape when you need imperative control — e.g. you’re building a non-LLM workflow, testing the protocol directly, or reacting to every action the user fires (not just the terminal submit). This calls ggui’s MCP tools directly via the official MCP SDK; no LLM in the loop. ```typescript import { Client } from "@modelcontextprotocol/sdk/client/index.js"; import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"; const transport = new StreamableHTTPClientTransport(new URL("http://127.0.0.1:6781/mcp"), { requestInit: { headers: { Authorization: "Bearer dev" }, }, }); const client = new Client({ name: "feedback-script", version: "1.0.0" }); await client.connect(transport); async function collectFeedbackLive(userName: string, product: string) { // 1. Handshake — negotiate the contract before rendering. // Pre-launch, `ggui_render` is handshake-first only. const hsResp = await client.callTool({ name: "ggui_handshake", arguments: { intent: "Collect product feedback (live)", blueprintDraft: { contract: feedbackContract, variance: { seedPrompt: `Show ${userName} a product feedback form for ${product}.`, }, }, }, }); const { handshakeId } = JSON.parse((hsResp.content[0] as { type: "text"; text: string }).text); // 2. Render — accept the handshake's suggestion (omit `override`). // `ggui_render` mints the `sessionId`. const renderResp = await client.callTool({ name: "ggui_render", arguments: { handshakeId, props: { userName, product }, }, }); const { sessionId, resourceUri } = JSON.parse( (renderResp.content[0] as { type: "text"; text: string }).text ); console.log(`Render ${sessionId} ready (${resourceUri}) — a host mounts it.`); // 3. Consume — long-poll until the user submits. while (true) { const consumeResp = await client.callTool({ name: "ggui_consume", arguments: { sessionId, timeout: 25 }, }); const { events, status } = JSON.parse( (consumeResp.content[0] as { type: "text"; text: string }).text ); for (const entry of events) { // Every consume entry has `type: 'action'`; the contract's // `actionSpec` key fires on `entry.intent`. if (entry.intent === "submit") { console.log("Submitted:", entry.actionData); return entry.actionData; } console.log(`Action ${entry.intent}:`, entry.actionData); } if (status !== "active") break; // 'expired' — render TTL elapsed } } ``` No `sleep()` between polls Pass a `timeout` to `ggui_consume` (recommended: `15` or `25` seconds for chat agents — `25` is the maximum; the server rejects anything above 25 with `INVALID_PARAMS`) so the server long-polls. A busy `while` loop without a timeout — or with a hand-rolled `setTimeout` between calls — burns budget and adds latency. ## What the user sees [Section titled “What the user sees”](#what-the-user-sees) The agent renders the form into whatever MCP-Apps host the user is in — inline in claude.ai / Claude Desktop, or in your own app via ``. The user fills it in and submits; the agent reads the typed result off `ggui_consume`: ```plaintext Rating: 4/5 — Great product, would love dark-mode support! ``` There is no URL to hand the user — the render is an MCP-Apps resource the host mounts. (For local development without an MCP-Apps host, the operator console bundled with `ggui serve` can display the render for debugging.) ## Related [Section titled “Related”](#related) * [Examples → Claude Agent](/examples/claude-agent/) — full runnable Claude Agent SDK + ggui MCP example * [MCP protocol reference](/api/mcp-protocol/) — wire-level `ggui_handshake` / `ggui_render` / `ggui_consume` shapes * [Event system](/architecture/event-system/) — `actionSpec`-driven flow and the `ConsumeEventEntry` shape * [Multi-step wizard](/cookbook/multi-step-wizard/) — chain forms across successive renders * [Glossary](/glossary/) — `render`, `contract`, `envelope`, `blueprint` # Multi-Step Wizard > Let the LLM sequence a back-navigable wizard by minting a fresh render per step and prefilling on back-navigation. Wizards in ggui mint a **fresh GguiSession per step** (each keyed by its own `sessionId`). Each step is its own `handshake → render → consume` round-trip; back-navigation re-renders the prior step with the prior `actionData` plumbed in as `props.prefill`. ## Pattern [Section titled “Pattern”](#pattern) 1. The host opens an MCP session against the ggui server and exposes the `ggui_*` tools to the LLM. No wrapper SDK in the agent process. 2. You describe the wizard once in the user prompt and define one typed `defineContract` per step. 3. The LLM autonomously sequences: `ggui_handshake` → `ggui_render` → `ggui_consume` → react on `intent` → next step’s `ggui_handshake` → `ggui_render` → … . 4. If a consume entry’s `intent` is `"back"`, the LLM re-handshakes the prior step with `props.prefill` carrying the prior `actionData` so values are restored. ## LLM-driven flow (canonical — Claude Agent SDK) [Section titled “LLM-driven flow (canonical — Claude Agent SDK)”](#llm-driven-flow-canonical--claude-agent-sdk) Configure a Claude Agent SDK host with the ggui MCP server, allow the `ggui_*` tools, and ship a wizard-shaped prompt. The model does the rest. ```typescript import { query } from "@anthropic-ai/claude-agent-sdk"; import { GGUI_AGENT_SYSTEM_PROMPT, defineContract } from "@ggui-ai/protocol"; // One contract per step. `defineContract({...} as const)` infers TS payload // types from the JSON Schemas — no parallel interface definitions. // A DataContract declares data flow only (propsSpec / actionSpec / // streamSpec / contextSpec) — there are no `name` or `layout` fields. // The step header ("Step 1 of 3 — Personal Information") travels as the // handshake `intent` (and, for finer aim, `blueprintDraft.variance.seedPrompt`). const personalInfoContract = defineContract({ actionSpec: { submit: { label: "Next", schema: { type: "object", required: ["fullName", "email", "phone"], properties: { fullName: { type: "string" }, email: { type: "string", format: "email" }, phone: { type: "string" }, }, }, }, }, } as const); // ... companyInfoContract + reviewContract defined similarly (also expose a // "back" actionSpec entry on step 2 and 3). for await (const event of query({ prompt: `Walk me through a 3-step onboarding wizard. Step 1 (Personal Info): use this contract verbatim ${JSON.stringify(personalInfoContract)} Step 2 (Company Info, with Back): use this contract verbatim ${JSON.stringify(companyInfoContract)} Step 3 (Review & Confirm): use this contract verbatim ${JSON.stringify(reviewContract)} Render step 3 with props.summary = {personal, company} so the summary can render. Navigation rules: - After each ggui_render, call ggui_consume and inspect events[].intent. - intent === "submit": advance to the next step's handshake + render, threading prior data via the render's props. - intent === "back": re-handshake the prior step's contract with props.prefill = priorActionData so values are restored. - After step 3 submit, simply stop — renders decay implicitly via TTL.`, options: { model: "claude-haiku-4-5", systemPrompt: GGUI_AGENT_SYSTEM_PROMPT, mcpServers: { ggui: { type: "http", url: process.env.GGUI_MCP_URL!, // e.g. http://127.0.0.1:6781/mcp headers: { Authorization: `Bearer ${process.env.GGUI_API_KEY!}` }, }, }, allowedTools: [ "mcp__ggui__ggui_handshake", "mcp__ggui__ggui_render", "mcp__ggui__ggui_consume", ], tools: [], strictMcpConfig: true, }, })) { // Inspect events for logging; the LLM drives each render autonomously. if (event.type === "assistant") console.log(event.message); } ``` ## Manual orchestration (raw MCP, no Claude in the loop) [Section titled “Manual orchestration (raw MCP, no Claude in the loop)”](#manual-orchestration-raw-mcp-no-claude-in-the-loop) When you need explicit control over each step — testing, deterministic playback, non-LLM driver — open a raw MCP session and call `ggui_*` tools yourself. ```typescript import { Client } from "@modelcontextprotocol/sdk/client/index.js"; import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"; import { defineContract } from "@ggui-ai/protocol"; const transport = new StreamableHTTPClientTransport(new URL(process.env.GGUI_MCP_URL!), { requestInit: { headers: { Authorization: `Bearer ${process.env.GGUI_API_KEY!}` } }, }); const mcp = new Client({ name: "wizard-driver", version: "1.0.0" }); await mcp.connect(transport); async function call(name: string, args: unknown): Promise { const res = await mcp.callTool({ name, arguments: args as Record }); return JSON.parse((res.content[0] as { text: string }).text) as T; } async function step( contract: unknown, intent: string, prefill?: Record ): Promise<{ intent: TIntent; actionData: unknown; sessionId: string }> { // ggui_handshake({ intent, blueprintDraft }) → { handshakeId, action, suggestion } const hs = await call<{ handshakeId: string }>("ggui_handshake", { intent, blueprintDraft: { contract }, }); // ggui_render({ handshakeId, props }) — props is REQUIRED (pass {} when none). const { sessionId } = await call<{ sessionId: string }>("ggui_render", { handshakeId: hs.handshakeId, props: prefill ? { prefill } : {}, }); // Long-poll ggui_consume until the user submits or goes back. for (;;) { const { events, status } = await call<{ events: Array<{ intent: string; actionData: unknown }>; status: "active" | "expired"; }>("ggui_consume", { sessionId, timeout: 25 }); // `intent` is the actionSpec key the iframe dispatched against — "back" // is its own entry, not a sub-field of "submit". const entry = events.find((e) => e.intent === "back" || e.intent === "submit"); if (entry) return { ...(entry as { intent: TIntent; actionData: unknown }), sessionId }; if (status === "expired") throw new Error("render expired before a terminal action"); } } // Step 1 const personal = await step<"submit">( personalInfoContract, "Onboarding step 1 of 3 — personal info" ); // Step 2 with back handling let company: { intent: "submit"; actionData: unknown } | null = null; while (!company) { const r = await step<"submit" | "back">( companyInfoContract, "Onboarding step 2 of 3 — company info" ); if (r.intent === "back") { // Re-render step 1 with the prior actionData as prefill — a fresh sessionId // is minted; the prior render decays via TTL on its own. await step<"submit">( personalInfoContract, "Onboarding step 1 of 3 — personal info (revisit)", personal.actionData as Record ); continue; } company = r as { intent: "submit"; actionData: unknown }; } // No explicit close — the render decays implicitly via TTL after step 3 submit. ``` ## Step lineage [Section titled “Step lineage”](#step-lineage) ```plaintext Step 1 render: sessionId=r_p1 (personal info) Step 2 render: sessionId=r_c1 (company info) ← user sees Company User clicks Back: -- no pop -- (r_c1 decays via TTL) Step 1 revisit: sessionId=r_p2 (prefilled with prior personal data) Step 2 revisit: sessionId=r_c2 Step 3: sessionId=r_r1 (review & confirm) ``` Each step is an independent render with its own `sessionId`. There is no stack — renders are flat. Prior renders decay via TTL after the agent moves on. ## Inspecting a session’s state [Section titled “Inspecting a session’s state”](#inspecting-a-sessions-state) `ggui_get_session` returns the full `GguiSession` (id, appId, status, eventSequence, timestamps, plus the spec fields — propsSpec/actionSpec/contextSpec/streamSpec) — useful for debugging or for a driver that needs to know whether a session is still active. ```typescript const state = await call<{ id: string; status: string }>("ggui_get_session", { sessionId: company!.sessionId, }); console.log(`Render status: ${state.status}`); ``` ## See also [Section titled “See also”](#see-also) * [Claude Agent example](/examples/claude-agent/) — end-to-end LLM-driven loop wired to a ggui MCP server * [MCP protocol reference](/api/mcp-protocol/) — full `ggui_*` tool signatures * [GguiSession](/glossary/#gguisession-a-render) — the unit minted by each step * [Feedback Form](/cookbook/feedback-form/) — single-step variant of the same pattern # Real-Time Dashboard > Stream live data into a generated UI by declaring a streamSpec channel on the contract and pushing updates with ggui_emit. The iframe owns the live channel; your host app just mounts the render. Live data in ggui is a **contract concern**, not a host-app concern. You don’t open a WebSocket in your React app and feed events into the render. Instead: 1. The agent declares a **`streamSpec`** channel on the contract — a typed, named live channel. 2. The agent renders the contract once, then pushes updates with **`ggui_emit`**. 3. The **generated component inside the iframe** subscribes to that channel and repaints as deliveries arrive. The iframe-runtime owns the channel transport (it picks WebSocket or polling per channel). Your host app does nothing dashboard-specific: it mounts the render with `` (via `useMcpAppsChat`) like any other ggui UI. The live updates flow **inside** the sandboxed iframe — they never pass through your host code. ## 1. Declare a `streamSpec` channel [Section titled “1. Declare a streamSpec channel”](#1-declare-a-streamspec-channel) A `streamSpec` is a flat `Record` on the contract. Each channel declares a JSON Schema its payloads must satisfy, plus optional accumulation + replay behavior: ```typescript const contract = { // What the component shows initially (validated like any props). propsSpec: { properties: { title: { schema: { type: "string" }, required: true }, }, }, // Live channels. Payloads on `metrics` must match its schema. streamSpec: { metrics: { description: "Live throughput + error-rate samples for the dashboard.", schema: { type: "object", properties: { ts: { type: "string" }, rps: { type: "number" }, errorRate: { type: "number" }, }, required: ["ts", "rps"], }, mode: "append", // accumulate each delivery into a series replay: "all", // a late-subscribing iframe gets the full backlog complete: true, // allow a terminal ggui_emit({ complete: true }) }, }, }; ``` | Channel field | Meaning | | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `schema` | **Required.** JSON Schema every payload on this channel must satisfy. `ggui_emit` validates against it. | | `mode` | `"append"` accumulates deliveries into a series (a feed / chart); `"replace"` keeps only the latest (a single live value). Optional (default `"append"`). | | `replay` | What a freshly-mounted iframe receives: `"all"` (full backlog), `"latest"` (last delivery only), `"none"`. Optional (default `"none"`). | | `complete` | Declare `complete: true` to allow a terminal `ggui_emit({ complete: true })` that closes the channel; undeclared channels reject it. Optional. | | `description` | Natural-language hint that steers how the generator wires the component to the channel. Optional but recommended. | | `source` | `{ tool, args? }` — declare a **pull** channel the runtime polls instead of you pushing. See [Pull channels](#pull-channels-source). | The example’s `replay: "all"` and `complete: true` are both explicit opt-ins on top of the defaults. ## 2. Render, then emit [Section titled “2. Render, then emit”](#2-render-then-emit) Negotiate + materialize the contract through the normal `ggui_handshake` → `ggui_render` flow, then push deliveries with `ggui_emit`. Payloads validate against `streamSpec[channel].schema`; a final `complete: true` closes the channel (allowed because the declaration above opted in with `complete: true`). ```typescript import { Client } from "@modelcontextprotocol/sdk/client/index.js"; import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"; const client = new Client({ name: "dashboard-agent", version: "1.0.0" }); await client.connect( new StreamableHTTPClientTransport(new URL("http://127.0.0.1:6781/mcp"), { requestInit: { headers: { Authorization: "Bearer dev" } }, }) ); // Negotiate a blueprint for the dashboard contract. const handshake = await client.callTool({ name: "ggui_handshake", arguments: { intent: "Live ops dashboard — throughput + error rate", blueprintDraft: { contract }, }, }); const { handshakeId } = handshake.structuredContent as { handshakeId: string }; // Materialize it. `props` is REQUIRED — pass the initial values. const render = await client.callTool({ name: "ggui_render", arguments: { handshakeId, props: { title: "Ops — us-east-1" } }, }); const { sessionId } = render.structuredContent as { sessionId: string }; // Stubs — swap in your real metric source. const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms)); const sample = () => 100 + Math.random() * 50; const sampleErr = () => Math.random() * 0.05; // Push live deliveries on the declared channel. for (let i = 0; i < 100; i++) { await client.callTool({ name: "ggui_emit", arguments: { sessionId, channel: "metrics", payload: { ts: new Date().toISOString(), rps: sample(), errorRate: sampleErr() }, }, }); await sleep(1000); } // Close the channel — subsequent emits on it reject. await client.callTool({ name: "ggui_emit", arguments: { sessionId, channel: "metrics", payload: {}, complete: true }, }); ``` ## 3. Host side: just mount the render [Section titled “3. Host side: just mount the render”](#3-host-side-just-mount-the-render) There is no dashboard-specific host code. The render arrives as an MCP-Apps resource on the agent’s tool result; your web app drives the conversation with `useMcpAppsChat` and mounts each render with ``. The generated component subscribes to the `metrics` channel itself, and the iframe-runtime delivers every `ggui_emit` into it — your host never sees the channel frames. ```tsx import { AppRenderer } from "@mcp-ui/client"; import { useMcpAppsChat } from "@ggui-ai/react/chat-helpers"; function Dashboard({ agentUrl }: { agentUrl: string }) { const { sessions, handleAppMessage } = useMcpAppsChat({ chatEndpoint: `${agentUrl}/agent`, }); // Mount the latest render with ; live `metrics` deliveries // repaint the chart INSIDE the iframe. See the React SDK page for the // full sandbox + relay wiring. } ``` See [React SDK](/sdk/react/) for the complete `` host contract (sandbox-proxy origin + `onReadResource` / `onCallTool` relay + `onMessage`), and the [`ggui-basic-web`](https://github.com/ggui-ai/ggui/tree/main/samples/apps/ggui-basic-web) sample for a runnable host. ## Pull channels (`source`) [Section titled “Pull channels (source)”](#pull-channels-source) The example above is a **push** channel — the agent actively emits. For data the runtime should fetch on its own cadence, declare a `source` instead and skip `ggui_emit` entirely: ```typescript streamSpec: { orders: { description: "Open orders, refreshed from the orders tool.", schema: { type: "object", properties: { id: { type: "string" }, total: { type: "number" } } }, source: { tool: "list_open_orders", args: { region: "us-east-1" } }, }, } ``` `source.tool` MUST resolve to a tool the contract declares in its `agentCapabilities.tools` (a cross-reference the contract linter enforces). The iframe-runtime polls that tool and feeds results into the channel; the agent declares the channel and renders, but never pushes. ## See also [Section titled “See also”](#see-also) * [React SDK](/sdk/react/) — `` + `useMcpAppsChat`, the host render-hosting surface * [MCP protocol reference](/api/mcp-protocol/) — `ggui_handshake`, `ggui_render`, `ggui_emit` request/response shapes * [Data vs Behavior](https://github.com/ggui-ai/ggui/blob/main/docs/principles/data-vs-behavior.md) — why live data is a contract field and rendering behavior is component code * [`ggui-basic-web` sample](https://github.com/ggui-ai/ggui/tree/main/samples/apps/ggui-basic-web) — a runnable MCP-Apps host # Testing ggui Integrations > Mock the MCP transport for agent-side unit tests and assert the tool calls your agent makes, without a real LLM round-trip. ggui’s agent surface has a dedicated mock layer so you never need a live `mcp.ggui.ai` (or self-hosted `ggui serve`) connection in unit tests: * **Agent side** — mock the MCP transport (not a wrapper SDK) and assert the tool calls your agent makes. Integration tests against a live endpoint belong in a separate tier — see [Self-Hosted Reference Deploys](/self-hosted/reference-deploys/) for spinning up a throwaway stack. ## Agent side: mock the MCP transport [Section titled “Agent side: mock the MCP transport”](#agent-side-mock-the-mcp-transport) ggui is consumed over standard MCP, so the right place to draw the test boundary is at the **MCP transport**, not at a wrapper SDK. Stub the tool-call responses your agent expects and assert against the call log — your agent code stays unmodified between test and production. ### With `@modelcontextprotocol/sdk` — stub `Client.callTool` [Section titled “With @modelcontextprotocol/sdk — stub Client.callTool”](#with-modelcontextprotocolsdk--stub-clientcalltool) If your agent talks to ggui through the canonical MCP `Client`, stub `callTool` and seed the responses keyed by tool name. A unit-test fixture only needs the fields your agent actually reads, so each builder returns a `Pick<>` of the real protocol type (`GguiHandshakeOutput`, `GguiRenderOutput`, `GguiConsumeOutput` from `@ggui-ai/protocol`) — keeping the field names and shapes wire-faithful without hand-rolling every required field of the live envelope. ```typescript import { describe, it, expect, beforeEach, vi } from "vitest"; import { Client } from "@modelcontextprotocol/sdk/client/index.js"; import type { GguiHandshakeOutput, GguiRenderOutput, GguiConsumeOutput, ConsumeEventEntry, } from "@ggui-ai/protocol"; function makeMockMcpClient() { const callLog: Array<{ name: string; arguments: unknown }> = []; const responses = new Map(); let lastSessionId: string | null = null; const renderEvents = new Map(); const renderStatus = new Map(); responses.set( "ggui_handshake", (): Pick => ({ handshakeId: `h_${Date.now()}`, action: "create", }) ); responses.set( "ggui_render", (): Pick => { const sessionId = `rnd_${Date.now()}`; lastSessionId = sessionId; renderEvents.set(sessionId, []); renderStatus.set(sessionId, "active"); return { sessionId, // Spec-canonical MCP-Apps entry point. There is NO clickable // `url` on the wire — the host mounts the `ui://ggui/render/{id}` // iframe resource. (A dead `url` had the model hallucinating // links that resolve nowhere, so it was removed.) resourceUri: `ui://ggui/render/${sessionId}`, action: "create", }; } ); responses.set("ggui_consume", (args: { sessionId: string }): GguiConsumeOutput => { const events = renderEvents.get(args.sessionId) ?? []; renderEvents.set(args.sessionId, []); return { events, status: renderStatus.get(args.sessionId) ?? "active", }; }); const client = { callTool: vi.fn(async ({ name, arguments: args }) => { callLog.push({ name, arguments: args }); const handler = responses.get(name); if (!handler) { // JSON-RPC -32601: Method not found — matches the live server. throw new Error(`MCP tool not found: ${name}`); } const result = typeof handler === "function" ? handler(args) : handler; // MCP wraps tool output in { content: [...], structuredContent: ... }. return { content: [{ type: "text", text: JSON.stringify(result) }], structuredContent: result, }; }), } as unknown as Client; return { client, callLog, // Simulate a user gesture appearing on the consume pipe. simulateSubmit(sessionId: string, data: ConsumeEventEntry["actionData"]) { const events = renderEvents.get(sessionId) ?? []; events.push({ type: "action", sessionId, intent: "submit", actionData: data, uiContext: {}, actionId: "mockactn", firedAt: new Date().toISOString(), }); renderEvents.set(sessionId, events); }, // Status semantics match the canonical protocol: `active` = more events // may arrive; `expired` = TTL elapsed. Flip terminal state explicitly. simulateExpire(sessionId: string) { renderStatus.set(sessionId, "expired"); }, }; } ``` ### Driving the mock from a test [Section titled “Driving the mock from a test”](#driving-the-mock-from-a-test) ```typescript describe("feedback agent", () => { let mock: ReturnType; beforeEach(() => { mock = makeMockMcpClient(); }); it("collects user feedback end-to-end", async () => { const handshake = await mock.client.callTool({ name: "ggui_handshake", arguments: { intent: "Collect feedback" }, }); const { handshakeId } = handshake.structuredContent as GguiHandshakeOutput; const render = await mock.client.callTool({ name: "ggui_render", // `props` is REQUIRED on ggui_render — pass `{}` when the agreed // contract declares no propsSpec. arguments: { handshakeId, props: {} }, }); const { sessionId, resourceUri } = render.structuredContent as GguiRenderOutput; // The render's entry point is the spec-canonical MCP-Apps resource // URI the host mounts — not a clickable link. expect(resourceUri).toMatch(/^ui:\/\/ggui\/render\//); // Pretend the user filled in the form. mock.simulateSubmit(sessionId, { rating: 5, comments: "Great!" }); const consume = await mock.client.callTool({ name: "ggui_consume", arguments: { sessionId }, }); const { events, status } = consume.structuredContent as GguiConsumeOutput; expect(status).toBe("active"); expect(events[0].actionData).toEqual({ rating: 5, comments: "Great!" }); // Assert the agent issued exactly the expected tool-call sequence. expect(mock.callLog.map((c) => c.name)).toEqual([ "ggui_handshake", "ggui_render", "ggui_consume", ]); }); }); ``` `actionData`, not `payload` `ConsumeEventEntry` carries gesture data on `actionData` (the consume pipe is the agent-facing view of an `ActionEnvelope` from the live channel). `payload` is the live-channel wire field on the raw envelope. Asserting against `events[0].payload` will silently return `undefined`. ### With Claude Agent SDK — stub `mcpServers` [Section titled “With Claude Agent SDK — stub mcpServers”](#with-claude-agent-sdk--stub-mcpservers) Consumers using `@anthropic-ai/claude-agent-sdk` typically pass an `mcpServers` config to `query()`. For unit tests, supply an in-memory server entry that returns canned tool responses instead of dialling `mcp.ggui.ai`. Use the SDK’s `createSdkMcpServer` (or the SDK-specific test helper) and register tools that produce the same structured payloads shown above. The principle is identical: stub at the MCP transport surface so your agent prompt, tool-loop logic, and consume-pipe handling exercise unchanged. ### With raw HTTP — stub `fetch` [Section titled “With raw HTTP — stub fetch”](#with-raw-http--stub-fetch) If your agent talks to a self-hosted `ggui serve` over plain HTTP (`http://127.0.0.1:6781/mcp`), `vi.spyOn(global, "fetch")` (or `msw`) is the right boundary. Assert request URL + JSON-RPC method, and return the matching `structuredContent` payload. ### Asserting errors [Section titled “Asserting errors”](#asserting-errors) ggui surfaces failures at protocol level — there are no SDK-specific error classes to import. Assert against **JSON-RPC error codes** (`-32601` method-not-found, `-32602` invalid-params, etc.) or **HTTP status codes** (`401 Unauthorized`, `408 Request Timeout`, `429 Too Many Requests`), depending on your transport. ```typescript it("surfaces auth errors", async () => { const failingClient = { callTool: async () => { // Mirror the wire shape: an HTTP-401 surface from the gateway becomes a // JSON-RPC error on the MCP client. const err = new Error("Unauthorized") as Error & { code?: number }; err.code = -32000; // JSON-RPC server-error range; httpStatus 401 upstream. throw err; }, }; await expect( failingClient.callTool({ name: "ggui_handshake", arguments: {} }) ).rejects.toMatchObject({ code: -32000 }); }); ``` See [Error Handling](/cookbook/error-handling/) for retry, fallback, and graceful-degradation patterns built on these protocol-level signals. *** ## What not to test [Section titled “What not to test”](#what-not-to-test) LLM-generated component code is non-deterministic — assert **behavior**, not DOM structure. Pin contracts (via `defineContract` + `useContract`) and test your agent’s tool-call sequence. Leave the visual layer to live snapshots or a separate generation-quality tier. See also: [@ggui-ai/react](/sdk/react/) · [MCP Protocol](/api/mcp-protocol/) · [Troubleshooting](/troubleshooting/). # Design Tokens > Visual reference for the DTCG design tokens that ggui primitives consume — colors, spacing, typography, radius, and shadows. Every `@ggui-ai/design` primitive — and by extension every gadget that ships with the OSS renderer — reads its visual state from [DTCG](https://design-tokens.github.io/community-group/format/) tokens exposed as CSS custom properties. Tokens themselves need no runtime: override the variables on any ancestor and the cascade does the rest on the next paint. Operator theming builds on these same variables: `ggui.json#theme` selects one of the shipped presets (or a DTCG file), and per-app overlays are validated `--ggui-*` maps injected after the base token block, so a partial overlay keeps token defaults. Agents can enumerate presets with `ggui_list_themes` and pick one per render via `ggui_render({themeId})` — see [Custom Theming](/cookbook/custom-theming/). ```css /* Every primitive uses var(--ggui-…) with a hardcoded fallback */ color: var(--ggui-color-primary-600, #0284c7); padding: var(--ggui-spacing-md, 16px); border-radius: var(--ggui-shape-radius-md, 8px); ``` Caution The swatch/scale tables below are rendered from a hand-maintained snapshot at `apps/docs/src/data/tokens.ts` (Astro can’t import the React design package directly). If a value here disagrees with `packages/design/src/themes/defaults/light.ts`, the design package is authoritative. *** ## Colors [Section titled “Colors”](#colors) ### Color Palettes [Section titled “Color Palettes”](#color-palettes) #### Primary (Sky Blue) 50 `#f0f9ff` `--ggui-color-primary-50` 100 `#e0f2fe` `--ggui-color-primary-100` 200 `#bae6fd` `--ggui-color-primary-200` 300 `#7dd3fc` `--ggui-color-primary-300` 400 `#38bdf8` `--ggui-color-primary-400` 500 `#0ea5e9` `--ggui-color-primary-500` 600 `#0284c7` `--ggui-color-primary-600` 700 `#0369a1` `--ggui-color-primary-700` 800 `#075985` `--ggui-color-primary-800` 900 `#0c4a6e` `--ggui-color-primary-900` #### Gray 50 `#f9fafb` `--ggui-color-neutral-50` 100 `#f3f4f6` `--ggui-color-neutral-100` 200 `#e5e7eb` `--ggui-color-neutral-200` 300 `#d1d5db` `--ggui-color-neutral-300` 400 `#9ca3af` `--ggui-color-neutral-400` 500 `#6b7280` `--ggui-color-neutral-500` 600 `#4b5563` `--ggui-color-neutral-600` 700 `#374151` `--ggui-color-neutral-700` 800 `#1f2937` `--ggui-color-neutral-800` 900 `#111827` `--ggui-color-neutral-900` #### Success 50 `#f0fdf4` `--ggui-color-success-50` 100 `#dcfce7` `--ggui-color-success-100` 200 `#bbf7d0` `--ggui-color-success-200` 500 `#22c55e` `--ggui-color-success-500` 600 `#16a34a` `--ggui-color-success-600` 700 `#15803d` `--ggui-color-success-700` 800 `#166534` `--ggui-color-success-800` #### Warning 50 `#fffbeb` `--ggui-color-warning-50` 100 `#fef3c7` `--ggui-color-warning-100` 200 `#fde68a` `--ggui-color-warning-200` 500 `#f59e0b` `--ggui-color-warning-500` 600 `#d97706` `--ggui-color-warning-600` 700 `#b45309` `--ggui-color-warning-700` 800 `#92400e` `--ggui-color-warning-800` #### Error 50 `#fef2f2` `--ggui-color-error-50` 100 `#fee2e2` `--ggui-color-error-100` 200 `#fecaca` `--ggui-color-error-200` 500 `#ef4444` `--ggui-color-error-500` 600 `#dc2626` `--ggui-color-error-600` 700 `#b91c1c` `--ggui-color-error-700` 800 `#991b1b` `--ggui-color-error-800` #### Info 50 `#ecfeff` `--ggui-color-info-50` 100 `#cffafe` `--ggui-color-info-100` 200 `#a5f3fc` `--ggui-color-info-200` 500 `#06b6d4` `--ggui-color-info-500` 600 `#0891b2` `--ggui-color-info-600` 700 `#0e7490` `--ggui-color-info-700` 800 `#155e75` `--ggui-color-info-800` ### Semantic Colors [Section titled “Semantic Colors”](#semantic-colors) These tokens map to specific UI roles and adapt between light and dark themes. **Surface**`#ffffff``--ggui-color-surface` **Surface Variant**`#f3f4f6``--ggui-color-surfaceVariant` **On Surface**`#111827``--ggui-color-onSurface` **On Surface Variant**`#6b7280``--ggui-color-onSurfaceVariant` **Outline**`#9ca3af``--ggui-color-outline` **Outline Variant**`#d1d5db``--ggui-color-outlineVariant` **Container**`#f9fafb``--ggui-color-container` **On Container**`#111827``--ggui-color-onContainer` ### Material Role Pairs [Section titled “Material Role Pairs”](#material-role-pairs) The canonical theme adds eight Material 3-inspired role pairs for surface/content layering. They sit alongside (and extend) the legacy text tokens — primitives use these to keep contrast right across nested surfaces. | CSS variable | Role | | ------------------------------- | ----------------------------------------------- | | `--ggui-color-surface` | Default page / sheet background | | `--ggui-color-onSurface` | Primary text and icons on `surface` | | `--ggui-color-surfaceVariant` | Subtle alternate background (cards, rails) | | `--ggui-color-onSurfaceVariant` | Secondary text/icons on `surfaceVariant` | | `--ggui-color-container` | Filled container (chips, banners, soft buttons) | | `--ggui-color-onContainer` | Text/icons on `container` | | `--ggui-color-outline` | Standard borders + dividers | | `--ggui-color-outlineVariant` | Faint borders, disabled outlines | *** ## Spacing [Section titled “Spacing”](#spacing) A consistent spacing scale ensures visual rhythm across all components. `xs` 4px `--ggui-spacing-xs` `sm` 8px `--ggui-spacing-sm` `md` 16px `--ggui-spacing-md` `lg` 24px `--ggui-spacing-lg` `xl` 32px `--ggui-spacing-xl` `2xl` 48px `--ggui-spacing-2xl` `3xl` 64px `--ggui-spacing-3xl` *** ## Typography [Section titled “Typography”](#typography) Canonical theme path: `font.{family,size,weight,lineHeight}.*`. Emitted as `--ggui-font-family-*`, `--ggui-font-size-*`, `--ggui-font-weight-*`, `--ggui-font-lineHeight-*`. #### Font Families The quick brown fox jumps over the lazy dog `Sans` `--ggui-typography-fontFamily-sans` The quick brown fox jumps over the lazy dog `Mono` `--ggui-typography-fontFamily-mono` #### Font Sizes `xs` 12px The quick brown fox `--ggui-typography-fontSize-xs` `sm` 14px The quick brown fox `--ggui-typography-fontSize-sm` `base` 16px The quick brown fox `--ggui-typography-fontSize-base` `lg` 18px The quick brown fox `--ggui-typography-fontSize-lg` `xl` 20px The quick brown fox `--ggui-typography-fontSize-xl` `2xl` 24px The quick brown fox `--ggui-typography-fontSize-2xl` `3xl` 30px The quick brown fox `--ggui-typography-fontSize-3xl` `4xl` 36px The quick brown fox `--ggui-typography-fontSize-4xl` #### Font Weights `Normal` The quick brown fox jumps over the lazy dog 400 `Medium` The quick brown fox jumps over the lazy dog 500 `Semibold` The quick brown fox jumps over the lazy dog 600 `Bold` The quick brown fox jumps over the lazy dog 700 #### Line Heights `Tight` Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 1.25 `Normal` Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 1.5 `Relaxed` Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 1.75 *** ## Border Radius [Section titled “Border Radius”](#border-radius) Canonical theme path: `shape.radius.*`. Emitted as `--ggui-shape-radius-{none,sm,md,lg,xl,2xl,full}`. `none`0 `--ggui-shape-radius-none` `sm`4px `--ggui-shape-radius-sm` `md`8px `--ggui-shape-radius-md` `lg`12px `--ggui-shape-radius-lg` `xl`16px `--ggui-shape-radius-xl` `2xl`24px `--ggui-shape-radius-2xl` `full`9999px `--ggui-shape-radius-full` *** ## Shadows [Section titled “Shadows”](#shadows) Canonical theme path: `shape.shadow.*`. Emitted as `--ggui-shape-shadow-{none,xs,sm,md,lg,xl,2xl}`. `none` `0 0 0 0 transparent` `--ggui-shape-shadow-none` `xs` `0 1px 2px 0 rgba(15, 23, 42, 0.04)` `--ggui-shape-shadow-xs` `sm` `0 1px 3px 0 rgba(15, 23, 42, 0.06)` `--ggui-shape-shadow-sm` `md` `0 8px 16px -4px rgba(15, 23, 42, 0.10)` `--ggui-shape-shadow-md` `lg` `0 16px 32px -8px rgba(15, 23, 42, 0.14)` `--ggui-shape-shadow-lg` `xl` `0 24px 48px -12px rgba(15, 23, 42, 0.18)` `--ggui-shape-shadow-xl` `2xl` `0 25px 50px -12px rgba(0, 0, 0, 0.25)` `--ggui-shape-shadow-2xl` *** ## Motion [Section titled “Motion”](#motion) The canonical `motion` group covers durations, easings, keyframes, and ready-made `transition` shorthands. Durations + transitions both surface as CSS custom properties; transitions are pre-composed so primitives can drop in a single `var(--ggui-motion-transition-…)` without rewriting the curve. | Variable | Typical value | When to use | | ------------------------------------ | ------------------------------------------- | -------------------------------------- | | `--ggui-motion-duration-instant` | `0ms` | Immediate state flips (no animation) | | `--ggui-motion-duration-fast` | `100ms` | Hover, focus, small icon swaps | | `--ggui-motion-duration-normal` | `200ms` | Default for color/opacity transitions | | `--ggui-motion-duration-slow` | `300ms` | Layout shifts, large fades | | `--ggui-motion-transition-colors` | `color/background-color/border-color 200ms` | Theme-aware color changes | | `--ggui-motion-transition-opacity` | `opacity 200ms` | Fades, show/hide | | `--ggui-motion-transition-transform` | `transform 200ms` | Translate/scale interactions | | `--ggui-motion-transition-all` | `all 200ms` | Catch-all when several properties move | Respect `accessibility.reducedMotion` — set durations to `0ms` (or override the transitions to `none`) when it’s `'reduce'`. *** ## Accessibility [Section titled “Accessibility”](#accessibility) Top-level `accessibility` tokens make a11y intent explicit instead of leaving it implicit in component styles. They emit as `--ggui-accessibility-*` and pair with the standard media queries. | Variable | Type | Notes | | ------------------------------------ | ----------------------------- | ------------------------------------------------- | | `--ggui-accessibility-focusRing` | shadow / outline shorthand | The focus indicator used by every primitive | | `--ggui-accessibility-reducedMotion` | `'no-preference' \| 'reduce'` | Mirror of `prefers-reduced-motion`; drives motion | | `--ggui-accessibility-highContrast` | `'standard' \| 'increased'` | Mirror of `prefers-contrast`; thickens borders | Override `focusRing` at the theme level to brand the focus indicator across every primitive at once. *** ## Z-Index [Section titled “Z-Index”](#z-index) A canonical layering scale prevents floating UIs from fighting each other. Values are unitless integers and increase with elevation. | Variable | Layer | Typical occupant | | ------------------------ | ------ | -------------------------------------- | | `--ggui-zIndex-hide` | `-1` | Off-screen / underlay | | `--ggui-zIndex-base` | `0` | Page content | | `--ggui-zIndex-docked` | `10` | Docked sidebars, sticky toolbars | | `--ggui-zIndex-dropdown` | `1000` | Menus, select popovers | | `--ggui-zIndex-sticky` | `1100` | Sticky table headers | | `--ggui-zIndex-banner` | `1200` | Announcement / cookie banners | | `--ggui-zIndex-overlay` | `1300` | Backdrop scrims | | `--ggui-zIndex-modal` | `1400` | Modal dialogs | | `--ggui-zIndex-popover` | `1500` | Floating popovers anchored to content | | `--ggui-zIndex-skipLink` | `1600` | Keyboard skip-link (must beat modals) | | `--ggui-zIndex-toast` | `1700` | Toast notifications | | `--ggui-zIndex-tooltip` | `1800` | Tooltips (topmost interactive element) | *** ## Using Tokens [Section titled “Using Tokens”](#using-tokens) ### In primitives [Section titled “In primitives”](#in-primitives) Nothing to wire — every primitive already consumes the tokens: ```tsx import { Button, Card, Input } from '@ggui-ai/design'; Submit ; ``` ### In your own components [Section titled “In your own components”](#in-your-own-components) Reference tokens by their CSS variable, with a hardcoded fallback for environments where the theme provider hasn’t loaded yet: ```css .my-component { background: var(--ggui-color-surface, #ffffff); padding: var(--ggui-spacing-md, 16px); border-radius: var(--ggui-shape-radius-lg, 12px); box-shadow: var(--ggui-shape-shadow-md, 0 8px 16px -4px rgba(15, 23, 42, 0.10)); font-family: var(--ggui-font-family-sans, system-ui, -apple-system, sans-serif); font-size: var(--ggui-font-size-sm, 14px); color: var(--ggui-color-onSurface, #111827); transition: var(--ggui-motion-transition-colors, color 200ms ease); } ``` ### Theming [Section titled “Theming”](#theming) Override on any element — `:root` for global, a wrapper for per-subtree: ```css :root { --ggui-color-primary-600: #7c3aed; /* Purple instead of sky blue */ --ggui-color-surface: #fefce8; /* Warm paper background */ --ggui-color-onSurface: #1f1410; /* Ink for the new surface */ --ggui-shape-radius-md: 16px; /* Pillier corners */ --ggui-motion-duration-normal: 240ms; /* Slightly more deliberate */ } ``` See [Custom Theming](/cookbook/custom-theming/) for the full recipe — global overrides, dark-mode pairs, and scoped subtrees. # Claude Agent > Drive ggui from Claude Agent SDK's tool-use loop — Claude calls ggui MCP tools directly, no client SDK in your code. This is the canonical Claude pattern for ggui. You wire ggui as an MCP server in Claude Agent SDK’s `mcpServers` config, hand Claude the ggui posture prompt (`GGUI_AGENT_SYSTEM_PROMPT`), and Claude decides when to call `ggui_handshake` / `ggui_render` / `ggui_consume` based on the tool descriptions it discovers via `tools/list`. **Zero ggui SDK code in your app** — Claude drives the protocol directly. A runnable version of this example lives at [`samples/agents/claude-agent-sdk/`](https://github.com/ggui-ai/ggui/tree/main/samples/agents/claude-agent-sdk). ## Install [Section titled “Install”](#install) ```bash npm install @anthropic-ai/claude-agent-sdk @ggui-ai/protocol ``` ```bash export ANTHROPIC_API_KEY="sk-ant-..." ``` ## Code [Section titled “Code”](#code) claude-agent.ts ```typescript import { query } from "@anthropic-ai/claude-agent-sdk"; import { GGUI_AGENT_SYSTEM_PROMPT } from "@ggui-ai/protocol"; // 1. Wire ggui as an MCP server. Claude Agent SDK will issue `tools/list` // against this URL on session start and discover every `ggui_*` tool. // `Bearer dev` authenticates because `ggui serve --dev-allow-all` accepts // any bearer — local dev only. const mcpServers = { ggui: { type: "http" as const, url: "http://127.0.0.1:6781/mcp", headers: { Authorization: "Bearer dev" }, }, }; // 2. Whitelist the ggui tools Claude is allowed to call. The SDK auto-namespaces // every tool as `mcp____`, so the prefix is `mcp__ggui__`. const GGUI_ALLOWED_TOOLS = [ "mcp__ggui__ggui_handshake", "mcp__ggui__ggui_render", "mcp__ggui__ggui_update", "mcp__ggui__ggui_emit", "mcp__ggui__ggui_consume", "mcp__ggui__ggui_get_session", ]; async function chat(userPrompt: string) { console.log(`\nUser: ${userPrompt}\n`); // 3. `query()` returns an AsyncGenerator of SDKMessage events. The SDK runs // the full tool-use loop internally — you just consume the stream. for await (const message of query({ prompt: userPrompt, options: { model: "claude-sonnet-4-6", mcpServers, allowedTools: GGUI_ALLOWED_TOOLS, // The posture-only canonical ggui prompt. Tells Claude *when* to reach // for a UI; tool descriptions tell it *how*. systemPrompt: GGUI_AGENT_SYSTEM_PROMPT, }, })) { if (message.type === "assistant") { for (const block of message.message.content) { if (block.type === "text") { process.stdout.write(block.text); } else if (block.type === "tool_use") { console.log(`\n[tool_use] ${block.name}`); } } } else if (message.type === "user") { // Tool results flow back as user-role messages from the SDK's perspective. for (const block of message.message.content) { if (block.type === "tool_result") { console.log(`[tool_result] ${block.tool_use_id}`); } } } else if (message.type === "result") { console.log(`\n\n[done] subtype=${message.subtype}`); } } } chat("I want to book a restaurant reservation for this weekend").catch(console.error); ``` ## Run [Section titled “Run”](#run) ```bash npx tsx claude-agent.ts ``` ## What you’ll see [Section titled “What you’ll see”](#what-youll-see) `query()` yields a stream of `SDKMessage` events. The shapes you’ll observe in a typical ggui turn: * **`system` (init)** — opening event listing the model, allowed tools, and MCP servers Claude discovered. * **`assistant`** — Claude’s response chunks. `content` is an array of blocks: * `text` — natural-language reply (streamed across multiple events). * `tool_use` — Claude invoking a ggui tool (e.g. `mcp__ggui__ggui_handshake`). The `input` field contains the tool arguments Claude generated. * `thinking` — extended-thinking blocks when reasoning is on. * **`user`** — tool results flowing back into the loop. `content[].type === "tool_result"` with `tool_use_id` pointing at the matching `tool_use`. * **`result`** — terminal event with `subtype` (`success`, `error_max_turns`, `error_during_execution`, …), `usage` totals, and `total_cost_usd`. A reservation booking typically streams: `system` → `assistant`(text + `tool_use:ggui_handshake`) → `user`(tool\_result) → `assistant`(`tool_use:ggui_render`) → `user`(tool\_result with `sessionId` + `resourceUri` — the host mounts the UI from the MCP-Apps resource) → \[user submits the form] → `assistant`(`tool_use:ggui_consume`) → `user`(tool\_result with submission data) → `assistant`(confirmation text) → `result`. ## Patterns worth stealing [Section titled “Patterns worth stealing”](#patterns-worth-stealing) * **Zero Agent Code.** Your file imports `query` and `GGUI_AGENT_SYSTEM_PROMPT` and lists tool names — nothing else. The protocol lives behind MCP; Claude reads tool descriptions and drives it directly. * **`GGUI_AGENT_SYSTEM_PROMPT` is posture, not instructions.** It tells Claude *when* to reach for a UI (structured input, choices, visual presentation). Per-tool semantics ship from the server in `tools/list` — you don’t restate them. * **Tool namespace is structural.** `mcp____` is non-negotiable; it’s how the SDK routes calls. Match the prefix exactly in `allowedTools`. * **Whitelist explicitly.** Omit `allowedTools` and Claude can call every tool the server exposes (including ops/protocol tools). The list above is the minimal agent-facing surface. * **Prompt caching is automatic** when the SDK detects a stable `systemPrompt` + `mcpServers` prefix across turns. No `cache_control` plumbing needed in your code. ## Related [Section titled “Related”](#related) * [`samples/agents/claude-agent-sdk/`](https://github.com/ggui-ai/ggui/tree/main/samples/agents/claude-agent-sdk) — runnable reference for this file * [OpenAI agent example](/examples/openai-agent/) — same shape, function-calling transport * [`GGUI_AGENT_SYSTEM_PROMPT` reference](/api/mcp-protocol/) — what’s in the posture prompt and why * [How it works](/how-it-works/) — what happens between `ggui_render` and the rendered UI # Gemini Agent > Wire Google Gemini's function-calling API to ggui via MCP — bridge ggui's MCP tools into Gemini function declarations and continue the conversation once the user submits. Wire ggui to Gemini’s function-calling API so the model can mint a UI mid-conversation, wait for the user to submit, and continue with the structured data. The pattern is a **thin bridge**: connect to ggui’s MCP server with the official `@modelcontextprotocol/sdk` client, then surface every MCP tool as a Gemini `FunctionDeclaration`. ## Setup [Section titled “Setup”](#setup) ```bash npm install @google/genai @modelcontextprotocol/sdk ``` ```bash export GEMINI_API_KEY="AIza..." ``` ## Code [Section titled “Code”](#code) gemini-agent.ts ```typescript import { GoogleGenAI } from "@google/genai"; import { Client } from "@modelcontextprotocol/sdk/client/index.js"; import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"; const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY! }); // 1. Connect to ggui over MCP (Streamable HTTP transport). `Bearer dev` // authenticates because `ggui serve --dev-allow-all` accepts any bearer — // local dev only. const mcpClient = new Client({ name: "gemini-ggui-agent", version: "0.1.0" }, {}); await mcpClient.connect( new StreamableHTTPClientTransport(new URL("http://127.0.0.1:6781/mcp"), { requestInit: { headers: { Authorization: "Bearer dev" }, }, }) ); // 2. Bridge MCP tools → Gemini function declarations. const { tools: mcpTools } = await mcpClient.listTools(); const geminiTools = [ { functionDeclarations: mcpTools.map((t) => ({ name: t.name, description: t.description, // Gemini takes JSON Schema as-is via parametersJsonSchema (NOT `parameters`). parametersJsonSchema: t.inputSchema, })), }, ]; // 3. Open a chat. `chats.create` keeps multi-turn state — reuse this handle. const chat = ai.chats.create({ model: "gemini-3.5-flash", config: { tools: geminiTools, systemInstruction: "You drive ggui MCP tools to render interactive UIs. Call the appropriate tool when you need to collect structured data from the user, then continue with their response.", }, }); async function run(userPrompt: string) { console.log(`\nUser: ${userPrompt}`); let response = await chat.sendMessage({ message: userPrompt }); // 4. Drain function calls until the model returns plain text. while (response.functionCalls?.length) { const functionResponses = await Promise.all( response.functionCalls.map(async (fc) => { const result = await mcpClient.callTool({ name: fc.name, arguments: fc.args, }); return { name: fc.name, response: { content: result.content } }; }) ); response = await chat.sendMessage({ message: functionResponses.map((fr) => ({ functionResponse: fr })), }); } console.log(`\nAssistant: ${response.text ?? "(no response)"}`); } await run("I need to schedule a meeting with my team for next week"); await mcpClient.close(); ``` ## Run [Section titled “Run”](#run) ```bash npx tsx gemini-agent.ts ``` ## What Happens [Section titled “What Happens”](#what-happens) 1. You ask Gemini to schedule a team meeting. 2. Gemini calls `ggui_handshake({intent, blueprintDraft})` and gets a `handshakeId` + a `suggestion` (the server matches a [blueprint](/glossary/) or synthesizes one). 3. Gemini calls `ggui_render({handshakeId, props})`; the result carries `{sessionId, resourceUri}` — your host mounts the UI from that MCP-Apps resource. 4. Gemini calls `ggui_consume({sessionId, timeout})`; when the user submits, the `events` array delivers `{intent, actionData, uiContext}`. 5. Gemini replies with plain text. ## Gemini-specific notes [Section titled “Gemini-specific notes”](#gemini-specific-notes) * Function schemas use **`parametersJsonSchema`** (JSON Schema passthrough), not the older `parameters` (subset-of-OpenAPI) field. MCP tools expose `inputSchema` as JSON Schema — pass it through unchanged. * Tools are grouped under `functionDeclarations`; tool replies are `functionResponse` parts inside the `message: PartListUnion`. * Multi-turn state lives on the `ai.chats.create()` handle — reuse `chat` across turns. Don’t call `models.generateContent` for chat flows or you lose history. * Tool-loop latency tip: set `generateContentConfig.thinkingConfig.thinkingLevel` to `MINIMAL` — high thinking levels add tens of seconds per tool turn. * The bridge is generic: every tool ggui exposes over MCP becomes a Gemini function declaration automatically. No per-tool wrapper code. ## Next [Section titled “Next”](#next) * [Claude Agent example](/examples/claude-agent/) — same MCP bridge pattern with Anthropic’s SDK (native MCP server support — no manual bridge needed). * [OpenAI Agent example](/examples/openai-agent/) — same flow with OpenAI function calling. * [How it works](/how-it-works/) — the three channels (bootstrap, MCP, WebSocket) and envelope shapes. # Generic MCP / Raw HTTP > Drive ggui from any MCP-compatible agent or via raw JSON-RPC over HTTP — official MCP client library, and language-agnostic curl/Python recipes. Use ggui from any language or framework — through the official MCP TypeScript client, or raw HTTP with JSON-RPC. There is no ggui-specific wrapper SDK: every endpoint is a vanilla MCP server, so any spec-compliant client works. > Building on top of the Claude Agent SDK instead? See [Claude Agent SDK example](/examples/claude-agent/) — it wires ggui in as a stock MCP server with no extra glue. ## Using the MCP client library (TypeScript) [Section titled “Using the MCP client library (TypeScript)”](#using-the-mcp-client-library-typescript) The official `@modelcontextprotocol/sdk` package speaks the MCP wire end-to-end. Point its `StreamableHTTPClientTransport` at `http://127.0.0.1:6781/mcp` and call ggui’s tools by name. ```typescript import { Client } from "@modelcontextprotocol/sdk/client/index.js"; import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"; const client = new Client({ name: "my-agent", version: "0.1.0" }, {}); // `Bearer dev` authenticates because `ggui serve --dev-allow-all` accepts // any bearer — local dev only. await client.connect( new StreamableHTTPClientTransport(new URL("http://127.0.0.1:6781/mcp"), { requestInit: { headers: { Authorization: "Bearer dev", }, }, }) ); // Discover the tool surface. const { tools } = await client.listTools(); console.log( "Available tools:", tools.map((t) => t.name) ); // → ['ggui_handshake', 'ggui_render', 'ggui_consume', // 'ggui_update', 'ggui_get_session', 'ggui_list_sessions', // 'ggui_list_gadgets', 'ggui_list_themes', 'ggui_emit', // 'ggui_list_featured_blueprints', 'ggui_search_blueprints', // 'ggui_render_blueprint'] // handshake → render at the raw MCP layer. const handshakeResult = await client.callTool({ name: "ggui_handshake", arguments: { intent: "feedback form", blueprintDraft: { contract: { /* DataContract — propsSpec, actionSpec, contextSpec, streamSpec */ }, }, }, }); const handshake = JSON.parse(handshakeResult.content[0].text) as { handshakeId: string; suggestion: { origin: "cache" | "agent" | "synth"; blueprintMeta: { blueprintId?: string; contractHash: string }; }; }; const renderResult = await client.callTool({ name: "ggui_render", arguments: { handshakeId: handshake.handshakeId, props: {}, }, }); const { sessionId, resourceUri } = JSON.parse(renderResult.content[0].text) as { sessionId: string; resourceUri: string; }; console.log("Render:", sessionId, "→", resourceUri); ``` The three-noun model: a **tool** is what the agent calls (the MCP methods above); a **gadget** is a renderer-side capability the LLM may opt into when generating the UI; a **blueprint** is a cached recipe the handshake returns as a `suggestion` (with `origin: 'cache' | 'agent' | 'synth'`) — accepting it on render reuses the provisional `blueprintId` and skips regeneration. Need a higher-level Claude-flavored shortcut? The [Claude Agent SDK example](/examples/claude-agent/) registers ggui as an MCP server and lets the agent loop drive `ggui_handshake` / `ggui_render` / `ggui_consume` on its own. *** ## Using raw HTTP (no SDK) [Section titled “Using raw HTTP (no SDK)”](#using-raw-http-no-sdk) Call MCP over JSON-RPC from any language. The flow is **`initialize` → `ggui_handshake` → `ggui_render` → `ggui_consume`** (poll, keyed by `sessionId`). Renders decay implicitly via TTL — no explicit close. ### Hosted vs self-hosted — what to swap [Section titled “Hosted vs self-hosted — what to swap”](#hosted-vs-self-hosted--what-to-swap) Every `curl` below targets a local `ggui serve --dev-allow-all`. To drive the hosted endpoint (coming soon) instead, swap two values: | What | Self-hosted (`ggui serve`) — default | Hosted (`mcp.ggui.ai`) — coming soon | | --------------- | -------------------------------------------------------------------- | ------------------------------------ | | Endpoint URL | `http://127.0.0.1:6781/mcp` | `https://mcp.ggui.ai/apps/` | | `Authorization` | `Bearer dev` (requires `ggui serve --dev-allow-all`; local dev only) | `Bearer ggui_user_...` | `--dev-allow-all` is for local dev only `--dev-allow-all` accepts any bearer — keep the default `127.0.0.1` bind and never expose it publicly. For real bearers use pair-minted ones (the strict default) — see [Pairing](/self-hosted/pairing/), and `--keys-file` to persist them across restarts. ### Step 1 — Initialize the MCP session [Section titled “Step 1 — Initialize the MCP session”](#step-1--initialize-the-mcp-session) ```bash curl -X POST http://127.0.0.1:6781/mcp \ -H "Authorization: Bearer dev" \ -H "Accept: application/json, text/event-stream" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-11-25", "clientInfo": { "name": "my-agent", "version": "1.0" }, "capabilities": {} } }' ``` `protocolVersion` here is the MCP transport spec date, not the ggui protocol draft. The `Accept` header is mandatory — the server rejects requests that don’t accept both `application/json` and `text/event-stream`. Responses come back as a single SSE event (`event: message` + `data: {...}`); parse the `data:` line as JSON — the `# → {...}` comments below show that parsed payload. ### Step 2 — Negotiate a handshake [Section titled “Step 2 — Negotiate a handshake”](#step-2--negotiate-a-handshake) ```bash curl -X POST http://127.0.0.1:6781/mcp \ -H "Authorization: Bearer dev" \ -H "Accept: application/json, text/event-stream" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "ggui_handshake", "arguments": { "intent": "Contact form", "blueprintDraft": { "contract": { "propsSpec": { "properties": { "fields": { "schema": { "type": "array", "items": {} } } } }, "actionSpec": { "submit": { "label": "Submit", "schema": { "type": "object" } } } } } } } }' # → { handshakeId, action, suggestion, nextStep? } ``` The returned `suggestion.origin` is the routing discriminator: `'cache'` (a cached blueprint matched — render with `{handshakeId, props}` and omit `override` for a cheap cache delivery), `'agent'` (gen against the draft on render), or `'synth'` (gen against a server-amended contract). `suggestion.blueprintMeta` is always present; it carries a `blueprintId` when the server matched or pre-minted one. See [`ggui_handshake`](/api/mcp-protocol/#ggui_handshake) for the full input + output schemas. ### Step 3 — Render the UI [Section titled “Step 3 — Render the UI”](#step-3--render-the-ui) ```bash curl -X POST http://127.0.0.1:6781/mcp \ -H "Authorization: Bearer dev" \ -H "Accept: application/json, text/event-stream" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "ggui_render", "arguments": { "handshakeId": "h_...", "props": {} } } }' # → { sessionId, resourceUri, action, contractHash, blueprintId, variantKey, cache, nextStep? } ``` `props` is REQUIRED (pass `{}` when the contract declares no `propsSpec`); omit `override` to accept the suggestion as-is, or pass `override: {contract?, variance?}` to re-aim. The render comes back as an MCP-Apps resource (`resourceUri`) a host mounts — there is no URL to hand the user; you poll for their actions with `sessionId`. ### Step 4 — Poll for events [Section titled “Step 4 — Poll for events”](#step-4--poll-for-events) ```bash curl -X POST http://127.0.0.1:6781/mcp \ -H "Authorization: Bearer dev" \ -H "Accept: application/json, text/event-stream" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": { "name": "ggui_consume", "arguments": { "sessionId": "4f6b2c0e-…", "timeout": 20 } } }' # → { events: ConsumeEventEntry[], status: "active" | "expired" } ``` Consume is keyed by the `sessionId` from step 3. `timeout` (seconds): an integer in `[0, 25]`; `0` = immediate. Values outside that range reject with `INVALID_PARAMS` (-32602) — the cap dodges infrastructure kill windows (API-gateway 30s HTTP limits). Pick 5–15s typically, 25 max; to wait longer, re-call `ggui_consume` in a loop — a longer wait is your loop, not a bigger timeout. For push-style delivery, prefer the [WebSocket Protocol](/api/websocket-protocol/) over polling; raw HTTP callers loop `ggui_consume` per render. Each entry has `{type: 'action', sessionId, intent, actionData, uiContext, actionId, firedAt}`. See [Envelopes](/protocol/envelopes/) for the wire shape. Renders decay implicitly via TTL — there is no explicit close ceremony. *** ## Python example [Section titled “Python example”](#python-example) A complete end-to-end run with the standard library and `requests`: ```python import json import time import requests API_URL = "http://127.0.0.1:6781/mcp" HEADERS = { "Authorization": "Bearer dev", # ggui serve --dev-allow-all; local dev only "Accept": "application/json, text/event-stream", "Content-Type": "application/json", } request_id = 0 def parse_sse(body: str) -> dict: # Responses come back as a single SSE event; the JSON-RPC payload is # the `data:` line of the `message` event. for line in body.splitlines(): if line.startswith("data:"): return json.loads(line[len("data:"):].strip()) raise RuntimeError(f"no SSE data line in response: {body[:200]}") def mcp_request(method: str, params: dict | None = None) -> dict: global request_id request_id += 1 payload = {"jsonrpc": "2.0", "id": request_id, "method": method} if params: payload["params"] = params return parse_sse(requests.post(API_URL, headers=HEADERS, json=payload).text) def call_tool(name: str, arguments: dict) -> dict: result = mcp_request("tools/call", {"name": name, "arguments": arguments}) if "error" in result: raise RuntimeError(f"MCP error: {result['error']}") return json.loads(result["result"]["content"][0]["text"]) # 1. Initialize the MCP session. mcp_request("initialize", { "protocolVersion": "2025-11-25", "clientInfo": {"name": "python-agent", "version": "1.0"}, "capabilities": {}, }) # Notifications carry no `id` (JSON-RPC), so post this one directly. requests.post(API_URL, headers=HEADERS, json={ "jsonrpc": "2.0", "method": "notifications/initialized", }) # 2. Negotiate the contract. handshake = call_tool("ggui_handshake", { "intent": "Product feedback form", "blueprintDraft": { "contract": { "propsSpec": {"properties": { "rating": {"schema": {"type": "number"}}, "comments": {"schema": {"type": "string"}}, }}, "actionSpec": {"submit": {"label": "Submit feedback", "schema": {"type": "object"}}}, }, }, }) # 3. Render — accept the handshake's suggestion as-is (omit `override`). result = call_tool("ggui_render", { "handshakeId": handshake["handshakeId"], "props": {}, }) session_id = result["sessionId"] print(f"resource: {result['resourceUri']}") # 4. Poll for events — keyed by sessionId. while True: consume = call_tool("ggui_consume", {"sessionId": session_id, "timeout": 20}) for entry in consume["events"]: # ConsumeEventEntry: {type: 'action', intent, actionData, uiContext, ...} print(f"intent={entry['intent']} data={entry['actionData']}") if consume["status"] == "expired": break if consume["events"]: # Got the gesture we needed — exit on first non-empty payload. break time.sleep(2) # Render decays implicitly via TTL — no explicit close. ``` For long-lived UIs, prefer the WebSocket channel (`ws://127.0.0.1:6781/ws` self-hosted; `wss://mcp.ggui.ai/ws` hosted, coming soon) over polling — see [WebSocket Protocol](/api/websocket-protocol/). *** ## See also [Section titled “See also”](#see-also) * [MCP Protocol Reference](/api/mcp-protocol/) — every method, every argument * [Claude Agent SDK example](/examples/claude-agent/) — higher-level loop that drives these same tools * [WebSocket Protocol](/api/websocket-protocol/) — push events instead of polling * [Envelopes](/protocol/envelopes/) — `ActionEnvelope`, `StreamEnvelope` * [OSS Quick Start](/oss-quickstart/) — run your own `ggui serve` in minutes # OpenAI Agent > Bridge OpenAI function calling to ggui's MCP server so GPT can show interactive UIs and read back structured user input. OpenAI’s chat API doesn’t speak MCP, so you bridge ggui’s MCP tools into OpenAI’s function-calling shape yourself. Two packages do the work: * **`@modelcontextprotocol/sdk`** — connects to your ggui MCP endpoint (a local `ggui serve` below), enumerates ggui’s tools, executes tool calls. * **`openai`** — drives the GPT loop and decides when to call those tools. The bridge is mechanical: list MCP tools once, map each to an OpenAI function definition, then forward every `tool_call` GPT emits straight through to `mcpClient.callTool`. ## Setup [Section titled “Setup”](#setup) ```bash npm install openai @modelcontextprotocol/sdk ``` ```bash export OPENAI_API_KEY="sk-..." ``` ## Code [Section titled “Code”](#code) openai-agent.ts ```typescript import OpenAI from "openai"; import { Client } from "@modelcontextprotocol/sdk/client/index.js"; import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"; const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY }); // 1. Connect to ggui's MCP server (`ggui serve --dev-allow-all` accepts any // bearer — local dev only). const mcpClient = new Client({ name: "openai-ggui-agent", version: "0.1.0" }, {}); await mcpClient.connect( new StreamableHTTPClientTransport(new URL("http://127.0.0.1:6781/mcp"), { requestInit: { headers: { Authorization: "Bearer dev" }, }, }) ); // 2. Enumerate ggui's MCP tools and bridge them into OpenAI's // function-calling tool shape. MCP `inputSchema` is already JSON Schema, // which is exactly what OpenAI's `parameters` expects. const { tools: mcpTools } = await mcpClient.listTools(); const openaiTools: OpenAI.ChatCompletionTool[] = mcpTools.map((t) => ({ type: "function", function: { name: t.name, description: t.description ?? "", parameters: t.inputSchema as Record, }, })); async function chat(userPrompt: string) { console.log(`\nUser: ${userPrompt}`); const messages: OpenAI.ChatCompletionMessageParam[] = [ { role: "system", content: "You are a helpful assistant. Use the available ggui tools to render interactive UIs whenever you need structured input from the user.", }, { role: "user", content: userPrompt }, ]; // 3. Drive the tool-call loop until GPT stops asking for tools. while (true) { const completion = await openai.chat.completions.create({ model: "gpt-5.5", messages, tools: openaiTools, }); const message = completion.choices[0].message; messages.push(message); if (!message.tool_calls || message.tool_calls.length === 0) { console.log(`\nAssistant: ${message.content}`); return; } // 4. Forward every tool call through MCP, feed results back to GPT. for (const call of message.tool_calls) { const result = await mcpClient.callTool({ name: call.function.name, arguments: JSON.parse(call.function.arguments), }); messages.push({ role: "tool", tool_call_id: call.id, content: JSON.stringify(result.content), }); } } } await chat("Help me plan a team dinner for 8 people"); await mcpClient.close(); ``` ## Run [Section titled “Run”](#run) ```bash npx tsx openai-agent.ts ``` GPT calls `ggui_handshake` then `ggui_render`; the tool result carries `{sessionId, resourceUri}` — an MCP-Apps resource your host mounts. GPT then calls `ggui_consume({sessionId})`, and the loop delivers the submitted payload on the next turn. ## How the bridge works [Section titled “How the bridge works”](#how-the-bridge-works) * **MCP enumerates the toolset.** `listTools()` returns whatever ggui exposes (`ggui_handshake`, `ggui_render`, `ggui_consume`, …); you don’t hard-code a tool schema in your agent. * **MCP schemas are already OpenAI-compatible.** `tool.inputSchema` is JSON Schema; OpenAI’s `function.parameters` is JSON Schema. The map is one-to-one. * **Tool dispatch is dumb forwarding.** Every `tool_call` GPT emits is passed verbatim to `mcpClient.callTool` — the MCP server (not your agent) owns render lifecycle, handshake, render, and consume. * **Identity vs grouping.** Identity comes from the `Authorization` header; conversation grouping (resume via `ggui_list_sessions`) comes from the optional `_meta["ai.ggui/host-session"]` request slice. Reusing the same `Client` keeps the transport alive but does not itself group renders. ## OpenAI-specific notes [Section titled “OpenAI-specific notes”](#openai-specific-notes) * Function arguments arrive as a JSON **string** — always `JSON.parse(toolCall.function.arguments)` before forwarding. * Tool results are returned as `{ role: "tool", tool_call_id, content }` messages (not Anthropic’s `tool_result` block shape). * `result.content` from MCP is an array of content blocks; `JSON.stringify`-ing it gives GPT a faithful view of structured payloads. For text-only tools you can pull `result.content[0].text` instead. ## Next [Section titled “Next”](#next) * [Claude Agent example](/examples/claude-agent/) — same outcome via the Claude Agent SDK’s native MCP support (no manual bridging). * [Gemini Agent example](/examples/gemini-agent/) — the same MCP-bridge pattern adapted to Google’s SDK. * [How it works](/how-it-works/) — the three channels (bootstrap, MCP, WebSocket) and envelope shapes. # OpenClaw Agent > Install the ggui skill in OpenClaw and let any agent push interactive UIs on demand. Placeholder integration **OpenClaw** and **ClawHub** are placeholder brand names for an upcoming launch partner — the `clawhub` CLI and the `mcporter.json` skill manifest referenced below do **not** exist as a shipping product yet. The rest of the page (tool catalogue, handshake-first flow, auth headers, MCP config JSON) is canonical and works against any MCP-compatible host today; once OpenClaw ships, only the install command on this page changes. If you’re integrating right now, follow [Generic MCP / Raw HTTP](/examples/generic-mcp/) instead. Install the ggui skill from ClawHub and any OpenClaw agent can generate interactive UIs from a natural-language prompt — forms, dashboards, wizards, anything the model can describe. ## Setup [Section titled “Setup”](#setup) ### 1. Install the skill [Section titled “1. Install the skill”](#1-install-the-skill) ```bash clawhub install ggui ``` This drops the ggui MCP tool catalogue and skill prompt into your agent’s context. ### 2. Pick an endpoint [Section titled “2. Pick an endpoint”](#2-pick-an-endpoint) **OSS / self-hosted** — no signup. Run `ggui serve --dev-allow-all` locally (defaults to `http://127.0.0.1:6781/mcp`; see the [OSS Quick Start](/oss-quickstart/)); any bearer — use `Bearer dev` — authenticates in this mode. Local development only; default `ggui serve` requires a paired bearer. ### 3. Configure MCP [Section titled “3. Configure MCP”](#3-configure-mcp) The skill ships an `mcporter.json` that wires this up automatically. For manual setup: **OSS `ggui serve`** ```json { "mcpServers": { "ggui": { "type": "http", "url": "http://127.0.0.1:6781/mcp", "headers": { "Authorization": "Bearer dev" } } } } ``` **Hosted ggui (coming soon)** — the cloud endpoint is per-app, no `/mcp` suffix: ```json { "mcpServers": { "ggui": { "type": "http", "url": "https://mcp.ggui.ai/apps/", "headers": { "Authorization": "Bearer ${GGUI_API_KEY}" } } } } ``` ## Tool catalogue [Section titled “Tool catalogue”](#tool-catalogue) The skill exposes the ggui MCP tools — the agent never picks a blueprint by hand, the server’s matcher does that under the hood during handshake. **Core render loop** | Tool | Purpose | | ---------------- | -------------------------------------------------------------------------- | | `ggui_handshake` | Negotiate the wire surface for the next UI (returns a `handshakeId`). | | `ggui_render` | Materialize the UI (mints `sessionId`; accept the suggestion or override). | | `ggui_consume` | Long-poll for user gestures (form submits, button clicks). | | `ggui_update` | Patch a delivered render’s props without re-rendering. | | `ggui_emit` | Push frames onto a declared `streamSpec` channel (optional). | **Inspection** | Tool | Purpose | | -------------------- | -------------------------------------------------------------------------- | | `ggui_get_session` | Inspect render state. | | `ggui_list_sessions` | Enumerate this conversation’s sessions for resume (keyed by host-session). | | `ggui_list_gadgets` | Enumerate renderer-side capabilities (map tiles, charts, editors). | | `ggui_list_themes` | List theme presets the agent may apply via `ggui_render({themeId})`. | **Blueprint registry (optional)** | Tool | Purpose | | ------------------------------- | ---------------------------------------------------- | | `ggui_list_featured_blueprints` | Browse curated blueprints the provider has featured. | | `ggui_search_blueprints` | Search the blueprint registry by keyword / intent. | | `ggui_render_blueprint` | Render a manifest-declared blueprint directly by id. | ## Usage [Section titled “Usage”](#usage) The canonical flow is **handshake → render → consume**. Ask your OpenClaw agent: > “Collect feedback about the user’s recent purchase. Ask for a star rating and free-form comments.” The agent will: 1. `ggui_handshake({ intent, blueprintDraft })` — get a `handshakeId` + a routed `suggestion` (origin: cache / agent / synth). 2. `ggui_render({ handshakeId, props })` — accept the suggestion as-is (or pass `override: { contract }` / `{ variance }` to re-aim). Returns `{ sessionId, resourceUri }` — the render is an MCP-Apps resource a host mounts, not a URL. 3. `ggui_consume({ sessionId, timeout: 20 })` — long-poll until the user submits; events arrive keyed by `intent` (your actionSpec key). Renders decay implicitly via TTL — there is no explicit close ceremony. ### Multi-step wizard [Section titled “Multi-step wizard”](#multi-step-wizard) > “Walk the user through a 3-step onboarding: personal info, preferences, confirmation.” Each step is its own fresh `ggui_handshake` + `ggui_render` pair (each minting a new `sessionId`). Carry earlier answers forward by passing them as `props` on the next step’s `ggui_render` (declare the matching propsSpec entries in that step’s `blueprintDraft`) so the next prompt can prefill. See the [Multi-step wizard cookbook](/cookbook/multi-step-wizard/) for back-navigation patterns. ### Live patches without a re-render [Section titled “Live patches without a re-render”](#live-patches-without-a-re-render) > “While the form is open, refresh the available time-slot list every 10s.” Loop `ggui_update({ sessionId, kind: "merge", patch: { slots } })` to mutate props in place (RFC 7396 JSON Merge Patch — `null` deletes a key). Use `{ kind: "replace", props }` for a full props swap. No new render, no flicker. ## How it works [Section titled “How it works”](#how-it-works) ```plaintext OpenClaw Agent ggui server User browser | | | |-- ggui_handshake ------->| | | (matcher picks cached | | | blueprint OR fires | | | synth — invisible) | | |<-- { handshakeId, -------| | | suggestion } | | |-- ggui_render({ -------->| | | handshakeId, props }) | | |<-- { sessionId, ---------| | | resourceUri } | | | |-- mounts resource ---->| | |---- render UI -------->| |-- ggui_consume --------->| | | |<--- submit form -------| |<-- { events } -----------| | | (render decays via TTL) | | ``` Blueprints are an internal cache: the matcher checks them on every handshake. A cache hit returns near-instantly; a miss generates fresh React (expect seconds to \~a minute depending on model). The agent doesn’t pick — it just describes intent. ## Patterns [Section titled “Patterns”](#patterns) * **Describe intent, not markup.** “A 3-question NPS survey” beats “a form with a slider, a textarea, and a submit button.” * **Pass data as `props`, declared in the contract.** Lists of options, prefilled values, the current user — declare them in `blueprintDraft`’s propsSpec and pass the values as `props` on `ggui_render`, not in the intent string. * **Fresh render per step.** Each new screen is a fresh `handshake → render` pair with its own `sessionId`. Prior renders decay via TTL. * **Drain `ggui_consume` in a loop.** Events are cleared after consumption. Match on each event’s `intent` (your actionSpec key, e.g. `submit`); react, then re-call. Exit when `status: "expired"`. ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) | Symptom | Fix | | -------------------- | ----------------------------------------------------------------------------------------------------- | | `Unauthorized` | Local: run `ggui serve --dev-allow-all` (or pair a bearer). Hosted (coming soon): set `GGUI_API_KEY`. | | `Session not found` | Session expired (TTL elapsed) — re-handshake to mint a fresh one. | | `Handshake required` | You called `ggui_render` without a `handshakeId` — handshake first. | | Empty `consume` | User hasn’t interacted yet. Keep polling (long-poll up to \~20s). | | Generation failed | Simplify the prompt. (Hosted only, coming soon: check your account has credits.) | ## Next steps [Section titled “Next steps”](#next-steps) * **[MCP Protocol Reference](/api/mcp-protocol/)** — wire-level tool catalogue * **[Claude Agent](/examples/claude-agent/)** — same flow, Claude SDK in TypeScript * **[Generic MCP / Raw HTTP](/examples/generic-mcp/)** — language-agnostic version * **[Feedback Form cookbook](/cookbook/feedback-form/)** — end-to-end recipe with code * **[Glossary](/glossary/)** — gadget vs tool vs blueprint # Hosted Quickstart > Ship your first agent UI against hosted ggui (mcp.ggui.ai) in under 5 minutes — no infrastructure required. Coming soon This page describes the **managed hosted path** (`mcp.ggui.ai` / `console.ggui.ai`), which is **not yet live** — it is not part of GGUI Preview 0.1.0. The self-hosted path is available today: start with the [Quickstart](/oss-quickstart/). This page is kept as a preview of the managed path and goes live when hosted ggui ships. In 5 minutes, your agent will negotiate a UI contract, push a generated form to a user, and receive their submission as structured data — no React code, no front-end build, no infrastructure. ```plaintext Your Agent → mcp.ggui.ai → MCP-Apps render (ui://ggui/render/) → User submits → Agent gets typed data ``` ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * **Node.js** 20+ * **A free `console.ggui.ai` account.** Sign in at [console.ggui.ai](https://console.ggui.ai) with email + password. (`console.ggui.ai` is the end-user dashboard for hosted ggui — see the [glossary](/glossary/) if the `ggui` / `guuey` split confuses you.) ## Step 1: Pick an app and mint an SDK API key [Section titled “Step 1: Pick an app and mint an SDK API key”](#step-1-pick-an-app-and-mint-an-sdk-api-key) 1. Sign in at [console.ggui.ai](https://console.ggui.ai). You land on `/apps` — new accounts come pre-provisioned with one default app; create another with **New App** if you want to scope this quickstart to its own surface (e.g. `feedback-demo`). 2. Open the app and go to **Keys** (`/apps/[appId]/keys`). Click **Mint key**, label it (e.g. `feedback-demo-sdk`), and submit. 3. The key reveals exactly once — **copy both the key (`ggui_user_…`) and the App ID (`app_…`) immediately.** Lose the key and you mint a new one; there’s no recovery. Caution Never commit `ggui_user_*` keys. Use `.env` files and a secret manager in production. ## Step 2: Install the dependencies [Section titled “Step 2: Install the dependencies”](#step-2-install-the-dependencies) ```bash npm install @anthropic-ai/claude-agent-sdk @ggui-ai/protocol # or: pnpm add @anthropic-ai/claude-agent-sdk @ggui-ai/protocol # or: yarn add @anthropic-ai/claude-agent-sdk @ggui-ai/protocol ``` * **`@anthropic-ai/claude-agent-sdk`** runs Claude as a tool-using agent and speaks MCP natively — no wrapper needed. * **`@ggui-ai/protocol`** exports `GGUI_AGENT_SYSTEM_PROMPT`, the canonical system prompt that teaches Claude the handshake → render → consume loop. ## Step 3: Write your agent [Section titled “Step 3: Write your agent”](#step-3-write-your-agent) Create `agent.ts`. The Claude Agent SDK connects to `mcp.ggui.ai` directly via its `mcpServers` config — your code just streams Claude’s messages and lets the model drive the ggui tools. ```typescript import { query } from "@anthropic-ai/claude-agent-sdk"; import { GGUI_AGENT_SYSTEM_PROMPT } from "@ggui-ai/protocol"; // 1. Point Claude's MCP client at your app's hosted endpoint. Bearer-auth // with the `ggui_user_*` key you minted in Step 1. Note: the per-app // cloud endpoint is the bare `/apps/` path — NO `/mcp` suffix // (that suffix is local-`ggui serve`-only). const mcpServers = { ggui: { type: "http" as const, url: "https://mcp.ggui.ai/apps/", headers: { Authorization: `Bearer ${process.env.GGUI_API_KEY!}` }, }, }; // 2. Allow Claude to call every ggui tool. The `mcp____` // naming is the SDK's convention — `` = `ggui` (the key above). const allowedTools = [ "mcp__ggui__ggui_handshake", "mcp__ggui__ggui_render", "mcp__ggui__ggui_update", "mcp__ggui__ggui_emit", "mcp__ggui__ggui_consume", "mcp__ggui__ggui_get_session", ]; async function main() { const prompt = "Collect product feedback from the user. Show a feedback form with a " + "1-5 star rating and a comments text area, wait for them to submit, " + "then summarize what they said."; // 3. Stream the conversation. Claude reads GGUI_AGENT_SYSTEM_PROMPT, // decides when to call ggui_handshake / ggui_render, // polls ggui_consume until the user submits, and reports back — // all without any wrapper SDK on your side. for await (const msg of query({ prompt, options: { mcpServers, allowedTools, systemPrompt: GGUI_AGENT_SYSTEM_PROMPT, }, })) { if (msg.type === "assistant") { for (const block of msg.message.content) { if (block.type === "text") console.log(block.text); } } else if (msg.type === "result") { console.log("Done:", msg.subtype); } } } main().catch(console.error); ``` ## Step 4: Run it [Section titled “Step 4: Run it”](#step-4-run-it) ```bash export ANTHROPIC_API_KEY="sk-ant-..." # for the Claude Agent SDK export GGUI_API_KEY="ggui_user_..." # for mcp.ggui.ai npx tsx agent.ts ``` You’ll see Claude narrate the handshake, call `ggui_render` (which returns `{ sessionId, resourceUri }` — the render surfaces as an MCP-Apps resource at `ui://ggui/render/`, not a clickable link), and then **block on `ggui_consume`**, polling for the user’s submission. That block is the point to notice: run programmatically like this, there is no UI surface for a human to submit through yet — the agent is waiting on a render nobody can see. To actually mount the render and let a user interact, you need an MCP-Apps host. Two ways to get one: * **Embed it in your own app** — Step 5 below mounts the render with the React SDK. * **Run the agent inside an MCP-Apps host** — claude.ai or Claude Desktop renders ggui resources inline (see [Clients](/clients/claude-desktop/)). ## Step 5 (optional): Embed in React [Section titled “Step 5 (optional): Embed in React”](#step-5-optional-embed-in-react) Want the UI inside your own app? Install the React SDK and the MCP-Apps host: ```bash npm install @ggui-ai/react @mcp-ui/client ``` A ggui render is an **MCP-Apps resource**. You drive the conversation with the `useMcpAppsChat` hook and mount each render’s sandboxed iframe with `` (imported directly from `@mcp-ui/client` — ggui doesn’t re-export it): ```tsx import { AppRenderer } from "@mcp-ui/client"; import { useMcpAppsChat } from "@ggui-ai/react/chat-helpers"; function Chat({ agentUrl }: { agentUrl: string }) { const { entries, sessions, send, handleAppMessage } = useMcpAppsChat({ chatEndpoint: `${agentUrl}/agent`, }); // - render `entries` as chat bubbles; call `send(prompt)` to talk to the agent // - mount each `sessions` entry with — it needs a sandbox-proxy // origin + onReadResource / onCallTool relay + onMessage={handleAppMessage} } ``` `useMcpAppsChat` talks to your **agent backend** (the process running the Step-3 `query()` loop, exposed over HTTP — `@ggui-ai/agent-server` gives you a brand-neutral `POST /agent` endpoint for exactly this). ``’s sandbox + resource-read + tool-call relay wiring is non-trivial; the complete runnable reference is the [`ggui-basic-web`](https://github.com/ggui-ai/ggui/tree/main/samples/apps/ggui-basic-web) sample. **Start there.** ## What just happened [Section titled “What just happened”](#what-just-happened) Under the hood, Claude drove these MCP tool calls against `mcp.ggui.ai`: 1. **`ggui_handshake`** negotiated a **contract** from a natural-language intent + draft, returning a `handshakeId` + a server suggestion (cache / agent / synth). 2. **`ggui_render`** with `{ handshakeId, props }` materialized the contract: ggui matched a cached **blueprint** (or synthesized a fresh React component), minted a `sessionId`, and returned `{ sessionId, resourceUri }` — the render is an MCP-Apps resource at `ui://ggui/render/`, surfaced on the tool result’s `_meta.ui.resourceUri`. (There is no clickable URL on the wire.) 3. A host mounted that resource — your app via `` (Step 5), or an MCP-Apps host like claude.ai inline — and the user submitted the form. 4. **`ggui_consume`** delivered the user’s submit gesture as a `ConsumeEventEntry` (`{ intent, actionData, uiContext, ... }`). Renders decay implicitly via TTL — there is no terminal `close` ceremony. Everything above the wire is `GGUI_AGENT_SYSTEM_PROMPT` + the Claude Agent SDK’s tool loop — no ggui-specific client code on your side. ```plaintext Agent mcp.ggui.ai MCP-Apps host │ │ (your app / claude.ai) │── handshake ───────────→ │ │ │← { handshakeId, ─ │ │ │ suggestion } │ │ │── render(handshakeId, ─ │ │ │ props) ────────────→ │ │ │ │── match/synth blueprint │ │← { sessionId, ─ │ │ │ resourceUri } │ │ │ │── ui://ggui/render/ ──→│ (host mounts iframe) │ │ │ │── consume(sessionId) ───→ │ │ │ │←── submit gesture ────────│ │← { events } ──────────── │ │ │ │ │ │ (render decays via TTL — no explicit close) │ ``` ## Next steps [Section titled “Next steps”](#next-steps) * **[Claude agent example](/examples/claude-agent/)** — canonical reference implementation for the snippet above * **[MCP protocol reference](/api/mcp-protocol/)** — every `ggui_*` tool, request/response, and error code * **[React SDK](/sdk/react/)** — embed ggui renders directly in your own React app with `useMcpAppsChat` + `` * **[Other LLMs](/examples/generic-mcp/)** — raw `@modelcontextprotocol/sdk` recipe; also [OpenAI](/examples/openai-agent/), [Gemini](/examples/gemini-agent/), [OpenClaw](/examples/openclaw-agent/) * **[Feedback-form cookbook](/cookbook/feedback-form/)** — the recipe above, with variations * **[Troubleshooting](/troubleshooting/)** — common issues and fixes * **[Glossary](/glossary/)** — gadget vs tool vs blueprint, ggui vs guuey, and the rest * **[Agentic App Builders](/agentic-app-builders/)** — if your goal is to make an existing app agent-drivable rather than building a fresh agent. # Glossary > Lookup reference for ggui terminology — GguiSession, contract, blueprint, channel, connector, gadget, tool, and the wire envelopes that tie them together. Lookup reference for the terms that run through these docs. Each entry is short and links to where the term is documented in depth. For a narrative walkthrough, see [**How ggui works**](/how-it-works/). ## Identity and lifecycle [Section titled “Identity and lifecycle”](#identity-and-lifecycle) ### GguiSession (a “render”) [Section titled “GguiSession (a “render”)”](#gguisession-a-render) The atomic unit of a ggui exchange — the canonical protocol shape for a single rendered UI. A GguiSession is minted server-side inside `ggui_render` (one per UI emission), lives until its TTL elapses, and is keyed by a stable `sessionId` (opaque string). It is a union of Component / System / McpApps variants and carries a single component mount plus a stream of live-channel deliveries. The server is the authority on its state, not the agent. `render` survives as the verb and in wire constants (`ggui_render`, `ui://ggui/render`, the `ai.ggui/render` slice). Conversation-scoped grouping (sibling GguiSessions inside the same host chat) flows through the unchanged `_meta["ai.ggui/host-session"]` slice — captured ONCE at creation, never lifted onto every GguiSession. The agent does not thread a conversation id; instead each new `ggui_handshake` → `ggui_render` pair mints a fresh `sessionId`. → See [MCP Protocol → ggui\_handshake / ggui\_render](/api/mcp-protocol/) for the lifecycle methods. ### GguiSession contents [Section titled “GguiSession contents”](#gguisession-contents) A single GguiSession packages a compiled component plus its declared contract: * `sessionId` — the stable identifier * `componentCode` — the compiled JavaScript module returned by generation * `props` — the data payload the agent rendered * `propsSpec` / `actionSpec` / `streamSpec` / `contextSpec` — the four contract specs that pin the wire surface * `clientCapabilities` — the package-keyed gadget catalog projected from the contract at render time In wire envelopes you’ll see `sessionId` consistently — there is no separate conversation-session id layer. → See [Envelopes → ActionEnvelope](/protocol/envelopes/#actionenvelope) for the wire shape. ### App (`appId`) [Section titled “App (appId)”](#app-appid) The agent-builder’s tenant scope. An `appId` (`app_…`) groups GguiSessions, blueprints, connectors, and provider keys under one boundary. On self-hosted `ggui serve`, the default app is whatever your `ggui.json` declares; on the hosted ggui cloud (coming soon), the `appId` is minted by the platform. Every `ggui_handshake` / `ggui_render` call is scoped to one `appId`. ### `shortCode` [Section titled “shortCode”](#shortcode) An internal 16-character token minted per render. Not on the agent wire — `ggui_render` returns `sessionId` + `resourceUri` (`ui://ggui/render/`), and hosts mount the GguiSession from the `resourceUri`; the agent never receives a render URL — but `ggui serve` still uses shortCodes for its local render-viewer route (`/r/`). *** ## Wire [Section titled “Wire”](#wire) ggui’s wire is split across orthogonal transports. Two share every framing: **MCP** (agent ↔ server request/response) and the **live channel** (server ↔ renderer WebSocket). A third depends on viewpoint — the [protocol overview](/protocol/overview/) names the **chat channel** (user ↔ wrapped agent, HTTP SSE) as the conversational-stack third; the [architecture overview](/architecture/overview/) names the **bootstrap channel** (server → renderer, one-shot bundle fetch) as the wire-pipeline third. The terms below all live on the live channel unless noted. ### Audience [Section titled “Audience”](#audience) A tag on every MCP handler — one of `agent`, `runtime`, `protocol`, or `ops` — that determines which route the tool surfaces on. `/mcp` serves the union of `agent` + `runtime` handlers (what the model and its runtime see); `/protocol` serves `protocol` (design-time spec/discovery); `/ops` serves `ops` (operator surface). The audience tag is set on every handler factory and encoded in the wire-name prefix (`ggui_protocol_*`, `ggui_ops_*`, `ggui_runtime_*`, or bare `ggui_*`). → See [Audience routes](/architecture/audience-routes/). ### Channel (live channel) [Section titled “Channel (live channel)”](#channel-live-channel) A named outbound stream on the live-channel WebSocket (`ws://127.0.0.1:6781/ws` on `ggui serve`; `wss://mcp.ggui.ai/ws` on the hosted cloud, coming soon). Agents declare channels in their `streamSpec`; the server validates each `StreamEnvelope` against the declared channel’s schema before delivery. A channel has a name (e.g. `message`, `tasks`, `progress`), a payload schema, a state-folding `mode` (`'append'` or `'replace'`), and an optional `replay` policy. Channels prefixed with `_ggui:` are reserved for the server (e.g. `_ggui:preview`, `_ggui:lifecycle`). Agent-authored `streamSpec` cannot declare them. → See [Envelopes → Reserved channels](/protocol/envelopes/#reserved-channels). ### Contract [Section titled “Contract”](#contract) The typed agreement between agent and renderer for a given render: what the props look like, what actions the user can dispatch, what each action’s payload schema is, what live channels the renderer subscribes to. Contracts are authored with `defineContract({…} as const)` so the protocol derives TypeScript types from a single source. A contract has four orthogonal specs: * **`propsSpec`** — initial render data (server → UI, one-time at render) * **`actionSpec`** — discrete events that drive the agent’s next turn (UI → agent, via `ggui_consume`) * **`contextSpec`** — observable state mirrored from UI to server, last-write-wins (UI → server) * **`streamSpec`** — outbound deliveries from agent to UI (agent → UI, via `ggui_emit`) The placement test for the two inbound specs: **does this thing need the agent’s next-turn reasoning?** Yes → `actionSpec`. No → `contextSpec`. There is no third category — `actionSpec` carries events that drive turns; `contextSpec` carries state the agent observes when it next does work. When a delivery violates the contract, the server rejects it with a typed, named failure (a `CONTRACT_VIOLATION` error frame on the live channel, code `-32020`; a typed rejection on the agent’s own tool call) — that’s the contract’s failure-mode surface. Nothing lands on the consume buffer. (The earlier `_ggui:contract-error` channel and `ContractErrorPayload` shape were removed in draft-2026-06-11.) ### `ActionEnvelope` [Section titled “ActionEnvelope”](#actionenvelope) The flat, narrow inbound envelope on the live channel. Carries a single canonical user action — `type` is always `'data:submit'` — plus a payload. The server validates `ActionEventValue` payloads against the render’s `actionSpec`. → See [Envelopes → ActionEnvelope](/protocol/envelopes/#actionenvelope). ### `StreamEnvelope` [Section titled “StreamEnvelope”](#streamenvelope) The outbound delivery on the live channel — one envelope per delivery on a named stream. Carries `channel`, `mode`, `payload`, and (when populated) a server-assigned `seq` for replay correctness. → See [Envelopes → StreamEnvelope](/protocol/envelopes/#streamenvelope). ### `nextStep` tool hint [Section titled “nextStep tool hint”](#nextstep-tool-hint) An author-declared hint on a contract action: `actionSpec[name].nextStep` names an MCP tool — “when the user dispatches this action, that tool is what should run next”. Every action is agent-routed: the server appends the action event to the GguiSession’s consume buffer and the agent reacts on its next turn via `ggui_consume`. The hint rides along on `ActionEventValue.tool` (derived server-side at event-build time) so the agent sees the contract author’s recommendation; the agent owns the call decision — the protocol never binds it. In agent-less deployments (a bare `ggui serve` with no agent process attached), actions take the SAME path: each action event queues on the GguiSession’s consume buffer until an agent attaches and drains it via `ggui_consume({sessionId})` — the server NEVER invokes a tool on the user’s behalf. There is no second routing model. Actions without a `nextStep` are pure event signals — the agent receives `{action, data}` and decides what to do unconstrained. (The retired `dispatch.kind === 'tool' | 'agent'` discriminated union from earlier drafts is gone; outside material still using that vocabulary is stale.) ### `ggui_emit` [Section titled “ggui\_emit”](#ggui_emit) The MCP tool the agent calls to emit a delivery onto a declared `streamSpec` channel of an existing render. Input is `{sessionId, channel, payload}`; the server validates `payload` against `streamSpec[channel].schema` and fans it out as a `StreamEnvelope` on the live channel. The outbound counterpart to `ggui_consume`’s inbound drain. → See [MCP Protocol → `ggui_emit`](/api/mcp-protocol/#ggui_emit). ### `ggui_consume` [Section titled “ggui\_consume”](#ggui_consume) The MCP tool the agent long-polls to drain buffered user events off one render. Consume-once semantics — events drain on read. Call this right after every `ggui_render` whose response carries `nextStep.tool === 'ggui_consume'` (i.e. the rendered contract has a non-empty `actionSpec`). Drained events surface with optional `tool` metadata mirrored from `actionSpec[action].nextStep`. → See [MCP Protocol → `ggui_consume`](/api/mcp-protocol/#ggui_consume). ### `nextStep` (advisory recovery hint) [Section titled “nextStep (advisory recovery hint)”](#nextstep-advisory-recovery-hint) A small wire-shape object the server returns on `ggui_handshake` and `ggui_render`. The handshake form is `{tool: 'ggui_render', example}`; the render form is `{tool: 'ggui_consume', description, example, args: {sessionId}}` — `args` carries the literal value to pass to `ggui_consume`. The `example` is a literal worked call prefilled with current ids, so the agent can recover the next step without re-reading the docs. On `ggui_render`, `nextStep` is emitted ONLY when the rendered contract has a non-empty `actionSpec` and points at `ggui_consume`; pure-display renders get no `nextStep`. Distinct from `actionSpec[name].nextStep`, which is an author-declared **tool hint** on a contract action (see [`nextStep` tool hint](#nextstep-tool-hint)). ### MCP service [Section titled “MCP service”](#mcp-service) A self-contained MCP server mounted at its own HTTP path (e.g. `/docs`, `/playground/todos`) with its own tool catalog, auth adapter, and lifecycle. Distinct from an `McpServerMount`, which aggregates tools onto the audience-filtered shared routes (`/mcp`, `/protocol`, `/ops`); a service stands alone at its mount path. Used when a tool group needs route-level isolation — a different auth posture, a tighter tool catalog, or a public read-only surface. → See [MCP services](/architecture/mcp-services/). *** ## Capabilities [Section titled “Capabilities”](#capabilities) ggui has two symmetric **capability surfaces** — one for what the *agent* can do, one for what the *renderer* can render. Both are declared per-app and bounded by the operator, not the agent. They mirror each other across the wire: the agent uses its tools to drive a render; the renderer uses its gadgets to render the result. | | Renderer (renders UI) | Agent (drives render) | | --------- | ----------------------------------- | ------------------------- | | Unit | **gadget** | **tool** | | Catalog | `clientCapabilities.gadgets` | `agentCapabilities.tools` | | Lifecycle | Loaded at iframe boot, SRI-verified | Bound at render start | | Authoring | `ggui.gadget.json` manifest | MCP tool code | ### Gadget (renderer-side capability) [Section titled “Gadget (renderer-side capability)”](#gadget-renderer-side-capability) A self-contained bundle the UI generator picks up when assembling a UI. Concrete examples: a Leaflet gadget exports a `LeafletMap` component the generated UI renders; a Stripe gadget exposes a checkout flow; a Calendar gadget exposes date-picker behaviour. Gadgets bridge third-party JS into the ggui iframe runtime via the `createGguiGadget` factory; a contract references them through the package-keyed `clientCapabilities.gadgets` map (outer key = npm package, inner key = export name), and they load SRI-verified at boot. Authored as `ggui.gadget.json` manifests and published to a marketplace registry (resolved per command from `--registry` / `ggui.json#registry` / `GGUI_REGISTRY`; installs fall back to `registry.ggui.ai`). The term replaced the older `clientLibraries` / “Client Libraries” name; old external references may still use it. ### Tool (agent-side capability) [Section titled “Tool (agent-side capability)”](#tool-agent-side-capability) An MCP tool the agent has access to when orchestrating renders — `ggui_handshake`, `ggui_render`, `ggui_consume`, plus any custom tools the operator wires in. Tools are the agent-side counterpart of gadgets: gadgets give the *renderer* something to render with; tools give the *agent* something to act with. Declared per-app in `agentCapabilities.tools` and surfaced to the model via the MCP server. Blueprints sit in a different category — they’re not capabilities, they’re *cached responses* (pre-composed UIs) that short-circuit fresh generation. See [Blueprint](#blueprint) below. ### Ops tool [Section titled “Ops tool”](#ops-tool) An MCP tool tagged with `audience: ['ops']`, surfaced on the server’s `/ops` route (e.g. `http://127.0.0.1:6781/ops`). Every action the console UI can perform is also available as an ops tool, so an LLM operator agent can drive the same workflows programmatically — list apps, rotate keys, inspect renders, yank blueprints. Wire-name prefix is `ggui_ops_*`, distinguishing them from agent-facing `ggui_*` tools at the route level. → See [Ops MCP](/api/ops-mcp/). ### Theme [Section titled “Theme”](#theme) A per-app visual overlay. `AppTheme = {mode: 'light' | 'dark', cssVariables, name?}` — where `cssVariables` is a map of `--ggui-*` custom properties — is snapshotted onto each GguiSession at render-commit and applied at the iframe `:root` after the base design tokens, so operator values win the cascade. Presets ship in `@ggui-ai/design` (7 today); agents discover them via `ggui_list_themes` and override per render with `ggui_render({themeId})`. Resolution chain: `GguiSession.themeId` → `App.defaultThemeId` → server fallback. *** ## Generation [Section titled “Generation”](#generation) ### Blueprint [Section titled “Blueprint”](#blueprint) A cached UI primitive — a stable, reusable card whose code, contract, and prompt are pre-computed. Blueprints are matched during `ggui_handshake` by intent + contract similarity (semantic search + LLM rerank); the paired `ggui_render` then serves the cached component — a hit renders in \~100 ms versus \~3 s for fresh generation. Project-local blueprints are authored as `ggui.ui.json` manifests and declared via `ggui.json#blueprints.include` globs; for marketplace publishing, a blueprint repo carries a `ggui.blueprint.json` artifact manifest (`ggui blueprint publish`). Where **gadgets** are ingredients the LLM composes with and **tools** are actions the LLM invokes, **blueprints** are recipes the LLM can return directly — a cache short-circuit for already-solved screens. ### Primitive [Section titled “Primitive”](#primitive) A leaf-level UI component declared in a primitive catalog (e.g. Button, Input, SearchField). Primitives are catalog-declared, not protocol-declared — the agent doesn’t ship a fixed component set; the operator declares which primitives are available via `ggui.json#primitives`. Component levels nest: **primitive** (Button) → **component** (SearchField) → **composite** (LoginForm, Modal) → **template** (ListDetail, Dashboard page). ### `shellType` [Section titled “shellType”](#shelltype) The visual shell the renderer wraps a render in. Three values today: `chat` (conversation pane), `fullscreen` (whole-window app), `spatial` (XR / immersive surface). Carried on `interfaceContext.shellType` and read by the runtime when mounting a render. *** ## Auth [Section titled “Auth”](#auth) ### Anonymous service [Section titled “Anonymous service”](#anonymous-service) An `McpService` mounted with `anonymous: true`. Auth becomes OPTIONAL, not skipped: a presented valid bearer still resolves to the caller’s real identity; only a missing or invalid credential falls back to a synthesized `{identity: {kind: 'builder'}, source: 'anonymous'}` principal. Safe for read-only public surfaces (e.g. the docs MCP service that serves how-to lookups); tools that mutate or read tenant-scoped data must re-impose auth at the handler level. → See [MCP services](/architecture/mcp-services/). ### Connector / connector key [Section titled “Connector / connector key”](#connector--connector-key) A `ggui_user_*` API key that authenticates an agent runtime against a ggui MCP server. Locally, `ggui keys create --keys-file ` mints bearers that `ggui serve --keys-file` accepts — no account needed. On the hosted cloud’s universal endpoint (coming soon), keys are minted via [`ggui keys create`](/cli/login/#manage-keys) after [`ggui login`](/cli/login/) (Preview — managed cloud, coming soon). Connector keys are scoped to one user; revoking via `ggui keys revoke ` is a soft-revoke (the audit row stays, but every subsequent request from the key returns `401 invalid_grant`). Distinct from the **bearer** minted by `ggui serve`’s pairing flow — that bearer is per-session and per-pairing, not user-keyed. ### `wsToken` [Section titled “wsToken”](#wstoken) A short-TTL opaque credential minted at `ggui_render` and delivered to the iframe on `_meta["ai.ggui/render"]`, paired with `wsUrl`. The iframe presents it on the WebSocket upgrade (`?wsToken=`) and in `SubscribePayload.wsToken`; the server validates it against the subscribing `sessionId` + `appId`. Refreshed without a re-handshake via the runtime-audience tool `ggui_runtime_refresh_ws_token`. ### `AuthAdapter` [Section titled “AuthAdapter”](#authadapter) The pluggable seam in `@ggui-ai/mcp-server` that decides who’s authenticated on `/mcp` and the live-channel `/ws` upgrade. The default for `ggui serve` is dev-mode pairing; production composes `createGguiServer({ auth })` with a custom adapter (OIDC, Cognito, custom). → See [`ggui serve` → Production hardening](/cli/serve/#production-hardening). *** ## See also [Section titled “See also”](#see-also) * [Protocol overview](/protocol/overview/) — the three-channel topology these terms hang off. * [Envelopes](/protocol/envelopes/) — wire reference for `ActionEnvelope` and `StreamEnvelope`. * [MCP Protocol](/api/mcp-protocol/) — MCP method reference (`ggui_handshake`, `ggui_render`, `ggui_update`, `ggui_consume`). * [WebSocket Protocol](/api/websocket-protocol/) — live-channel message-type reference. # How ggui works > The four moments of a ggui exchange — handshake, render, interact, consume — explained end-to-end in five minutes. A walk-through for agent developers. You’ll come out of this with a working mental model of what happens between the moment your agent calls `ggui_handshake` and the moment the user submits the form. Five minutes. No setup required — this is conceptual. ## The four moments [Section titled “The four moments”](#the-four-moments) Every ggui exchange is the same four moments, in order: ```plaintext 1. HANDSHAKE Post a draft contract; the server routes a suggestion 2. RENDER Accept or override; the server mints an MCP-Apps resource 3. INTERACT The host mounts it; the user fills the UI and submits 4. CONSUME Drain the user's gestures off a render-scoped pipe ``` The rest of this page expands those four moments into a story. ## 1. Handshake — the wire surface is negotiated [Section titled “1. Handshake — the wire surface is negotiated”](#1-handshake--the-wire-surface-is-negotiated) Your agent’s first call is `ggui_handshake` — the server runs blueprint-search + contract-validation in parallel and returns a routed suggestion. (These are MCP tool calls the LLM emits; there is no client SDK — the shapes below are the tool input → output.) ```ts // ggui_handshake tool — input: ggui_handshake({ intent: "collect feedback after a support chat", blueprintDraft: { contract: { /* propsSpec, actionSpec, ... */ }, }, }); // → { handshakeId, action, suggestion } ``` The returned `suggestion.origin` is `cache` (existing blueprint matched), `agent` (gen against the draft), or `synth` (gen against an amended draft). No UI is generated yet — the agent commits next, on render. Each render is independent: each `handshake → render` pair mints a fresh **GguiSession** — the protocol’s unit for one rendered UI — keyed by `sessionId`. There is no conversation-level session object; conversation-scoped grouping (sibling renders inside the same chat) flows through the `_meta["ai.ggui/host-session"]` slice — captured ONCE at creation. → See [`ggui_handshake`](/api/mcp-protocol/) for the wire shape. ## 2. Render — the UI gets generated (or matched) [Section titled “2. Render — the UI gets generated (or matched)”](#2-render--the-ui-gets-generated-or-matched) Now the agent commits against the prior handshake’s suggestion — `props` is required; omit `override` to accept the suggestion as-is: ```ts // ggui_render tool — props required; omitting `override` accepts // the handshake suggestion: ggui_render({ handshakeId, props: { question: "How did the session go?" }, // or re-aim: override: { contract: {...} } / { variance: {...} } }); // → { sessionId, resourceUri, action, ... } ``` Server-side, materialisation runs one of two paths — the path was already chosen at handshake time, render just executes it: 1. **Cache delivery** (`suggestion.origin === 'cache'`). A matching blueprint was found during handshake; render serves the cached component. \~100ms. 2. **Fresh generation** (`origin === 'agent'` or `'synth'`). The server runs the LLM-driven UI generator (`@ggui-ai/ui-gen`) — plan → impl → check → derive. The output is a TSX component compiled to JS, plus a typed **contract** describing the actions the user can take and the data they can submit. \~3s. Either way, any gadgets the component imports (Leaflet, Stripe, Calendar, …) resolve from the app’s declared gadget set (stdlib floor + `ggui.json#app.gadgets`) and load SRI-verified at iframe boot. The agent gets back a `sessionId` (globally unique UUID for the delivered render) and a `resourceUri` (`ui://ggui/render/`). The render is an MCP-Apps resource — there is no clickable URL the agent forwards; a host mounts the resource. → See [`ggui_render`](/api/mcp-protocol/) for the wire shape. ## 3. Interact — the user fills the UI [Section titled “3. Interact — the user fills the UI”](#3-interact--the-user-fills-the-ui) A host mounts the render — your app via ``, or an MCP-Apps host like claude.ai inline. The renderer: 1. Hits the **bootstrap channel** — fetches the compiled component bundle (SRI-verified) 2. Mounts the component in an iframe with the props the agent rendered 3. Connects the **live channel** — a WebSocket subscription scoped to this render 4. When the user submits, the component dispatches an `ActionEnvelope` like `{ type: "data:submit", payload: {...} }`. The server validates the payload against the contract’s `actionSpec`. The renderer is **stateless** between page loads — props come from the server, state comes from the user, and the server is the source of truth for the render’s state. → See [Envelopes](/protocol/envelopes/) for the live-channel wire reference. ## 4. Consume — the action lands back with the agent [Section titled “4. Consume — the action lands back with the agent”](#4-consume--the-action-lands-back-with-the-agent) Actions are agent-routed. The server queues every gesture on a render-scoped pipe; the agent drains it by calling `ggui_consume` (long-poll, keyed by `sessionId`): ```ts // ggui_consume tool (long-poll) — returns { events, status }: const { events, status } = ggui_consume({ sessionId, timeout: 25 }); for (const event of events) { if (event.intent === "submit_feedback") { await processFeedback(event.actionData); } } ``` Each row is a `ConsumeEventEntry`: `{ type: 'action', sessionId, intent, actionData, uiContext, actionId, firedAt }`. `intent` is the action key from the contract’s `actionSpec`; `actionData` is the typed payload (validated against `actionSpec[intent].schema`). `status` is `'active'` until the render’s TTL elapses (`'expired'`) — exit the loop once you have the events you need, or when `status` is `'expired'`. An `actionSpec` entry may carry a `nextStep: ''` hint naming one of the contract’s `agentCapabilities.tools` — an **advisory** hint for the agent’s planner. Implementations MUST treat it as advisory; the agent owns the call decision. Agent-less `ggui serve` deployments take the same path: events queue on the consume buffer until an agent attaches and drains them — the server never invokes a tool on the user’s behalf. There is no second routing model. When the agent wants to refresh the visible card in response to an event (e.g. show a confirmation, splice in new data), it calls `ggui_update` (keyed by `sessionId`, `kind: 'replace' | 'merge'`) — the iframe receives the new props on the live channel without a fresh `ggui_render`. Then loop back to `ggui_consume`. Rule of thumb: if your reaction ran a domain tool that changed what the card displays, call `ggui_update` *before* re-calling `ggui_consume` — skipping it is the most common wire-compliance bug. → See [`ggui_consume`](/api/mcp-protocol/) and the `ConsumeEventEntry` row shape on the same page. ## What you didn’t have to do [Section titled “What you didn’t have to do”](#what-you-didnt-have-to-do) Notice what your agent code did *not* have to handle: * **No UI authoring.** The component code was generated or matched from cache. * **No WebSocket plumbing.** The renderer connects to the live channel on its own; you didn’t open a socket. * **No state management.** The server holds render state. You called `ggui_consume` and got events. * **No SDK lock-in.** Everything above is plain MCP tool calls — works from any MCP client. That’s the protocol. The OSS `ggui serve` running locally (`ws://127.0.0.1:6781/ws`) is the reference implementation; a hosted endpoint at `mcp.ggui.ai` (`wss://mcp.ggui.ai/ws`) is coming soon — both speak the same wire. ## Next [Section titled “Next”](#next) * **Build something** — [OSS Quick Start](/oss-quickstart/) (local); the [Hosted Quick Start](/getting-started/) with `mcp.ggui.ai` is coming soon * **See the wire** — [MCP Protocol](/api/mcp-protocol/), [Envelopes](/protocol/envelopes/), [WebSocket](/api/websocket-protocol/) * **Look up a term** — [Glossary](/glossary/) * **Look at example agents** — [Claude](/examples/claude-agent/), [OpenAI](/examples/openai-agent/), [Gemini](/examples/gemini-agent/), [raw MCP](/examples/generic-mcp/) * **Already shipped a SaaS?** — [Agentic App Builders](/agentic-app-builders/) covers the (in-design) path to make an existing app agent-drivable. # OSS Quick Start > Scaffold a ggui agentic app with `@ggui-ai/create-agentic-app` and run it locally — no account, no cloud, no ggui API key. Scaffold a complete ggui agentic app and run it locally — your agent, the ggui MCP server, a sample MCP server, and a web client — in one `npx`. ```plaintext agent ── MCP ──→ ggui serve ──→ MCP-Apps resource ui://ggui/render/ ``` ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * **Node.js** 20+ * **pnpm**, **npm**, or **bun** — any recent package manager. * An MCP-capable agent runtime (Claude Desktop, Claude Code, Cursor, or anything that reads `.mcp.json`). * No account, no API key. Everything is local. ## Step 1: Scaffold a project [Section titled “Step 1: Scaffold a project”](#step-1-scaffold-a-project) ```bash npx @ggui-ai/create-agentic-app my-app cd my-app pnpm install # or: npm install / bun install ``` `@ggui-ai/create-agentic-app` scaffolds a small monorepo from an official template (`claude-agent-sdk` / `openai-agents-sdk` / `google-adk`): `servers/ggui/` (the ggui MCP server config), `servers/agent/` (your agent), `servers/mcps/todo/` (a sample MCP server), and `apps/web/` (a web client). See [`@ggui-ai/create-agentic-app`](https://www.npmjs.com/package/@ggui-ai/create-agentic-app) for the template list. ## Step 2: Boot the server [Section titled “Step 2: Boot the server”](#step-2-boot-the-server) Set an LLM key in `.env.local` at the project root (any one — the boot probe walks `anthropic` → `openai` → `google` → `openrouter`): .env.local ```bash ANTHROPIC_API_KEY=sk-ant-... ``` ```bash pnpm dev ``` `pnpm dev` boots the whole project together — the ggui MCP server (`ggui serve` from [`@ggui-ai/cli`](https://www.npmjs.com/package/@ggui-ai/cli), embedding `@ggui-ai/mcp-server`), your agent, the sample MCP server, and the web client. The ggui server (`servers/ggui`) defaults to `http://127.0.0.1:6781`: * **MCP endpoint:** `http://127.0.0.1:6781/mcp` * **WebSocket (live channel):** `ws://127.0.0.1:6781/ws` * **Operator console:** `http://127.0.0.1:6781/` Granular scripts (`dev:ggui`, `dev:agent`, `dev:mcps`, `dev:web`, `dev:stop`) run the pieces individually — see the scaffold’s `README`. ## Step 3: Point an agent runtime at the local MCP [Section titled “Step 3: Point an agent runtime at the local MCP”](#step-3-point-an-agent-runtime-at-the-local-mcp) Add this entry to the scaffold’s existing `.mcp.json` (it already contains a `ggui-dev` helper server): ```json { "mcpServers": { "ggui": { "url": "http://127.0.0.1:6781/mcp", "headers": { "Authorization": "Bearer dev" } } } } ``` Claude Desktop, Claude Code, Cursor, and any runtime that reads `.mcp.json` will discover the agent-facing tool catalogue — `ggui_handshake` / `ggui_render` / `ggui_update` / `ggui_emit` / `ggui_consume`, plus discovery tools (`ggui_get_session`, `ggui_list_sessions`, `ggui_list_gadgets`, `ggui_list_themes`, blueprint search/render). The flow is **`handshake` → `render`**, with `ggui_update` to mutate props on a delivered render. Write a system prompt that tells the LLM when to render UIs — the [Examples](/examples/claude-agent/) section has working recipes per framework. ## What works today [Section titled “What works today”](#what-works-today) * ✅ **Local server + wsToken-gated WebSocket subscribe → ack** work end-to-end — the iframe receives `wsUrl`/`wsToken` on the `ai.ggui/render` slice. Render plumbing is production-shaped, not a mock. * ✅ **`handshake` → `render`** delivers an MCP-Apps resource (`ui://ggui/render/`) that an MCP-Apps host mounts. * ✅ **Component generation is wired via BYOK.** Export `ANTHROPIC_API_KEY` (or `OPENAI_API_KEY` / `GOOGLE_API_KEY` / `OPENROUTER_API_KEY`) before `ggui serve` and `ggui_render` runs the real `@ggui-ai/ui-gen` pipeline (blueprint match → synth). Without any key, `ggui_render` returns a “Connect Claude” card pointing at the local `/settings` page rather than failing. * ✅ **Per-app theming.** The scaffold’s `servers/ggui/ggui.json` sets `theme: {preset: 'indigo', mode: 'dark'}`; agents can list presets via `ggui_list_themes` and override per render with `ggui_render({themeId})`. * 🔒 **Default auth is pair-minted.** `/mcp` rejects bearers that weren’t issued by the pairing flow. Pass `--dev-allow-all` to accept any non-empty bearer as `builder` (safe only on `127.0.0.1`), or swap in a real `AuthAdapter` via `createGguiServer({ auth })` before exposing the server beyond localhost. ## What this is not [Section titled “What this is not”](#what-this-is-not) * **Not a hosted service.** No ggui cloud account, no billing, no managed dashboards. For those, see the [Hosted Quick Start](/getting-started/) (coming soon). * **Not a managed billing surface.** Generation runs on YOUR provider key (BYOK) — every `ggui_render` bills the provider directly. The hosted ggui cloud (coming soon) will bundle credit-metered billing and managed keys; this OSS path runs on your own provider key today. ## Vocabulary [Section titled “Vocabulary”](#vocabulary) * **Tool** — an agent-side action exposed over MCP (`ggui_render`, `ggui_handshake`, …). * **Gadget** — a renderer-side capability surfaced inside the viewer (formerly `clientLibraries`). * **Blueprint** — a cached component recipe matched before generation runs. Full definitions: [Glossary](/glossary/). ## Just the bare MCP server [Section titled “Just the bare MCP server”](#just-the-bare-mcp-server) The scaffold orchestrates everything through `pnpm dev`. If you only want the OSS MCP server — no agent or web supervision — run [`ggui serve`](/cli/serve/) against a `ggui.json` directly (the same `ggui serve` the scaffold’s `servers/ggui` runs): ```bash # = ggui serve --mcp-only --dev-allow-all --port 6781 pnpm --filter ./servers/ggui start ``` Working from a monorepo clone rather than the published packages? Build the workspace copies first: ```bash pnpm --filter @ggui-ai/cli build node packages/ggui-cli/dist/cli.js serve --mcp-only ``` ## What’s next [Section titled “What’s next”](#whats-next) * **[MCP Protocol Reference](/api/mcp-protocol/)** — wire format and tool catalogue (same on OSS and hosted). * **[WebSocket Protocol](/api/websocket-protocol/)** — live-channel envelopes (`ActionEnvelope`, `StreamEnvelope`). * **[Examples](/examples/claude-agent/)** — MCP-config-only integrations with system-prompt recipes (Claude, OpenAI, Gemini, OpenClaw, generic MCP). * **[Hosted Quick Start](/getting-started/)** — managed generation and dashboards on ggui cloud (coming soon). * **[GitHub repo](https://github.com/ggui-ai/ggui)** — source, issue tracker, full monorepo walkthrough. # Bootstrap handshake > How a host mounts the ggui renderer iframe, the postMessage contract that crosses that boundary, and the canonical bootstrap failure modes. A ggui render ships as an [MCP App](https://modelcontextprotocol.io/) — a `ResourceContents` blob whose `text` is a thin-shell HTML document. When a host mounts that blob in an iframe, the shell loads the `@ggui-ai/iframe-runtime` bundle, which opens a live-channel WebSocket and starts rendering. This page is the handshake spec across the iframe boundary. > **Audience:** protocol implementers and third-party MCP host builders. If you’re already on `@ggui-ai/react`, the web consumer surface ([`useMcpAppsChat`](/sdk/react/) from `@ggui-ai/react/chat-helpers` + `` from `@mcp-ui/client`) wraps everything below — React Native’s equivalent host is ``. The protocol underneath those wrappers is what’s documented here. The `ProtocolError` union and the full `ObservabilityEvent` catalog ship as exported types in [`@ggui-ai/iframe-runtime`](https://github.com/ggui-ai/ggui/tree/main/packages/iframe-runtime) (re-exported through `@ggui-ai/react` so host apps need no direct renderer import); version-handshake details live in the [WebSocket Protocol reference](/api/websocket-protocol/). This page is the focused handshake spec. *** ## The boot flow [Section titled “The boot flow”](#the-boot-flow) ```plaintext host renderer (in iframe) │ │ │ 1. fetch ResourceContents from MCP server │ │ (`{contents: [{uri, mimeType:'text/html', text}]}`) │ │ │ │ 2. mount ``` The `event.source` check is non-optional — without it, any window can spoof renderer envelopes. Production hosts SHOULD also validate `msg` against [the lifecycle envelope schema](https://github.com/ggui-ai/ggui/blob/main/packages/protocol/src/integrations/mcp-apps.ts) before mirroring state into trusted UI. *** ## Host obligations summary [Section titled “Host obligations summary”](#host-obligations-summary) A host that implements the JSON-RPC methods above plus the four postMessage event handlers honors the protocol’s bootstrap contract. The MUST / SHOULD breakdown: 1. **MUST** honor `_meta["ai.ggui/render"].runtimeUrl` from the resource — the iframe-runtime bundle URL. 2. **MUST** classify `ggui:bootstrap-failed` onto `BootstrapFailureReason` (or render the raw string for unknown values). 3. **MUST** surface `ggui:bootstrap-failed` as a user-visible error. 4. **SHOULD** surface `ggui:observe` events to host telemetry. 5. **MUST NOT** intercept `tools/call` JSON-RPC traffic — forward to the MCP server’s tool registry verbatim. 6. **MUST** narrow `event.source` to the iframe’s `contentWindow` before reading any postMessage data. These obligations are encoded in the [Conformance kit](/protocol/conformance/) — a third-party host that satisfies them passes the host-implementer fixtures. *** ## See also [Section titled “See also”](#see-also) * [Protocol overview](/protocol/overview/) — three-channel topology; bootstrap is the path into the live channel. * [Envelopes](/protocol/envelopes/) — live-channel wire shapes (post-bootstrap traffic). * [Conformance](/protocol/conformance/) — the bar a host implementation must pass. * [`@ggui-ai/iframe-runtime` on GitHub](https://github.com/ggui-ai/ggui/tree/main/packages/iframe-runtime) — `ProtocolError` union, full `ObservabilityEvent` catalog, boot-sequence source. * [`useMcpAppsChat`](/sdk/react/) (from `@ggui-ai/react/chat-helpers`) + `` (from `@mcp-ui/client`) — the web React surface that boxes everything above (React Native’s host is ``). * [`packages/console/src/routes/GguiSessions.tsx`](https://github.com/ggui-ai/ggui/blob/main/packages/console/src/routes/GguiSessions.tsx) — production reference implementation. # Conformance > What it means to be ggui-conformant — the 4-criterion contract bar, 6-criterion protocol bar, and the conformance kit as arbiter. > An implementation is ggui-conformant iff it passes the [conformance kit](https://github.com/ggui-ai/ggui/tree/main/packages/protocol-conformance) — a fixture-based test suite a candidate runs against. Opinion, intent, and prose-level reading of this site are NOT the arbiter; the kit is. This page describes what the ggui protocol promises in exchange for the name “protocol”, what each contract inside it must satisfy, and how the kit makes those promises observable. ## What conformance means [Section titled “What conformance means”](#what-conformance-means) Conformance for ggui means three concrete things: 1. **A third-party implementation can replace the first-party one** — agents, hosts, and ops tools that work against the OSS `ggui serve` work against the third-party server too, without source-level changes. 2. **Every named failure mode produces an observable signal** — operators see violations without running a debugger. 3. **Every breaking change to the protocol is reproducible** — “is this PR breaking?” resolves to a kit run, not a debate. If a layer that calls itself a “protocol” can’t honor these three promises, the layer is something else (a shape, an SDK feature, an author convention) and should be named accordingly. ## The Contract Bar — 4 criteria [Section titled “The Contract Bar — 4 criteria”](#the-contract-bar--4-criteria) A **runtime contract** in ggui MUST satisfy all four. Three of four is not a contract. Documenting a fourth in prose without mechanism is not a contract. ### 1. Named parties [Section titled “1. Named parties”](#1-named-parties) The contract states WHO is on each side. Not “producer” and “consumer” in the abstract — the concrete roles. The `ggui_runtime_submit_action` handler and the consume-buffer pipe. The iframe-runtime and the render-channel server. The contract author and the platform validator. If you can’t name the parties in one sentence, there is no contract — only a data type adrift. * ✅ “The `ggui_runtime_submit_action` handler appends every valid `kind: 'dispatch'` envelope to the render-keyed pending-events pipe; the agent drains it via `ggui_consume`.” * ❌ “Clients should respect the ordering semantics.” ### 2. Explicit obligations per party [Section titled “2. Explicit obligations per party”](#2-explicit-obligations-per-party) Each party has a list of MUSTs and MUST-NOTs. SHOULDs are discipline, not contract — a SHOULD belongs in a style guide. The obligations must be specific enough that a reviewer can literally check a diff against them. * ✅ “Agent-authored `streamSpec` MUST NOT declare a channel whose name starts with `_ggui:`.” * ❌ “Handlers should behave predictably.” An obligation without a verifiable test is a hope, not a contract. ### 3. Defined failure mode per obligation [Section titled “3. Defined failure mode per obligation”](#3-defined-failure-mode-per-obligation) When the obligation breaks, there is a **named, typed, observable failure**. Generic `throw new Error()` is not a failure mode. `console.warn()` is not a failure mode. “Log the outcome to telemetry and carry on” is not a failure mode. Acceptable mechanisms: * A canonical error-code union (`CONTRACT_VIOLATION`, `SESSION_NOT_FOUND`, `SCHEMA_MISMATCH_ERROR`, the runtime-tool rejection codes `INVALID_ACTION_KIND` / `PIPE_NOT_FOUND` / `CONTEXT_TOO_LARGE`). * A typed rejection frame the caller receives on the call that caused it (e.g. a `CONTRACT_VIOLATION` error frame on the live channel, or a `{ok:false, code}` `structuredContent` rejection on a runtime tool). * Boot-time refusal with a message naming the offender (e.g. mount tool-name collision). * Compile-time impossibility (the type has no field → consumers can’t read it). Unacceptable: silent noop, silent degradation, swallowed exception, “it’ll surface in the next call if it’s a real problem.” ### 4. Observable violation [Section titled “4. Observable violation”](#4-observable-violation) An operator can **see the violation without running a debugger**. Surfaces: * An error envelope/frame the caller observes synchronously (the gold standard — a `CONTRACT_VIOLATION` error frame on the live channel when an inbound action violates the contract). * A validation response the caller receives synchronously. * An operator UI that reads the above. * A structured log emitted at a known event name, documented as the contract’s telemetry point. A contract whose violations only show up in production stack traces fails this bar — an operator who inherits the system in six months can’t tell what’s working and what’s silently degraded. *** ## The Protocol Bar — 6 criteria [Section titled “The Protocol Bar — 6 criteria”](#the-protocol-bar--6-criteria) A **protocol** is the emergent layer above a set of contracts. Every layer called “a protocol” MUST satisfy all six. Five of six is a protocol-in-progress; the gap MUST be flagged explicitly and the layer treated as experimental until closed. ### 1. Wire-format specification [Section titled “1. Wire-format specification”](#1-wire-format-specification) A canonical prose spec describing every envelope shape, every field, every value constraint, and — critically — every intentional omission and why. Not just TypeScript types. Types say the shape; the spec says the **semantics**. For ggui, this lives in the site-level wire references — [Envelopes](/protocol/envelopes/), [MCP Protocol](/api/mcp-protocol/), [WebSocket Protocol](/api/websocket-protocol/) — which document every envelope shape, field, and intentional omission. ### 2. Message sequencing and state [Section titled “2. Message sequencing and state”](#2-message-sequencing-and-state) Given envelope X at time T in state S, which transitions are legal? What happens on reconnect? On resume? On concurrent emission? Crash recovery? Out-of-order delivery? A protocol without sequencing is a data type with pretensions. ggui’s sequencing lives in the [three-channel topology](/protocol/overview/) + the `GguiSessionStreamBuffer` interface + the `fromSeq` replay contract. Any new channel or envelope class MUST answer the sequencing question explicitly. ### 3. Version negotiation [Section titled “3. Version negotiation”](#3-version-negotiation) Producer and consumer MUST be able to agree on what version they speak, or explicitly refuse. Stamping a version on every envelope is infrastructure; actually rejecting a mismatched peer is the protocol feature. Pre-launch “advisory stamp only” is acceptable IF the launch-cutover plan names the policy flip (producer-stamp + consumer-reject). Anti-pattern: calling version-stamping “versioning” and shipping. See [Version policy](/protocol/version-policy/) for the post-launch handshake semantics. ### 4. Conformance testability at the seam [Section titled “4. Conformance testability at the seam”](#4-conformance-testability-at-the-seam) A third-party implementer can verify their implementation without running the ggui server. This means: * A public fixture table of envelopes and expected behaviors. * An executable conformance kit (a test package a third party `pnpm add`s and runs). * Coverage of every canonical failure mode — a third-party implementation that passes the kit can be used interchangeably with the first-party one. Without this, “third party adopts the protocol” means “third party reads the spec and hopes.” ### 5. Named failure modes — closed, or extensibly-closed [Section titled “5. Named failure modes — closed, or extensibly-closed”](#5-named-failure-modes--closed-or-extensibly-closed) Every way the protocol can fail has a name, a code, and a shape. Acceptable forms: * **Closed union** — exhaustive by design. Bumping requires a major version bump. Use when the set of values is fixed by an external spec or by a pre-launch design decision the protocol owners control end-to-end. * **Extensibly-closed** — e.g. the `channel_error` code union `'CHANNEL_UNKNOWN' | 'SESSION_NOT_FOUND' | 'SUBSCRIBE_UNAUTHORIZED' | 'POLL_FAILED' | (string & {})`, or the open `code: string` on the WS `error` frame whose canonical literals include `CONTRACT_VIOLATION` and `UPGRADE_REQUIRED`. Consumers MUST handle unknown values gracefully. Adding new values does NOT bump the protocol version. Use when producer-side failure modes are expected to grow (new tool classes, new transports, new preconditions) without consumers needing a new version to render them. Unacceptable: ad-hoc `message: string` as the only failure surface. ### 6. Vendor-neutral separation from implementation [Section titled “6. Vendor-neutral separation from implementation”](#6-vendor-neutral-separation-from-implementation) The protocol package imports nothing from a specific runtime, transport, cloud vendor, or framework. `@ggui-ai/protocol` MUST remain consumable by a third-party implementation that has never seen `@ggui-ai/mcp-server`. Violation of this criterion is the loudest signal that what you have is an SDK feature pretending to be a protocol. *** ## The conformance kit [Section titled “The conformance kit”](#the-conformance-kit) The kit lives at [`packages/protocol-conformance`](https://github.com/ggui-ai/ggui/tree/main/packages/protocol-conformance) in the open repo — a fixture-based test suite a candidate implementation runs against to demonstrate conformance. ```bash pnpm add -D @ggui-ai/protocol-conformance ``` Beyond the WS runner, the package ships pure-function catalogs for the gadget obligations — schema, registration, and resolution conformance — importable from `@ggui-ai/protocol-conformance/{schema-conformance,registration-conformance,resolution-conformance}`; the raw fixture catalog is also exported at `@ggui-ai/protocol-conformance/fixtures`. Programmatic and CLI entry points: ```ts import { runConformance } from "@ggui-ai/protocol-conformance"; const result = await runConformance({ serverUrl: "http://localhost:3000", auth: { kind: "bearer", token: process.env.TOKEN! }, }); if (result.failed.length > 0) process.exit(1); ``` ```bash npx ggui-protocol-conformance --url http://localhost:3000 --auth bearer:$TOKEN ``` `serverUrl` / `--url` take the implementation’s **base** `http://` / `https://` URL — the runner appends `/ws` and derives the `ws://` / `wss://` scheme itself. **Transport.** v1.0 is **WebSocket-only** — the canonical ggui transport (see the [WebSocket Protocol reference](/api/websocket-protocol/)). The kit’s `TransportConfig` is an extensibly-closed union, so later bindings (stdio MCP, HTTP long-poll) can be added post-v1.1 without breaking the public API. **Path-A vs Path-B fixtures.** The fixture catalog spans both wire-observable claims and surface-observable claims. The runner handles **Path-A** — behaviors a runner can assert from WS frames alone (no MCP-Apps-host adapter, no Playwright). **Path-B** fixtures (e.g., `bootstrap-failure`, `props-update`) require a browser-host harness driving Playwright + `page.route()` fault injection + DOM assertion; they are recorded as SKIP on the WS runner, not FAIL. The partition is intentional: Path-A FAILs are vendor-neutrality bugs the server owns; Path-B SKIPs are claims a different driver is responsible for. The kit covers: * **Envelope round-trip** — every fixture in the table can be emitted, observed, validated, and round-tripped. * **Reserved-channel authority** — the implementation rejects agent-authored `streamSpec` entries in the `_ggui:` namespace and validates the platform-owned shapes (`_ggui:preview`, `_ggui:lifecycle`). * **Schema enforcement** — `actionSpec[action].schema` ⊆ the hinted tool’s `inputSchema`, with a `SCHEMA_MISMATCH_ERROR` push-time rejection on violation. * **Sequencing** — `seq` is gap-free per-session, `fromSeq` replay returns the right tail, `replayTruncated` is honored when the requested cursor is unrecoverable. * **Version handshake** — schema-version stamping on every envelope; `UPGRADE_REQUIRED` emission on mismatch (post-launch — pre-launch is advisory). * **Action persistence** — an action frame round-trips to an ack carrying `payload.sequence`, proving the event landed on the GguiSession’s consume buffer (append-then-ack). * **Contract enforcement at receipt** — an action for an undeclared name is rejected with a `CONTRACT_VIOLATION` error frame and nothing reaches the consume buffer. A change is **breaking** iff at least one fixture that passed against version N now fails against version N+1 when the only change is the protocol version. See [Version policy → §2](/protocol/version-policy/#2-breaking-change-definition--the-kit-is-the-arbiter) for the policy this anchors. *** ## Pre-launch vs launch posture [Section titled “Pre-launch vs launch posture”](#pre-launch-vs-launch-posture) Pre-launch (`draft-` versions), some protocol criteria are intentionally at ⚠️ — flagged gaps with owners and closing slices. The point is not zero gaps forever; it is **zero silent gaps**. | Criterion | Pre-launch posture | Launch (v1.0) | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | Version negotiation | Envelope `schemaVersion`: advisory stamp; consumers MUST NOT reject on mismatch. Subscribe handshake (`supportedVersions` / `serverVersion`): server default `versionPolicy: 'reject'` — emits `UPGRADE_REQUIRED` and closes; `'advisory'` is a legacy opt-out for migration windows. | Same mechanisms; envelope stamps stay advisory, the subscribe handshake stays the rejection point. Mismatched majors surface as `UPGRADE_REQUIRED`. | | Conformance kit | Optional today; available for first-party servers + early third-party implementers. | Required before third-party implementers are invited to build on the protocol. | | Schema-compat checker | Render-time + console blueprint-try (`SCHEMA_MISMATCH_ERROR` rejection on the `ggui_render` tool result); operator policy `'reject' \| 'warn' \| 'off'` (default `'reject'`). | Same; default unchanged. | At launch, all load-bearing boundaries MUST be at 4/4 contract + 6/6 protocol for any layer described as a public interop surface. Load-bearing = any boundary a third-party implementer is expected to adopt. Internal-only boundaries may sit at lower scores if the gap is explicitly scoped to internal use. *** ## Anti-patterns [Section titled “Anti-patterns”](#anti-patterns) Things that feel contract-shaped but fail the bar: | Looks like | Is actually | Why | | ------------------------------------- | ---------------------------- | ---------------------------------------------------------- | | ”TypeScript type is the contract” | Shape-only | Types say what, not who/when/what-on-violation | | ”Docstring says MUST” | Author discipline | Prose without mechanism decays | | ”A validator function exists” | Half-contract | Validator without observable failure path wastes the check | | ”Error gets logged” | Not observable | Logs aren’t observability unless somebody reads them | | ”Pre-launch advisory” | Infrastructure, not contract | Valid interim stance; MUST flag the gap + name the flip | | ”We cover the common cases” | Denylist discipline | Rock-paper-scissors with future adversaries | | ”Three similar implementations agree” | Folklore | Interop-by-intuition is not interop | If a new “contract” maps to a row here, either strengthen it to meet the bar or pick a different word. *** ## Vocabulary [Section titled “Vocabulary”](#vocabulary) Used precisely throughout this site: * **Shape** — a TypeScript type with no enforcement story. * **Convention** — author discipline; no mechanism. * **Contract** — passes the 4-criterion bar. * **Protocol** — passes the 6-criterion bar; a set of contracts with sequencing + versioning + conformance-kit. If a doc says “this contract is enforced by convention” — that’s a category error and either the contract framing or the convention framing is wrong. *** ## See also [Section titled “See also”](#see-also) * [Protocol overview](/protocol/overview/) — three-channel topology and reference implementation. * [Version policy](/protocol/version-policy/) — semver semantics, breaking-change definition, deprecation timeline. * [Envelopes](/protocol/envelopes/) — wire shapes the conformance kit asserts on. * [Conformance kit on GitHub](https://github.com/ggui-ai/ggui/tree/main/packages/protocol-conformance) — the test package itself. # Live-channel envelopes > Wire shapes for ActionEnvelope (inbound), StreamEnvelope (outbound), and the reserved _ggui namespace. The live WebSocket carries two envelope shapes: | Envelope | Direction | Carries | | ---------------- | --------------- | ----------------------------------------------- | | `ActionEnvelope` | client → server | A canonical user action (form submit, click, …) | | `StreamEnvelope` | server → client | An outbound delivery on a named stream channel | Canonical wire reference. Shapes below mirror the TypeScript in [`@ggui-ai/protocol`](https://github.com/ggui-ai/ggui/tree/main/packages/protocol/src) verbatim: `types/events.ts` (ActionEnvelope), `types/live-channel.ts` (StreamEnvelope). *** ## ActionEnvelope [Section titled “ActionEnvelope”](#actionenvelope) Inbound live-channel envelope — the body of a `type: 'action'` WebSocket message. Flat, narrow, limited to fields the server actually enforces or diagnostic fields real consumers populate today. ```ts interface ActionEnvelope { sessionId: string; // required — render identity type: EventType; // required — see EventType below payload?: TPayload; // shape depends on `type` clientSeq?: number; // client-monotonic dedup hint schemaVersion?: string; // producer's PROTOCOL_SCHEMA_VERSION (advisory pre-launch) } ``` | Field | Type | Required | Semantics | | --------------- | ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sessionId` | `string` | Yes | Server enforces subscriber-render binding — envelopes whose `sessionId` doesn’t match the render the WebSocket subscriber is bound to are rejected with `SESSION_MISMATCH`. | | `type` | `EventType` | Yes | Always `data:submit` — the only member of the `EventType` union (see below). The active render’s `actionSpec` gates which action names are accepted. (The pre-actionSpec `EventSubscription` / `DEFAULT_SUBSCRIPTION` gating shapes were deleted from `@ggui-ai/protocol` — there is no subscription gating on the wire.) | | `payload` | `TPayload?` | No | For `type: 'data:submit'` this carries an `ActionEventValue` shape (`{action, data, tool?}`) whose `data` field is validated against the render’s `actionSpec[action].schema`. | | `clientSeq` | `number?` | No | Client-monotonic sequence number for at-least-once dedup. Declared shape; no server enforcement today (no inbound dedup infrastructure yet). Clients SHOULD populate when their transport can replay (e.g., reconnect-with-backfill). | | `schemaVersion` | `string?` | No | Protocol schema version stamped by the producer. Pre-launch: advisory — consumers MUST NOT reject on mismatch. Post-launch: receiving major mismatches surface as `UPGRADE_REQUIRED`. | ### Fields intentionally NOT on the envelope [Section titled “Fields intentionally NOT on the envelope”](#fields-intentionally-not-on-the-envelope) These fields appear on neighboring shapes but are excluded from `ActionEnvelope` by design: | Field | Why omitted | | --------------------------------- | ------------------------------------------------------------------------------------------------------- | | `appId` | Server resolves it from the render; client-claimed values are ignored for enforcement. | | `userId` / `user` | Diagnostic render metadata captured at subscribe time, not per-delivery. | | `deviceInfo` / `interfaceContext` | Same as above — render-level, not action-level. | | `componentId` / `contractHash` | Diagnostic; no enforcement consumer today. | | `timestamp` | Server uses its own clock for ordering + log emission; client-supplied timestamps aren’t authoritative. | | `correlationId` | The doctrine names this for agent-push ↔ user-action pairing; `sessionId` covers the narrow case today. | ### `EventType` [Section titled “EventType”](#eventtype) `EventType` is a single-member union — `'data:submit'` is the only action type the protocol recognizes: | Type | Notes | | ------------- | ----------------------------------------------------------------------- | | `data:submit` | Carries `ActionEventValue` (`{action, data, tool?}`); schema-validated. | The old `data:change` / `lifecycle:focus` / `lifecycle:blur` / `interaction:click` / `interaction:hover` / `interaction:scroll` / `error:validation` / `error:connection` members were removed in `draft-2026-06-12` — they had no producers. ### `ActionEventValue` [Section titled “ActionEventValue”](#actioneventvalue) Payload shape for `data:submit`: ```ts interface ActionEventValue { action: string; // action ID from the contract (e.g. "submit", "archive") data: TData; // action payload (e.g. form data) tool?: string; // MCP tool name mirrored from actionSpec[action].nextStep (when declared) } ``` **Derivation.** `tool` is derived server-side from `actionSpec[action].nextStep` at event-build time — clients do not populate it. When the action has no declared `nextStep`, `tool` is absent — the agent decides the next tool freely from broader context. The hint is advisory either way; the agent owns the call decision. *** ## StreamEnvelope [Section titled “StreamEnvelope”](#streamenvelope) Outbound live-channel envelope — the body of a `type: 'data'` WebSocket message. Carries a single delivery on a named stream channel. ```ts interface StreamEnvelope { sessionId: string; // required channel: string; // required — keys into streamSpec mode: StreamChannelMode; // required — 'append' | 'replace' payload: JsonValue; // required — channel-specific shape complete?: boolean; // terminal marker for completable channels seq?: number; // server-assigned monotonic outbound sequence schemaVersion?: string; // producer's PROTOCOL_SCHEMA_VERSION } ``` | Field | Type | Required | Semantics | | --------------- | ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sessionId` | `string` | Yes | Render this delivery belongs to. | | `channel` | `string` | Yes | Channel name. Keys into the agent’s declared `streamSpec`. Names starting with `_ggui:` are server-owned (see [Reserved channels](#reserved-channels)). | | `mode` | `StreamChannelMode` | Yes | State-folding mode. `'append'` (default for narrative streams — message log, telemetry) accumulates deliveries; `'replace'` (default for snapshot streams — task progress, session state) replaces the current value. Senders declare; receivers honor. Typically equals the channel’s declared `mode` on the spec, but the envelope is the authoritative per-delivery signal. | | `payload` | `JsonValue` | Yes | Validated against `streamSpec[channel].schema`. Shape is channel-specific; consumers typecheck via contract inference when they use `defineContract` + `useStream`. | | `complete` | `boolean?` | No | Terminal completion marker — truthy on the last delivery for a completable channel (one declared with `complete: true` on the spec). Consumers use this to transition subscribers into a “channel closed” state. Absent on non-terminal deliveries. | | `seq` | `number?` | No | Render-scoped monotonic outbound sequence. Server-assigned; clients MUST NOT populate it on producer-side inputs. Gap-free within a single render, starting at 1. Used by the client to track `lastSeenSeq` for reconnect (pass it back as `SubscribePayload.fromSeq`) and to dedupe deliveries (at-least-once semantics). OPTIONAL today because hosted cloud doesn’t yet stamp `seq`; OSS `@ggui-ai/mcp-server` always populates it. A future slice promotes this to required. | | `schemaVersion` | `string?` | No | Same advisory-pre-launch / `UPGRADE_REQUIRED`-post-launch semantics as on `ActionEnvelope`. | ### Fields intentionally NOT on the envelope [Section titled “Fields intentionally NOT on the envelope”](#fields-intentionally-not-on-the-envelope-1) | Field | Why omitted | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `replay` | Per-channel policy declared on `streamSpec[channel].replay`. A per-delivery field would imply replay can vary message-to-message, which it can’t. | | `timestamp` | Replay correctness needs `seq` only; timestamp is a future optional addition driven by a concrete client-UX need. | *** ## Reserved channels [Section titled “Reserved channels”](#reserved-channels) Channel names starting with `_ggui:` are **reserved** for the server. Agent-authored `streamSpec` MUST NOT declare any name in this namespace; structural validation rejects every reserved-prefix entry with the message `Stream channel '' is in the reserved '_ggui:' namespace — server-owned channels cannot be declared in agent streamSpec`. Two channel names are recognized today: | Channel | Owner | Payload shape | Purpose | | ----------------- | ------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `_ggui:preview` | Server (A2UI) | A2UI `ServerMessage` — see `@ggui-ai/preview-a2ui` | Provisional A2UI assembly stream emitted by the server during fresh-gen `ggui_render` flows. The renderer subscribes implicitly and dispatches the payload through its preview surface. | | `_ggui:lifecycle` | Server | `GguiLifecyclePayload` | Generation-progress lifecycle kinds (`handshake_started`, `handshake_completed`, `render_started`, `consume_polling`) the renderer surfaces as a progress affordance. | A typo inside the reserved namespace (e.g. `_ggui:preveiw`) is NOT recognized — delivery falls through to the normal “unknown channel” rejection rather than silently passing as a reserved channel. The `_ggui:contract-error` channel was a reserved channel in earlier drafts but was removed entirely in `draft-2026-06-11` — the channel, its payload shape, and its validator are gone. Contract violations now surface as a typed `CONTRACT_VIOLATION` error frame on the live channel (code `-32020`) on the call that caused them; nothing lands on the consume buffer. *** ## Schema versioning [Section titled “Schema versioning”](#schema-versioning) The `schemaVersion` field is present on both envelopes. It carries the producer’s `PROTOCOL_SCHEMA_VERSION` constant. **Pre-launch (`draft-` versions):** advisory. Consumers MUST NOT reject on mismatch; missing `schemaVersion` fields are normal. **Post-launch:** receiving an envelope whose major version diverges from the consumer’s known major surfaces as a live-channel error with `code: UPGRADE_REQUIRED`. The handshake resolution flow is documented in the [WebSocket Protocol](/api/websocket-protocol/) reference. See [Version policy](/protocol/version-policy/) for the full mapping of what counts as a major / minor / patch bump. *** ## See also [Section titled “See also”](#see-also) * [WebSocket Protocol](/api/websocket-protocol/) — live-channel message types (`subscribe`, `action`, `ack`, `render`, `data`, `error`) that carry these envelope payloads. * [MCP Protocol](/api/mcp-protocol/) — MCP JSON-RPC methods (`ggui_handshake`, `ggui_render`, `ggui_consume`, etc.). * [Protocol overview](/protocol/overview/) — the three-channel topology. * [Version policy](/protocol/version-policy/) — semver semantics, breaking-change definition, deprecation timeline. * [`@ggui-ai/protocol` source](https://github.com/ggui-ai/ggui/tree/main/packages/protocol/src) — canonical TypeScript definitions. # Protocol overview > ggui is an open protocol for AI agents to render interactive UIs over three wire channels. MCP-native, framework-agnostic, server-enforced. `ggui` is an **open protocol** that lets AI agents render interactive UIs to humans. An agent describes what it needs in natural language; ggui generates React components, delivers them over a typed live channel, and routes user actions back through a server-side enforcement point. This site documents the protocol itself, version `draft-2026-06-12` (see `PROTOCOL_SCHEMA_VERSION` in [`@ggui-ai/protocol`](https://github.com/ggui-ai/ggui/tree/main/packages/protocol/src/version.ts)). Everything below is implementable from the spec — the open-source [`ggui serve`](/cli/serve/) is the reference conformant implementation (a hosted endpoint at `mcp.ggui.ai` is coming soon). The `@ggui-ai/*` packages are the reference SDKs. ## Three parties, three channels [Section titled “Three parties, three channels”](#three-parties-three-channels) ```plaintext ┌───────────────────────┐ │ user client │ │ (React / RN / web) │ └─────┬────────────┬────┘ │ │ chat live (WebSocket) (HTTP SSE) ↑↓ │ │ ┌────────▼────┐ ┌───▼────────────┐ │ wrapped- │ │ │ │ agent │ │ core-mcp │ │ (developer │───▶ (session │ │ code) │ MCP authority) │ └─────────────┘ └────────────────┘ MCP (over HTTP) ``` | Channel | Direction | Transport | Purpose | Status | | ------- | ---------------------- | ------------- | ------------------------------------------------- | --------- | | Chat | user ↔ wrapped-agent | HTTP SSE | Conversational surface (chat-completion style) | Optional | | MCP | agent ↔ core-mcp | MCP over HTTP | Tool control + session mutation | Mandatory | | Live | core-mcp ↔ user client | WebSocket | Live UI session delivery + canonical user actions | Mandatory | The MCP and live channels are the **protocol kernel** — every conformant implementation MUST provide them. The chat channel is product-mandatory (the OSS `ggui serve` ships a chat surface) but protocol-optional: an embed that uses ggui purely for typed live UIs, with no conversational chat, is still conformant. The WebSocket endpoint is `ws://127.0.0.1:6781/ws` (default) when running `ggui serve` locally; self-hosters expose it as `wss:///ws`. (A hosted endpoint at `wss://mcp.ggui.ai/ws` is coming soon.) ## Why the live channel is mandatory [Section titled “Why the live channel is mandatory”](#why-the-live-channel-is-mandatory) The typed live-channel contract needs a server-side enforcement point. That point is the live channel itself. A `streamSpec` declares named streams, payload schemas (validated as `StreamEnvelope`s), replay policy, ordering, and completion semantics. Subscriptions declare which events the client UI consumes. None of that means anything unless a non-agent authority validates it on the wire. If the agent shipped bytes directly to the user, the “contract” would be documentation, not contract — see [Conformance](/protocol/conformance/) for the 4-criterion contract bar this enforces. So **no live channel, no enforcement point, no contract.** The live channel and the typed live-channel contract are a pair — reconsider one, you reconsider the other. ## Wire surfaces [Section titled “Wire surfaces”](#wire-surfaces) Each channel maps to a documented wire surface on this site: | Surface | Channel | What it covers | | ---------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [MCP Protocol](/api/mcp-protocol/) | MCP | JSON-RPC methods (canonical lifecycle order): `ggui_handshake`, `ggui_render`, `ggui_consume`, `ggui_update`, `ggui_emit`, `ggui_get_session`, `ggui_list_sessions`, plus gadget/theme/blueprint discovery (`ggui_list_gadgets`, `ggui_list_themes`, `ggui_list_featured_blueprints`, `ggui_search_blueprints`, `ggui_render_blueprint`) | | [WebSocket Protocol](/api/websocket-protocol/) | Live | Subscribe / `ActionEnvelope` / ack / render / `StreamEnvelope`; replay; reconnection | | [MCP Apps support](/api/mcp-apps/) | MCP + Live | Resource shape (`{contents:[{uri,mimeType,text}]}`); host-side iframe-runtime boot | | [OAuth (`ggui serve --oauth`)](/api/oauth/) | MCP | OAuth 2.1 + PKCE + Dynamic Client Registration for hosts with no pre-shared bearer | ## Reference implementation [Section titled “Reference implementation”](#reference-implementation) The open implementation lives at [`github.com/ggui-ai/ggui`](https://github.com/ggui-ai/ggui): * `packages/mcp-server` — the MCP + live-channel server. * `packages/ggui-react` — the host-side SDK. * `packages/ggui-cli` — ships [`ggui serve`](/cli/serve/), which runs the whole protocol locally on one command. The self-hosted open-source path is the available-now story — `ggui serve` runs the whole protocol on one command. A hosted endpoint at `mcp.ggui.ai` (same protocol, managed infrastructure, no self-host required) is coming soon. ## Core vocabulary [Section titled “Core vocabulary”](#core-vocabulary) Three nouns recur on every page. Get them right and the rest of the spec falls into place — see the [glossary](/glossary/) for the full list. * **Gadget** — a renderer-side capability (Mapbox, Leaflet, a charting library). Declared per-app in `ggui.json#app.gadgets` (the `@ggui-ai/gadgets` stdlib is always the floor); loaded at iframe boot. The agent never touches gadget code. * **Tool** — an agent-side action exposed over MCP (`ggui_render`, `ggui_update`, etc.). Tools mutate session state. * **Blueprint** — a cached recipe (component code + contract) keyed by intent. Matched on the fast path; generated on miss. Gadgets and tools are the protocol’s two **symmetric capability surfaces** — gadgets give the renderer something to render with; tools give the agent something to act with. Both are operator-bounded and declared per-app (`clientCapabilities.gadgets`, `agentCapabilities.tools`). See [glossary → Capabilities](/glossary/#capabilities). ## What the protocol is not [Section titled “What the protocol is not”](#what-the-protocol-is-not) * **Not a renderer.** The protocol carries component code and props; how the host evaluates that code is its concern. The reference SDK uses dynamic ESM import plus the `@ggui-ai/iframe-runtime` bundle (the self-contained ESM bundle that boots inside the MCP-Apps iframe), but a conformant host can swap in a sandboxed iframe, a server-rendered HTML pipeline, or anything else. * **Not a UI library.** Components are generated per render by the agent; ggui ships no fixed component set. Primitives (Button, Input) are catalog-declared, not protocol-declared. * **Not framework-coupled.** The wire is JSON over HTTP and WebSocket. React is the most-developed SDK today, but `@ggui-ai/protocol` types and `@modelcontextprotocol/sdk` (Anthropic’s official MCP TypeScript SDK) are framework-neutral. ## Versioning + conformance [Section titled “Versioning + conformance”](#versioning--conformance) The protocol follows semver. The arbiter for “what counts as a breaking change” is the **conformance kit** at [`packages/protocol-conformance`](https://github.com/ggui-ai/ggui/tree/main/packages/protocol-conformance) — a fixture-based test suite that any candidate implementation runs against. A change is **major** iff at least one conformance fixture that passed against version N now fails against version N+1, with the protocol version as the only delta. See the [Version policy](/protocol/version-policy/) for the full semver mapping, deprecation timeline, and version support matrix. ## See also [Section titled “See also”](#see-also) * [MCP Protocol reference](/api/mcp-protocol/) — MCP wire grammar. * [WebSocket Protocol reference](/api/websocket-protocol/) — live-channel wire grammar. * [Envelopes](/protocol/envelopes/) — the live-channel wire shapes: `ActionEnvelope` (inbound) and `StreamEnvelope` (outbound), plus the reserved `_ggui:` channel namespace. * [Bootstrap handshake](/protocol/bootstrap-handshake/) — host-side postMessage + JSON-RPC contract for mounting a session in an iframe. * [Conformance](/protocol/conformance/) — the kit, the bar, and how to claim conformance. * [`ggui serve`](/cli/serve/) — run the protocol locally. # Version policy > Major / minor / patch semantics for the ggui protocol, deprecation timeline, support matrix, and CI enforcement. > **Semver promise:** a change to `@ggui-ai/protocol` is breaking if-and-only-if a consumer built against the prior version now fails the conformance kit. This page defines “major”, “minor”, and “patch” on the ggui protocol, how deprecation windows work, which server ↔ client pairs are supported, and how a breaking change is migrated. The canonical version constant is `PROTOCOL_SCHEMA_VERSION` (an alias of `PROTOCOL_VERSION` in [`@ggui-ai/protocol`](https://github.com/ggui-ai/ggui/blob/main/packages/protocol/src/version.ts)). Current value: `draft-2026-06-12`. Wire-level negotiation runs through the schema-version handshake; mismatches surface as the `UPGRADE_REQUIRED` error. The current server default is `versionPolicy: 'reject'` — on mismatch the server emits `UPGRADE_REQUIRED` and closes the connection; `'advisory'` is a legacy opt-out that keeps it open. *** ## 1. Semver semantics applied to the protocol [Section titled “1. Semver semantics applied to the protocol”](#1-semver-semantics-applied-to-the-protocol) The protocol follows semver. What counts as each bump kind is defined by the **conformance kit** ([`packages/protocol-conformance`](https://github.com/ggui-ai/ggui/tree/main/packages/protocol-conformance)), not by surface-syntax changes in the `@ggui-ai/protocol` package. ### Major (N → N+1) [Section titled “Major (N → N+1)”](#major-n--n1) A bump is **major** iff at least one conformance-kit fixture that passed against version N now fails against version N+1 when the only change is the protocol version. Examples of changes that are major: * Renaming a **reserved channel** (e.g., `_ggui:preview` → `_ggui:assembly`). * Removing a canonical live-channel error code that the kit asserts (e.g., deleting `CONTRACT_VIOLATION`). * **Narrowing** an extensibly-closed union (e.g., collapsing `SubmitActionKind` variants so previously-recognized kinds now fail validation). * Changing the shape of an **envelope** (`ActionEnvelope`, `StreamEnvelope`) in a way that invalidates fixtures emitted by prior-version producers — required-field additions, required-field renames, required-field type changes. * Tightening a `MUST` / `MUST NOT` clause in the spec such that prior-conformant implementations become non-conformant. * Changing handshake semantics in a way that rejects a subscribe that would previously have succeeded (e.g., the `versionPolicy` default flip `advisory` → `reject` — already shipped on 2026-04-24 as a pre-launch config-default change with its own release note; post-v1.0, a flip of this shape is major). * Removing or replacing a **transport binding** previously declared conformant. ### Minor (N.x → N.(x+1)) [Section titled “Minor (N.x → N.(x+1))”](#minor-nx--nx1) A bump is **minor** iff every conformance-kit fixture that passed against N.x still passes against N.(x+1), and the delta is additive. Examples of changes that are minor: * Adding a new **`channel_error` code** literal (consumers that don’t recognize it degrade per the extensibly-closed union rule). * Adding a new **observability event kind** to the renderer’s `ggui:observe` postMessage union (extensibly-closed — see the [Bootstrap handshake](/protocol/bootstrap-handshake/) page). * Adding an **optional field** on an envelope. Pre-existing consumers see `undefined` and MUST behave as before. * Adding a new **reserved channel** whose absence is not a failure mode for prior-version consumers. * Adding a new **canonical live-channel error code** (the `code` field is typed open). * Adding a new **transport binding** (e.g., stdio MCP, HTTP long-poll) while keeping WebSocket canonical. ### Patch (N.x.y → N.x.(y+1)) [Section titled “Patch (N.x.y → N.x.(y+1))”](#patch-nxy--nxy1) A bump is **patch** iff the only changes are documentation clarifications, fixture additions that do not change assertions on prior-version consumers, or internal implementation adjustments to first-party packages that do not affect the wire or the kit. Examples: * Spec prose clarifications that close a reader-ambiguity without changing obligations. * New conformance-kit fixtures that assert behavior already required by the prior version’s spec text. * Bug fixes in first-party servers / clients that bring them back into conformance (the bar was always there — the code now honors it). ### The `draft-` prefix [Section titled “The draft- prefix”](#the-draft--prefix) Pre-v1 versions use a `draft-` prefix (e.g., `draft-2026-06-12`). While `draft-`, the semver rules above describe **intent**, not **obligation** — the protocol reserves the right to ship breaking changes without a migration doc until the first stable release tags `v1.0`. **Rule flip at v1.0:** once `PROTOCOL_SCHEMA_VERSION` drops the `draft-` prefix, every major bump MUST have a migration doc (CI-enforced) and every deprecation MUST honor the window described in §3. *** ## 2. Breaking change definition — the kit is the arbiter [Section titled “2. Breaking change definition — the kit is the arbiter”](#2-breaking-change-definition--the-kit-is-the-arbiter) > **A change is breaking if-and-only-if a consumer built against the prior version now fails the conformance kit.** Anchor every future “is this breaking?” debate to a kit run. Opinion, intent, and prose-level spec reading are NOT the arbiter — the kit is. Operational consequences: 1. If you’re unsure whether a PR is breaking, **run the kit** against the prior-version tag and against the PR branch. If fixtures that passed before now fail, the PR is major. 2. If the kit passes but you “feel” the change is risky, **add a fixture** that captures the worry. Either the fixture passes (the change is not breaking) or it fails (the change is breaking and you just found out) — both outcomes are productive. 3. If you think a change is major but the kit disagrees, the kit has a gap. Patch the kit in the same PR; the patched kit decides. This anchor means every change’s breaking-ness is **observable and reproducible**, not a matter of taste. *** ## 3. Deprecation timeline [Section titled “3. Deprecation timeline”](#3-deprecation-timeline) Deprecation is the only graceful path from a minor-version ship to a major-version removal. ### The window [Section titled “The window”](#the-window) * **v(N)** — the version in which a surface is first tagged `@deprecated` (in TSDoc) AND documented in the release notes as deprecated. The surface MUST continue to work identically to the prior version; `@deprecated` is a signal to consumers, not a behavior change. * **v(N+1)** — deprecated surface still works. Callers SHOULD migrate in this window. Release notes repeat the deprecation warning. * **v(N+2)** — removal is allowed here at the earliest. Removal is a major bump, so this version is v(N+2) = major. The two-minor window guarantees consumers saw at least one full minor cycle with the `@deprecated` warning before removal. ### Minimum [Section titled “Minimum”](#minimum) **At least two minor versions MUST elapse between `@deprecated` and removal.** If N is the first deprecated version and N+2 is the major that removes it, the intermediate v(N+1) minor MUST ship. Shorter windows (v(N) deprecated → v(N+1) removed) are NOT allowed for non-security changes. ### Security-fix escape hatch [Section titled “Security-fix escape hatch”](#security-fix-escape-hatch) A **critical security fix** MAY skip the window — shipping a breaking change without a prior `@deprecated` minor — if and only if: 1. The release note explicitly names the CVE or security class. 2. The release note explains why the window was skipped. 3. A migration doc per §5 ships alongside the release. Non-security urgency (e.g., “this mistake is embarrassing”) is NOT grounds for skipping the window. ### What “deprecated” means on the wire [Section titled “What “deprecated” means on the wire”](#what-deprecated-means-on-the-wire) The protocol does not have a wire-level “deprecated field” marker. Deprecation lives in TSDoc on the `@ggui-ai/protocol` types and in the release notes. Consumers parsing the wire cannot detect a field is `@deprecated` from the frame alone — they learn it from the package changelog. ### Policy-default flips count as breaking [Section titled “Policy-default flips count as breaking”](#policy-default-flips-count-as-breaking) Changing a **default** that the wire handshake depends on is breaking under §2 because consumers that relied on the prior default observably fail against the new default. The canonical example already happened pre-launch: the `versionPolicy` default flip `advisory` → `reject` shipped on 2026-04-24 as a config-default change with its own release note. Post-v1.0, a flip of that shape MUST use the same window: ship the new value as an opt-in in v(N), document the flip in the release notes, then flip the default in v(N+2). *** ## 4. Version support matrix [Section titled “4. Version support matrix”](#4-version-support-matrix) Which server versions support which client versions. Populated at launch (v1.0); the row below is illustrative — the protocol is pre-v1 (`draft-2026-06-12`) today: | Server `PROTOCOL_SCHEMA_VERSION` | Min client | Max client | Status | EOL date | | -------------------------------- | ---------- | ---------- | ------------------------ | -------- | | *`1.0.x`* | *`1.0.0`* | *`1.0.x`* | *current (illustrative)* | — | ### Column meanings [Section titled “Column meanings”](#column-meanings) * **Server version** — the `PROTOCOL_SCHEMA_VERSION` the server emits in the subscribe-ack payload’s `serverVersion`. * **Min client / Max client** — the lowest / highest entries in the client’s `CLIENT_SUPPORTED_VERSIONS` set guaranteed to subscribe successfully. * **Status** — one of: * `current` — actively maintained; all fixes land here. * `security-only` — no new features; only security patches. * `EOL` — no longer maintained. Servers on EOL versions MAY refuse to start. * **EOL date** — the date `current` transitions to `security-only`, or `security-only` transitions to EOL. ### Matrix update cadence [Section titled “Matrix update cadence”](#matrix-update-cadence) * New **minor** ship → append a row; prior row may update Max client. * New **major** ship → append a new row; prior-major row transitions to `security-only` for at least 6 months before EOL. * Security-only → EOL → at least 6 additional months. ### Out-of-matrix clients [Section titled “Out-of-matrix clients”](#out-of-matrix-clients) If a client targets a version outside the matrix, the server emits `UPGRADE_REQUIRED`. Whether the connection stays open depends on the server’s `versionPolicy` at the time. *** ## 5. Migration-guide requirement [Section titled “5. Migration-guide requirement”](#5-migration-guide-requirement) Every major bump MUST ship a migration doc at `docs/protocol/migrations/v-to-v.md`. (Current pre-v1 drafts use date-named migration docs — e.g. `2026-06-05-gguisession-reintroduction.md`; the `v-to-v.md` pattern applies from v1.0.) The CI check (§7) enforces the file’s existence; content follows a standard template with required sections: * **What changed** — 1–2 paragraph summary. * **Why** — motivation (conformance-kit failure mode that drove the change). * **Breaking-change summary** — bullet list of renamed / removed / tightened surfaces. * **Migration steps per consumer kind** — fixture authors, ConformanceHost implementers, agent builders, SDK consumers. * **Timeline** — dates for v(N) deprecation ship, v(N+1) soft cut, v(N+2) removal. * **Rollback procedure** — how to pin to prior version if a consumer can’t migrate fast enough. *** ## 6. Release cadence expectations [Section titled “6. Release cadence expectations”](#6-release-cadence-expectations) These are targets, not promises: * **Minor (N.x → N.(x+1)):** roughly monthly. Additive adjustments driven by conformance-kit fixture gaps, new observability events, or new canonical error codes tend to accumulate on this cadence. Empty minor cycles are skipped rather than force-shipped. * **Major (N → N+1):** annual or slower. Rare and pre-announced. A major ship is a disruption event for every downstream — the protocol leans hard on minor + deprecation windows to defer majors. * **Patch (N.x.y → N.x.(y+1)):** ad hoc. Doc corrections, fixture additions that tighten existing assertions, and first-party impl bug fixes ship when ready. Announcements ship in the version history maintained in [`@ggui-ai/protocol`’s `version.ts`](https://github.com/ggui-ai/ggui/blob/main/packages/protocol/src/version.ts) and in the public protocol release notes. *** ## 7. CI enforcement [Section titled “7. CI enforcement”](#7-ci-enforcement) Two workflows guard this policy: * **Spec drift** — ensures spec envelope code blocks match the `@ggui-ai/protocol` types. Catches structural drift that would otherwise ship as silent breakage. * **Version migration** — reads `PROTOCOL_SCHEMA_VERSION` on the PR head and on the base ref; if the **major** component changed, asserts the migration doc exists in the PR diff. The second check is the policy’s teeth: you cannot ship a major bump without the migration doc the policy requires. *** ## Appendix: Worked examples [Section titled “Appendix: Worked examples”](#appendix-worked-examples) ### A.1 Adding a new live-channel error code [Section titled “A.1 Adding a new live-channel error code”](#a1-adding-a-new-live-channel-error-code) **Scenario:** a new failure mode — `TOOL_DENIED` — needs to land alongside the existing canonical literals on the WS `error` / `channel_error` frame. * **Bump kind:** minor. Prior-version consumers that don’t know `TOOL_DENIED` see an extensibly-closed (`code: string`) value and MUST degrade gracefully. No kit fixture asserting the prior closed set should fail. * **Required work:** add the constant to `@ggui-ai/protocol`, document it as a canonical live-channel error-code literal, add a conformance-kit fixture asserting the new code round-trips. * **Migration doc:** none needed (not a major bump). ### A.2 Removing a canonical error-code literal [Section titled “A.2 Removing a canonical error-code literal”](#a2-removing-a-canonical-error-code-literal) **Scenario:** `SCHEMA_MISMATCH_ERROR` is merged into `CONTRACT_VIOLATION` with a structured `causedBy`. * **Bump kind:** major. A consumer that pattern-matches on `SCHEMA_MISMATCH_ERROR` now never sees it, fails its fixture. * **Required work:** first ship `@deprecated SCHEMA_MISMATCH_ERROR` in v(N), continue emitting both `SCHEMA_MISMATCH_ERROR` and the new shape during v(N+1), then remove `SCHEMA_MISMATCH_ERROR` emission in v(N+2). * **Migration doc:** `vN-to-v(N+1).md` (enforced by CI on the major-bump PR). Covers the `causedBy` shape, fixture changes, and consumer-side pattern-match migration. ### A.3 Renaming a reserved channel [Section titled “A.3 Renaming a reserved channel”](#a3-renaming-a-reserved-channel) **Scenario:** `_ggui:preview` → `_ggui:assembly` for parity with transport-layer conventions. * **Bump kind:** major. Every consumer that subscribes to the old name now fails. Every fixture that references the old name needs updating. * **Required work:** can NOT ship via deprecation (reserved-channel names are matched verbatim). Must bundle with other breaking changes into the next major. Migration doc is non-trivial — every producer AND consumer changes. * **Operational note:** changes of this shape are exactly why the protocol prefers extensibly-closed unions + additive fields + separate channels over in-place renames. ### A.4 Clarifying a spec MUST [Section titled “A.4 Clarifying a spec MUST”](#a4-clarifying-a-spec-must) **Scenario:** the spec’s `refresh` semantics paragraph has two readings; the kit’s fixture matched only one. * **Bump kind:** patch IF the kit’s existing assertion already covered the intended reading (prose clarifies code); minor IF the clarification surfaces a new required behavior that prior-version impls weren’t necessarily honoring (new assertion); major IF the clarification tightens behavior such that previously-conformant impls now fail. * **Test:** run the kit against the prior-version tag. If it passes, the clarification is patch/minor. If it fails, it was major all along — the original spec text was ambiguous and shipping the clarification is a breaking change. *** ## See also [Section titled “See also”](#see-also) * [Protocol overview](/protocol/overview/) — three-channel topology and reference implementation. * [Conformance kit](https://github.com/ggui-ai/ggui/tree/main/packages/protocol-conformance) — the test suite this policy treats as the arbiter. * [Conformance](/protocol/conformance/) — the 4-criteria contract bar + 6-criteria protocol bar this policy gates. # Gadgets SDK > Wrap any 3rd-party browser library (Leaflet, Mapbox, Stripe, …) into an LLM-callable React hook with `createGguiGadget` from `@ggui-ai/gadgets`. `@ggui-ai/gadgets` is the standard library of browser-capability hooks **and** the wrapper SDK that lets you bind any 3rd-party library into the same uniform contract the LLM already knows. * **STDLIB hooks** — `useGeolocation`, `useCamera`, `useClipboardWrite`, `useClipboardPaste`, `useNotifications`, `useFilePicker`, `useMicrophone`. * **Wrapper SDK** — `createGguiGadget` for Leaflet, Mapbox, Stripe, Chart.js, Three.js, or anything else with a browser API. See [Glossary](/glossary/) for the gadget / tool / blueprint vocabulary, and [Marketplace Registry](/sdk/marketplace/) for distribution. ## Installation [Section titled “Installation”](#installation) ```bash npm install @ggui-ai/gadgets ``` ## Authoring a wrapper [Section titled “Authoring a wrapper”](#authoring-a-wrapper) ```ts import { createGguiGadget } from "@ggui-ai/gadgets"; export const useLeafletMap = createGguiGadget< // TOutput — what the hook resolves with on `status: 'completed'`. { containerRef: (el: HTMLDivElement | null) => void }, // TOptions — what the calling component passes in. { center: [number, number]; zoom: number } >({ // Canonical hook name — the export name a contract references // under clientCapabilities.gadgets[][]. The // `use`-prefixed camelCase name marks this export as a hook. hook: "useLeafletMap", // REQUIRED teaching text. Synth + decision LLM both see this with // a 300-char per-entry budget; description is preserved, usage // truncates first when over budget. description: "Render an interactive Leaflet map with tile layer and pan/zoom controls. Returns a container ref to attach to a

.", usage: "Mount when the intent names a rendered map (location browsing, route preview, points-of-interest grid). Pass `center: [lat, lng]` + `zoom: 2..20`.", // REQUIRED example. JsonValue — concrete shape the LLM uses to // pattern-match on cold gen. example: { call: "const map = useLeafletMap({ center: [37.7749, -122.4194], zoom: 12 });", returns: { status: "completed", value: { containerRef: "" }, }, }, // Optional anti-patterns / library quirks. Surfaces in the // boilerplate generator's prompt; the LLM uses them to avoid known // misuse patterns. gotchas: "Leaflet requires the container

to have a non-zero height before the map mounts — apply `style={{ height: 400 }}` (or similar) directly. Default-marker icons require leaflet.css to be in the document; the styleUrl on this descriptor covers that.", // REQUIRED. `version` is part of the blueprint cache key, so a // wrapper bump automatically invalidates stale cached generations. version: "0.0.1", // `package` AND `version` are both REQUIRED — bare npm name, exact // semver pin (no URLs, no ranges). `bundleUrl` is optional; when // set it wins for boilerplate import emission. // // Resolution order (operator wins over author wins over spec // default): explicit `bundleUrl` → operator `bundleHost` override // → author `bundleHost` → spec default `registry.ggui.ai`. With // `bundleHost` + `package` + `version` the server assembles // `https:///bundles////bundle.js` // — prefer this over hardcoded `bundleUrl`. package: "@my-org/ggui-leaflet", bundleHost: "registry.ggui.ai", // Optional companion CSS bundle. The wrapper SHOULD self-inject // any required CSS in its hook; the styleUrl is purely an origin // declaration so the renderer's CSP allows the load. Same // `bundleHost`-based resolution applies — explicit `styleUrl` // overrides the host-derived `style.css` path. // API-call origins (XHR / fetch / WebSocket / ``). The // renderer's Content-Security-Policy unions these into BOTH // connect-src AND img-src so map tiles loaded via work. connect: ["https://tile.openstreetmap.org"], // Public env keys this wrapper consumes (see "Public env channel" // below). Both wire + registry zod schemas enforce the same // `GGUI_PUBLIC_APP_[A-Z0-9_]+` prefix as App.publicEnv. Leaflet // doesn't need a token; Mapbox does. // requires: ["GGUI_PUBLIC_APP_MAPBOX_TOKEN"], // The React hook. Wrappers bundle their underlying library at // build time (esbuild / tsup) and `import` it inside the hook. // The function MUST return the standard `{value, status, start, …}` // shape that satisfies `GadgetHook`. hookImpl: (props) => { // … wrap Leaflet's lifecycle into ggui's stable hook contract … return { value: { containerRef: () => undefined }, status: "completed", start: async () => undefined, }; }, }); ``` The factory **synchronously zod-validates** the spec at module load. Missing `description` / `usage` / `example`, or a missing `package` / `version`, throws `WrapperConformanceError` with the field path. Authors see the error at import time — not at runtime. `useLeafletMap` is a callable hook; the immutable wrapper descriptor is attached as `useLeafletMap.descriptor`. Operators register the descriptor on `App.gadgets`. For distribution, wrappers ship as a `ggui.gadget.json` manifest (see [Marketplace Registry](/sdk/marketplace/)). The registry’s publish endpoint computes the bundle’s `sha384` and stamps it on the registered entry’s `bundleSri`; `ggui gadget install` writes the descriptor (including `bundleSri` + resolved `bundleUrl`) into `ggui.json#app.gadgets[]`. Hand-authored entries omit `bundleSri` — the iframe runtime falls back to integrity-less dynamic `import()`. Non-stdlib registered descriptors also carry `typesUrl` (HTTPS URL to the wrapper’s `.d.ts`) and `typesSri` (SHA-384 SRI over those types), so the generator can type-check against the wrapper’s real surface. `typesUrl` is REQUIRED at registration time for any non-stdlib package; `typesSri` is stamped by the registry on publish (optional for hand-authored entries). ## Operator registration [Section titled “Operator registration”](#operator-registration) Add the descriptor (or its JSON shape) to `ggui.json#app.gadgets`: A `GadgetDescriptor` is a PACKAGE — `package` + `version` + transport metadata declared once, plus an `exports[]` array carrying each export’s teaching text: ```json { "app": { "slug": "leaflet-demo", "name": "Leaflet gadget demo", "gadgets": [ { "package": "@my-org/ggui-leaflet", "version": "0.0.1", "bundleHost": "registry.ggui.ai", "connect": ["https://tile.openstreetmap.org"], "exports": [ { "hook": "useLeafletMap", "description": "Render an interactive Leaflet map…", "usage": "Mount when the intent names a rendered map…", "example": { "call": "const map = useLeafletMap({ center: [37.7749, -122.4194], zoom: 12 });", "returns": { "status": "completed", "value": { "containerRef": "" } } }, "gotchas": "Leaflet requires the container

…" } ] } ] } } ``` A package that ships more than one export (two hooks, or a hook plus a React `component`) adds further entries to the same `exports` array — the transport metadata is declared once and shared. The CLI threads `app.gadgets` into the in-process `AppMetadataStore` so the same singleton powers `ggui_list_gadgets`, handshake-time prompt injection, render-time validation + enrichment, and CSP derivation. ## Contract gadget refs vs `GadgetDescriptor` [Section titled “Contract gadget refs vs GadgetDescriptor”](#contract-gadget-refs-vs-gadgetdescriptor) Two distinct shapes — do not confuse them. One is the wire map a host agent authors on a contract; the other is the registry-side package descriptor an operator registers. Both are organized around a gadget **package** that ships one or more **exports**, where each export is either a hook (a `use`-prefixed camelCase name) or a component (a PascalCase name): * **Contract gadget refs** — `clientCapabilities.gadgets` on a `DataContract` is a **package-keyed two-level map** carrying IDENTITY ONLY. The outer key is the npm package name; the inner key is the export name; the inner value is a `GadgetExportUse` — `{ description?, usage? }`, usually just `{}` (optional intent-specific override prose). There is NO `hook` / `component` field on the wire — the export-name GRAMMAR is the discriminator: `useGeolocation` is a hook, `LeafletMap` is a component. There is NO `version`, NO `permission`, NO transport metadata, and NO `binding` key. The wire carries `(package, exportName)` and nothing else. * **`GadgetDescriptor`** — the full registry-side PACKAGE descriptor (what operators register on `App.gadgets`). Package-level identity (`package` + `version`) plus transport metadata (bundle URLs, `connect`, `typesUrl` / `typesSri`) declared once, plus an `exports: GadgetExport[]` array (≥1). Each `GadgetExport` is a field-presence-discriminated union — a hook export `{ hook, … }` or a component export `{ component, … }` — carrying that export’s teaching text + per-export `permission`. `version`, transport metadata, `permission`, and `requires` ALL resolve server-side from this descriptor at render time; the contract author never restates them. `createGguiGadget` authors a single-export package; multi-export packages add further `exports` entries. ## Agent reference shape [Section titled “Agent reference shape”](#agent-reference-shape) Once a package is registered on `App.gadgets`, contracts reference its exports through the package-keyed `clientCapabilities.gadgets` map — outer key = package name, inner key = export name: ```ts const contract = { // … propsSpec / actionSpec / contextSpec … clientCapabilities: { gadgets: { "@my-org/ggui-leaflet": { // PascalCase key ⇒ a component export. Empty value is the // common case; an optional `{ description?, usage? }` override // sharpens the teaching text for this specific intent. LeafletMap: {}, }, "@ggui-ai/gadgets": { // `use`-prefixed camelCase key ⇒ a hook export. useGeolocation: {}, }, }, }, }; ``` The wire is identity-only: render resolves each `(package, exportName)` pair against the registered `GadgetDescriptor` and enriches the persisted `ComponentGguiSession` with the canonical `version`, transport metadata, teaching text, and `permission`. To walk the map in code, call `listContractGadgets(contract)` — it flattens the package-keyed map into a `readonly GadgetUse[]`, each entry `{ package, name, description?, usage? }`. References to unregistered exports reject at render validation with `gadget_not_registered` and a did-you-mean hint when a close stdlib match exists (Levenshtein < 3 cutoff). Render also rejects with `gadget_package_mismatch` when a referenced export name belongs to a different registered package than the one keyed. ## What the renderer derives [Section titled “What the renderer derives”](#what-the-renderer-derives) When ANY gadget in `clientCapabilities.gadgets` declares `bundleUrl` / `styleUrl` / `connect[]`, the render’s spec-canonical `_meta.ui.csp` block carries the derived `{ connectDomains, resourceDomains }` (per the MCP Apps spec). The MCP-Apps host applies them to the sandboxed iframe as a Content-Security-Policy — conceptually: ```plaintext script-src 'self' 'unsafe-inline' ; style-src 'self' 'unsafe-inline' ; connect-src 'self' ; img-src 'self' data: ``` * `'unsafe-inline'` on `script-src` is needed because the render shell embeds the bootstrap as an inline `