How do agents use ggui?

An agent uses ggui through its MCP config alone. Start the self-hosted server with npx -y @ggui-ai/cli serve, add one HTTP MCP entry pointing at it, and the agent can call ggui’s tools to put a UI in front of the user for anything it can do — no SDK imports, no event handlers, no frontend code.

Yes. ggui is Apache 2.0-licensed and developed in the open at github.com/ggui-ai/ggui. The protocol spec and reference implementations are open, and the @ggui-ai/cli, @ggui-ai/react, and @ggui-ai/react-native packages ship on npm.

How does ggui relate to MCP?

ggui is built on the Model Context Protocol. It registers as a standard MCP server, so any MCP-speaking agent or runtime can call it with a single HTTP entry in its MCP config — there is no proprietary integration surface to adopt. UI requests and the interaction events that flow back both ride ordinary MCP messages, which is what keeps ggui LLM-agnostic and framework-agnostic.

Which agent frameworks work with ggui?

Claude Agent SDK, OpenAI Agents, Google ADK are tested and ship first-party samples in the repo. LangGraph and Mastra — like any other MCP-speaking runtime — work through the same single HTTP MCP entry, with no first-party sample required.

open protocol · generative graphical user interface

The interface layer for agents.

The runtime between an agent’s decision and a user’s screen. Open protocol, MCP-native, LLM-agnostic. Self-hosted, open source.

Start in one command

npx -y @ggui-ai/cli serve

Runs the self-hosted ggui MCP server. Point any MCP-speaking agent at it — first-party Claude, OpenAI, and Google ADK samples ship in the repo — and it renders generative UI for every tool call.

Get started ↗Read the docs ↗v0.5.0-rc.2 · early alpha ↗

What is ggui?

ggui is an open-source interface layer that lets AI agents show real user interfaces instead of plain text. It runs as an MCP server: the agent describes what it needs to show, and ggui matches a cached blueprint or generates a UI against the agent’s declared data contract, then renders it on the user’s screen — web or mobile. Interaction events flow back to the agent over the same contract, and the developer writes no frontend code.

MCP-native
Register as an MCP server. Any MCP-speaking agent can call it.
LLM-agnostic
Claude, OpenAI, Gemini — bring your own key.
Framework-agnostic
Tested on Claude Agent SDK, OpenAI Agents, Google ADK — plus any MCP-speaking runtime (LangGraph, Mastra, raw MCP). Chat-additive, not chat-replacement.
Open protocol
Apache 2.0. Spec, reference implementations, public benchmarks.
React + React Native
Web and mobile renderers, both shipped on npm.
Benchmarked
Runs, latencies, and costs measured — methodology open.
Dashboard ↗

01 / Premise

Why ggui.

Most MCP tools don't ship with a UI.

Agents can call them. Users see text. The interface has to come from somewhere.

One UI per tool doesn't compose.

A calendar UI doesn’t help when the agent also needs weather and email on the same surface. UI built per-tool doesn’t survive contact with multi-tool workflows.

The agent picks the right UI. The protocol renders it.

ggui works with blueprints — UI layouts bound to declared data shapes. Developers pre-author them for the moments they want to control. Agents generate new ones in real time when nothing fits, and ggui caches each one so the same request reuses the same proven screen next time. All of them share the same data contract the agent is already working with. One tool, many composed, a full generative app experience — the protocol renders all three the same way.

02 / How it works

Four things happen between “agent wants to show” and “user sees a UI.”

The agent calls ggui over MCP.

Your agent doesn’t need to know about UI. It calls a tool. ggui is that tool, exposed as an MCP server — any agent that speaks MCP can call it.

The user sees something right away.

Before ggui has decided what to render, a preview skeleton streams onto the user’s surface — a small subset of primitives designed for fast, partial-render feedback. No spinner, no blank state. The wait becomes assembly.

ggui picks or generates a blueprint.

Meanwhile, ggui checks the registry — blueprints the developer wrote, and blueprints the agent generated on earlier requests. If one fits the data the agent is passing, it’s reused directly — no fresh generation, the same proven screen every time. If none fit, ggui generates a new one against the same data contract, and keeps it for next time.

The final UI replaces the skeleton. Events flow back.

When the blueprint is ready, it takes over the user’s surface — web, mobile, or spatial. When the user interacts, events return to the agent along the same data contract that drew the UI. No glue code in between.

The full spec — wire protocol, blueprint schema, data contract rules — lives in the docs.

Read the spec ↗Star on GitHub ↗

Apache 2.0 · Contributions welcome via github.com/ggui-ai/ggui.

03 / The gap

Generative UI alone isn’t enough. MCP Apps alone isn’t either.

Each half solves some of the problem. Neither alone makes agent-rendered interfaces production-grade. ggui closes the gap with a typed data contract — and takes the union of wins on every axis.

