MCP Protocol

The ggui API uses the Model Context Protocol (MCP) over HTTP with JSON-RPC 2.0.

Same protocol on hosted and OSS

The wire format documented here is identical whether you’re calling hosted Guuey or your own OSS ggui serve instance. The endpoint URL and authentication differ — this page shows the hosted defaults.

Endpoint

🟣 Hosted Guuey:

POST https://api.guuey.com/mcp

🟢 OSS / self-hosted (ggui serve):

POST http://127.0.0.1:6781/mcp

Authentication

🟣 Hosted Guuey — include your API key and app ID in every request:

Authorization: Bearer ggui_sk_...
X-Ggui-App-Id: app_...
Content-Type: application/json

🟢 OSS / self-hosted — dev mode accepts any non-empty bearer token as the builder identity. Swap in a real AuthAdapter via createGguiServer({ auth }) before exposing beyond 127.0.0.1:

Authorization: Bearer dev
Content-Type: application/json

Session Lifecycle

1. initialize       → Handshake (automatic, done once per connection)
2. ggui_push        → Create session + resolve rendering
3. ggui_commit      → Accept the decision and provide props
4. ggui_consume     → Poll for user events (repeat as needed)
5. ggui_push/pop    → Navigate the UI stack
6. ggui_close       → Clean up when done

Rendering Pipeline

ggui_push resolves the best rendering path in this order:

1. Blueprint match — curated/heuristic/llm-authored screens indexed by sourceTools. Instant, deterministic, zero-LLM.
2. Deterministic derivation — single-tool outputSchema → contract → pool.
3. Intent fast-path — prior contract-hash lookup.
4. Full negotiation — RAG + LLM (fallback).

Pass sourceTools (which tools produced the data) and wiredTools (which tools are available for actions). The handler picks the best path and returns a decision. ggui_commit accepts and sends props.

---

Tools

ggui_push

Create a new UI or push a card onto an existing session’s stack. V4 uses nested input groups.

Input: { story, session?, rendering?, infra?, shortcuts? }

story (required):

Field	Type	Required	Description
intent	string	Yes	Concise purpose — same intent = cached component reused.
data	object	No	Structured data to display.
sourceTools	string[]	No	MCP tools that produced this data. Primary key for blueprint matching.
wiredTools	string[]	No	MCP tools available as user actions.
prompt	string	No	Additional instructions beyond the intent.
context	string | object	No	Agent reasoning, user situation.

Other groups: session.{id, message}, rendering.{shellType, interfaceContext}, infra.{ttl, model}, shortcuts.{templateId, props, autoCommit}.

Returns a decision: { sessionId, pageId, decision, renderUrl, shortCode }. Call ggui_commit with props to accept (or override to request something different).

ggui_commit

Accept or override the decision returned by ggui_push. Required to complete rendering (unless shortcuts.autoCommit was set on push).

Field	Type	Required	Description
sessionId	string	Yes	Session ID from the push response.
pageId	string	Yes	Page ID from the push response.
accept	boolean	No	Accept the decision.
props	object	No	Data matching the decision’s contract.
alternativeId	string	No	Pick a different alternative (suggestive modes).
override	object	No	{ action, contract, instructions, prompt } override.

ggui_pop

Remove the top UI card from the session stack.

Field	Type	Required	Description
sessionId	string	Yes	Session to pop from

Returns: { poppedId, stackSize }

ggui_consume

Poll for buffered user events. Events are cleared after being returned (consume-once semantics).

Field	Type	Required	Description
sessionId	string	Yes	Session to consume from

Returns: { events: ActionEnvelope[], status: "active" | "completed" }

ggui_get_session

Get the full state of a session, including the UI stack and event sequence.

Field	Type	Required	Description
sessionId	string	Yes	Session to inspect

Returns: { sessionId, appId, stack, currentStackIndex, adapterPermissions, eventSequence, status }

ggui_get_stack

Get the current UI stack: what pages are displayed, their prompts, and their contracts (stream spec for ggui_stream, actions for ggui_consume).

Field	Type	Required	Description
sessionId	string	Yes	Session to inspect

Returns: { stack: StackItem[], currentStackIndex, contracts }

ggui_close

Close and delete a session.

Field	Type	Required	Description
sessionId	string	Yes	Session to close

Returns: { success: boolean }

---

Events

User actions flow from browser to agent as canonical flat ActionEnvelope records. Each envelope has this structure:

interface ActionEnvelope<TPayload = JsonValue> {
  sessionId: string;
  type: EventType;
  payload?: TPayload; // For `data:submit`: { action, data?, tool? }
  stackIndex?: number;
  pageId?: string;
  clientSeq?: number; // client-monotonic, for at-least-once dedup
}

The envelope is flat — no nested event / context / meta blocks. Diagnostic session metadata (device info, interface context) lives on the session at subscribe time, not per-delivery.

Event Types

Type	Category	Description
data:submit	Data	User submitted a form
data:change	Data	A field value changed
lifecycle:session_start	Lifecycle	Session created
lifecycle:session_end	Lifecycle	Session ended
lifecycle:stack_push	Lifecycle	Card pushed to stack
lifecycle:stack_pop	Lifecycle	Card popped from stack
interaction:click	Interaction	User clicked a component
interaction:hover	Interaction	User hovered
interaction:scroll	Interaction	User scrolled
error:validation	Error	Form validation failed
error:connection	Error	WebSocket connection issue

Default subscription (when omitted): ["data:submit", "lifecycle:session_end"]

---

Error Codes

Code	Name	Description
-32700	Parse Error	Invalid JSON in request
-32600	Invalid Request	Not a valid JSON-RPC object
-32601	Method Not Found	Unknown method name
-32602	Invalid Params	Missing or invalid tool arguments
-32603	Internal Error	Server-side failure
-32001	Unauthorized	Invalid API key or app ID
-32002	Session Not Found	Session expired or deleted
-32003	App Not Found	App ID does not exist
-32004	Generation Failed	UI generation failed

---

Supported Models

Model ID	Provider	Tier	Description
anthropic/claude-haiku-4-5	Anthropic	Fast	Default model. Fast, cost-effective
anthropic/claude-sonnet-4-5	Anthropic	Balanced	Higher quality output
anthropic/claude-opus-4-5	Anthropic	Premium	Highest quality
gemini/gemini-3-flash	Google	Fast	Very fast, large context
openai/gpt-5.2	OpenAI	Premium	High quality
openai/gpt-5.1-codex-mini	OpenAI	Fast	Fast code generation

---

Example: Full Session (curl)

# 1. Initialize
curl -X POST https://api.guuey.com/mcp \
  -H "Authorization: Bearer ggui_sk_..." \
  -H "X-Ggui-App-Id: app_..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","clientInfo":{"name":"curl","version":"1.0"},"capabilities":{}}}'

# 2. Push a UI
curl -X POST https://api.guuey.com/mcp \
  -H "Authorization: Bearer ggui_sk_..." \
  -H "X-Ggui-App-Id: app_..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"ggui_push","arguments":{"story":{"intent":"Contact form"}}}}'

# 3. Poll for events
curl -X POST https://api.guuey.com/mcp \
  -H "Authorization: Bearer ggui_sk_..." \
  -H "X-Ggui-App-Id: app_..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"ggui_consume","arguments":{"sessionId":"ses_..."}}}'

# 4. Close session
curl -X POST https://api.guuey.com/mcp \
  -H "Authorization: Bearer ggui_sk_..." \
  -H "X-Ggui-App-Id: app_..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"ggui_close","arguments":{"sessionId":"ses_..."}}}'