ggui

ggui is the universal MCP-UI protocol — a runtime-negotiated data contract between AI agents and human users.

Docs · OSS Quickstart

Agents describe what they need in natural language; ggui generates ephemeral, interactive interfaces over MCP. No frontend code, no React templates, no custom components — agents talk, users see UI.

This repo is the open protocol + reference runtime. Self-host with ggui serve; pair against any MCP-aware agent runtime (Claude Desktop, Claude Code, Cursor, ChatGPT desktop, Goose, your own). Zero Guuey account required, zero managed infrastructure required, zero cloud dependency.

Quickstart

# Scaffold a minimal OSS server + agent entry
npm create ggui-server@latest my-app
cd my-app
npm install

# Boot the MCP server
npx ggui serve     # binds 127.0.0.1:6781 by default

ggui serve stands up @ggui-ai/mcp-server with the first-run bundle: MCP at /mcp, the same-origin session viewer at /s/<shortCode>, pairing endpoints, and a channel-3 WebSocket. Open http://127.0.0.1:6781/ to land on the operator console.

Point any MCP-compatible agent runtime at http://127.0.0.1:6781/mcp with Authorization: Bearer dev. The OSS Quickstart walks through the full self-hosted path including pairing.

Honest scope today

• ✅ Local server, viewer, cookie-authenticated WebSocket subscribe → ack all work end-to-end.
• ✅ ggui_push mints shortCodes and lands on the same-origin viewer.
• ⏳ Component-code generation is not yet wired on the OSS path. ggui_push returns codeReady: false; the viewer shows the live session shell with an empty state until a stack item arrives. The OSS generator seam is tracked in issues.
• 🔒 Default auth is dev-mode (any non-empty bearer → builder). Swap in a real AuthAdapter via createGguiServer({ auth }) before exposing beyond 127.0.0.1.

How it works

┌─────────┐     MCP Tools      ┌──────────┐     WebSocket     ┌──────────┐
│  Your   │ ────────────────→  │  ggui    │ ────────────────→ │  User's  │
│  Agent  │   ggui_push        │  server  │   real-time UI    │  browser │
│         │   ggui_update      │          │   updates         │          │
│         │ ←────────────────  │          │ ←──────────────── │          │
│         │   user events      │          │   clicks, forms   │          │
└─────────┘                    └──────────┘                   └──────────┘

Your agent uses MCP tools to push UIs and receive user events. The protocol is defined by @ggui-ai/protocol; the reference server lives in @ggui-ai/mcp-server; embedding primitives ship in @ggui-ai/react.

MCP tools (primary surface)

Plus a blueprint family (ggui_search_blueprints, ggui_render_blueprint, ggui_validate_blueprint, …) for catalogue lookups. Full reference: MCP Protocol Reference.

Zero agent code (MCP config only)

If your agent runtime supports MCP natively, skip the SDK entirely. Add ggui serve as an MCP server:

{
  "mcpServers": {
    "ggui": {
      "url": "http://127.0.0.1:6781/mcp",
      "headers": { "Authorization": "Bearer dev" }
    }
  }
}

The runtime's native tool-calling loop discovers ggui_push, ggui_update, and the blueprint catalogue tools directly. Working examples per framework: Claude, OpenAI, Gemini, generic MCP.

Embedding UIs

<McpAppIframe> is the canonical consumer primitive. It takes an MCP Apps resource and mounts the ggui session inside a same-origin iframe. The iframe owns the WebSocket lifecycle, renderer bundle, and stack rendering — host code does not touch StackItem / WebSocket / renderer internals.

import { McpAppIframe, type ProtocolError } from "@ggui-ai/react";
import { useEffect, useState } from "react";

function App({ sessionId }: { sessionId: string }) {
  const [resource, setResource] = useState<{ uri: string; mimeType: string; text: string } | null>(
    null
  );

  useEffect(() => {
    // Fetch the session-resource envelope from your MCP host —
    // OSS path: GET http://127.0.0.1:6781/s/<shortCode>/resource
    fetchSessionResource(sessionId).then((r) => setResource(r.contents[0]));
  }, [sessionId]);

  if (!resource) return <p>Loading…</p>;

  return <McpAppIframe resource={resource} onError={(err: ProtocolError) => console.error(err)} />;
}

Implementer references for the full protocol: Architecture overview, MCP Apps support, WebSocket protocol.

For non-React frameworks, embed the viewer directly:

<iframe src="http://127.0.0.1:6781/s/{shortCode}" width="100%" height="600"></iframe>

Packages

Consumer-facing surface — what you npm install:

Package	Purpose	npm
@ggui-ai/cli	The ggui binary — ggui serve, ggui dev, ggui pair
@ggui-ai/mcp-server	Reference OSS server (programmatic embedding)
@ggui-ai/server	Agent server — receives events, dispatches MCP
@ggui-ai/mcp-client	Agent SDK — call ggui tools from your agent runtime
@ggui-ai/react	React embedding — <McpAppIframe> + shells
@ggui-ai/protocol	Wire types (events, sessions, WebSocket, MCP envelopes)
create-ggui-server	Scaffold — npm create ggui-server@latest

Plus 11 supporting packages (@ggui-ai/wire, @ggui-ai/shared, @ggui-ai/agent-runtime, @ggui-ai/dev-stack, @ggui-ai/devtool, @ggui-ai/design, @ggui-ai/preview-a2ui, @ggui-ai/mcp-server-core, @ggui-ai/mcp-server-handlers, @ggui-ai/project-config, @ggui-ai/ui-registry) — see each subdirectory for details.

Hosted providers

Self-hosting is the primary path. If you'd prefer managed infrastructure (no server to run, no LLM key to wire, hosted dashboards), Guuey is the first-party hosted provider built on this protocol. The OSS protocol is identical on both paths — you can move between self-hosted and hosted without rewriting anything against this SDK.

Contributing

See CONTRIBUTING.md. Issues + PRs welcome.

License

MIT — see LICENSE.