Generative UI alone

MCP Apps alone

ggui

Speed

LLM call per render — seconds.

Pre-shipped HTML — instant.

Reuses proven screens — zero regeneration; renders in seconds.

Truth

Buttons can do anything.

Hand-validated by the host.

Contract validated both ways.

Coverage

Any MCP — but unreliably.

Only servers that shipped an App.

Any MCP, reliably.

Composition

Per-tool, no sharing.

Sandboxed, no cross-server.

Cross-MCP in one session.

04 / Why ggui

What this gives you that a UI kit can’t.

Generated UI, bounded by a contract.

Every surface the agent renders is validated against a declared data contract — both ways. Outbound emissions are schema-checked before fan-out; inbound user actions are allowlisted on ingress. The harness can invent anything, but the contract layer keeps it inside spec.

The server owns the session, not the client.

A neutral session authority — not the agent, not the browser — holds the running contract. Sessions survive reconnects via ring-buffer replay. Multiple subscribers can watch one session at once: two users, or a user plus a dashboard, or a mobile client plus a desktop one.

The UI layer doesn't care which framework you run.

Add ggui to an existing Claude, OpenAI, or Google agent — or any MCP-speaking runtime like LangGraph — with one HTTP entry in your MCP config. Keep your chat runtime. The ggui layer is additive — it ships the interface, nothing else.

05 / Origins

Where this comes from.

“I spent years at the Ethereum Foundation as a cypherpunk, building trustless protocols with cryptography. Working with AI agents, I kept seeing the same missing piece: a data contract between the agent and the person it serves. ggui is that contract.”

— Wanseob Lim, Author of the ggui protocol

@wanseob ↗

Backed by Hashed Vibe Labs

06 / Two ways to run it

Two ways to run it. Pick one.

ggui is MCP-native. Bolt it onto an existing agent, or start a new one from a first-party sample — either way, ggui is wired in from the first run.

Existing agent

Point an existing agent at ggui.

Two steps: run a ggui server, then point your agent’s MCP config at it over HTTP. Your agent starts rendering generative UIs for every tool it can call — no frontend code, no framework lock-in.

# 1 · start a ggui server (local dev — skips pairing)
npx -y @ggui-ai/cli serve --dev-allow-all

# 2 · point your agent's MCP config at it
{
  "mcpServers": {
    "ggui": { "type": "http", "url": "http://127.0.0.1:6781/mcp" }
  }
}

See MCP setup ↗

New agent

Start from a first-party sample.

Clone the repo and build on the samples — agent backend, ggui MCP server, and web client, wired together. Pick your framework: Claude, OpenAI, or Google ADK.

$ git clone https://github.com/ggui-ai/ggui
# agent samples — samples/agents/
#   claude-agent-sdk · openai-agents-sdk · google-adk
# web client — samples/apps/ggui-basic-web
#   (Vite + React + @ggui-ai/react)

→ follow the samples quickstart in the README
  pnpm dev   # everything → http://localhost:6890

Claude

OpenAI

Gemini

LangGraph

Mastra

and more

Browse the samples ↗

One open protocol. Any MCP. Any agent. Any model.

07 / FAQ

Common questions. Direct answers.

What is ggui?: ggui is an open-source interface layer that lets AI agents show real user interfaces instead of plain text. It runs as an MCP server: the agent describes what it needs to show, and ggui matches a cached blueprint or generates a UI against the agent’s declared data contract, then renders it on the user’s screen — web or mobile. Interaction events flow back to the agent over the same contract, and the developer writes no frontend code.
How do agents use ggui?: An agent uses ggui through its MCP config alone. Start the self-hosted server with npx -y @ggui-ai/cli serve, add one HTTP MCP entry pointing at it, and the agent can call ggui’s tools to put a UI in front of the user for anything it can do — no SDK imports, no event handlers, no frontend code.
Is ggui open source?: Yes. ggui is Apache 2.0-licensed and developed in the open at github.com/ggui-ai/ggui. The protocol spec and reference implementations are open, and the @ggui-ai/cli, @ggui-ai/react, and @ggui-ai/react-native packages ship on npm.
How does ggui relate to MCP?: ggui is built on the Model Context Protocol. It registers as a standard MCP server, so any MCP-speaking agent or runtime can call it with a single HTTP entry in its MCP config — there is no proprietary integration surface to adopt. UI requests and the interaction events that flow back both ride ordinary MCP messages, which is what keeps ggui LLM-agnostic and framework-agnostic.
Which agent frameworks work with ggui?: Claude Agent SDK, OpenAI Agents, Google ADK are tested and ship first-party samples in the repo. LangGraph and Mastra — like any other MCP-speaking runtime — work through the same single HTTP MCP entry, with no first-party sample required.

More in the repo ↗ and discussions ↗.