OSS Quick Start

read as .md

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.

agent ── MCP ──→ ggui serve ──→ MCP-Apps resource ui://ggui/render/<id>

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

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 for the template list.

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):

ANTHROPIC_API_KEY=sk-ant-...

pnpm dev

pnpm dev boots the whole project together — the ggui MCP server (ggui serve from @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

Add this entry to the scaffold’s existing .mcp.json (it already contains a ggui-dev helper server):

{
  "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 section has working recipes per framework.

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/<id>) 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

Not a hosted service. No ggui cloud account, no billing, no managed dashboards. For those, see the Hosted Quick Start (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

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.

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 against a ggui.json directly (the same ggui serve the scaffold’s servers/ggui runs):

# = 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:

pnpm --filter @ggui-ai/cli build
node packages/ggui-cli/dist/cli.js serve --mcp-only

What’s next

MCP Protocol Reference — wire format and tool catalogue (same on OSS and hosted).
WebSocket Protocol — live-channel envelopes (ActionEnvelope, StreamEnvelope).
Examples — MCP-config-only integrations with system-prompt recipes (Claude, OpenAI, Gemini, OpenClaw, generic MCP).
Hosted Quick Start — managed generation and dashboards on ggui cloud (coming soon).
GitHub repo — source, issue tracker, full monorepo walkthrough.