Protocol overview

read as .md

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). Everything below is implementable from the spec — the open-source ggui 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

                 ┌───────────────────────┐
                 │      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://<your-server>/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 StreamEnvelopes), 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 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	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	Live	Subscribe / `ActionEnvelope` / ack / render / `StreamEnvelope`; replay; reconnection
MCP Apps support	MCP + Live	Resource shape (`{contents:[{uri,mimeType,text}]}`); host-side iframe-runtime boot
OAuth (`ggui serve --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:

packages/mcp-server — the MCP + live-channel server.
packages/ggui-react — the host-side SDK.
packages/ggui-cli — ships ggui 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 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.

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 — 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 for the full semver mapping, deprecation timeline, and version support matrix.