--- title: Protocol overview description: 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. :::note[ggui vs guuey] **ggui** (this site) is the open protocol — published at [github.com/ggui-ai/ggui](https://github.com/ggui-ai/ggui); a hosted endpoint at `mcp.ggui.ai` is coming soon. **guuey** is a separate commercial agent-hosting platform at [guuey.com](https://guuey.com) that speaks the ggui protocol. Don't conflate them. ::: ## Three parties, three channels ``` ┌───────────────────────┐ │ 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. :::note[Channel names, not numbers] This page describes the conversational stack — the three transports between a user, a wrapped agent, and the ggui server: **chat / MCP / live**. The [Architecture overview](/architecture/overview/) describes the wire pipeline instead — **bootstrap / MCP / live**. The two views share MCP and the live channel; they differ only on the third: the protocol view names the chat surface the agent and user talk over, while the architecture view names the bootstrap fetch that delivers the compiled component to the renderer. Naming channels by their transport keeps the two views consistent. ::: 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 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 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 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 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 - **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 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 - [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.