llms.txt@public git:20261005.c0ee652A

Immutable. This exact content never changes and is served at /api/v1/blob/cab38b94992010cd.

# A2UI Catalog (the A2UI Atomic Catalog)

> Open-source, typed UI vocabulary (546 atoms) an AI agent uses to compose real interfaces — web, Google Meet stages, Apps Script web apps, Google Chat cards, MCP Apps and Android apps — from one JSON schema payload, instead of generating HTML.

## Start here

- [What is A2UI?](https://a2uicatalog.ai/what-is-a2ui/): Plain-English guide to the A2UI protocol: how agents send UI as JSON, how it travels over MCP, AG-UI and A2A, where it renders, and how it differs from generated HTML. Includes a 26-second explainer film.

## Integrate & Developer Resources

- [MCP server](https://a2uicatalog.ai/mcp): Live JSON-RPC endpoint, no auth/signup required. GET with `Accept: application/json` returns a machine-readable server descriptor listing every tool.
- [Documentation MCP server](https://a2uicatalog.ai/mcp-docs): A separate MCP identity (`a2uicatalog-docs`) for questions FROM this product's own docs — `search_docs(query)` and `list_docs()`. The product server above takes actions (compose/render/publish); this one only answers doc questions.
- [CLI / local MCP server (npm registry)](https://registry.npmjs.org/@a2uicatalog/mcp): `npx -p @a2uicatalog/mcp a2ui render page.json` renders a payload to HTML with no account and no MCP client. Also runs as a local MCP server (`a2uicatalog-mcp` bin) for Claude Desktop/Cursor, and deploys `training.md` to your own Google Apps Script web app via `build_app`. Source: `mcp/` in the [GitHub repository](https://github.com/a2uicatalog/a2ui). (npm's own package-page web UI 403s plain HTTP clients — the registry API link above is the one that resolves for a bot; `npm view @a2uicatalog/mcp` or a browser both work fine for a human.)
- [Agent Skills](https://a2uicatalog.ai/.well-known/agent-skills/index.json): three `SKILL.md` files (`a2ui-catalog`, `a2ui-compose`, `a2ui-mcp` — picking atoms, composing/rendering a payload, connecting a new agent over MCP) installable via `npx skills add a2uicatalog/a2ui`. Source: `skills/` in the GitHub repository.
- [Developer portal](https://a2uicatalog.ai/developers/): Human and agent developer portal, integration guide, REST surfaces, code samples, and self-hosting runbooks.
- [SDKs & client libraries](https://a2uicatalog.ai/sdks/): Official SDK documentation, npm CLI package, Agent Skills, and client code generators.
- [API docs](https://a2uicatalog.ai/docs/): API documentation for REST endpoints (/api/render, /api/compose, /ask), request/response schemas, and error shapes.
- [API reference](https://a2uicatalog.ai/api-docs/): Predictable entry point for developer resources, OpenAPI specs, and MCP endpoints.
- [OpenAPI spec](https://a2uicatalog.ai/openapi.json): Full OpenAPI 3.1 specification for all endpoints and schemas.
- [Auth docs](https://a2uicatalog.ai/auth/): Authentication documentation, enterprise OAuth discovery metadata, and public unauthenticated access policies.
- [Auth & rate limits](https://a2uicatalog.ai/.well-known/agent-auth.md): No API key or signup — the actual per-tool call limits.
- [Authentication guide](https://a2uicatalog.ai/auth.md): Why you almost certainly need no credential, plus the optional OAuth path for enterprise platforms that require one.
- [SDK guide](https://a2uicatalog.ai/sdk.md): SDK and client library documentation in Markdown format.
- [Webhooks & events](https://a2uicatalog.ai/webhooks/): Event delivery, Server-Sent Events (SSE) streaming, and chat webhook destinations.
- [Pricing & quotas](https://a2uicatalog.ai/pricing/): Free tier limits and self-hosting options.
- [Versioning & deprecation policy](https://a2uicatalog.ai/versioning/): What changes without notice, how breaking changes are announced (`Deprecation`/`Sunset` headers, 90-day minimum), and the CI parity gate that enforces it.
- [NLWeb search](https://a2uicatalog.ai/ask): Ask a plain-English question about the catalog (GET `?query=` or POST JSON) and get ranked, typed atom matches — no need to scrape HTML. `mode=summarize` adds a one-paragraph answer; `mode=generate` composes a real UI from the match. Supports SSE streaming (`Accept: text/event-stream`).
- [Machine-readable catalog](https://a2uicatalog.ai/spec.json): The full atom vocabulary as structured JSON — every field contract, generated from the schema.
- [Strict per-atom JSON Schema](https://a2uicatalog.ai/catalogue/atoms-json-schema.json): For constrained decoding, so a model cannot emit an invalid atom.
- [Agent discovery document](https://a2uicatalog.ai/.well-known/ard.json): Canonical ARD v0.91 resource discovery catalog (legacy alias at /.well-known/ai-catalog.json; also referenced from robots.txt's `Agentmap:` directive).
- [MCP Apps playground](https://a2uicatalog.ai/surfaces/mcp-apps): Renders atoms live inside MCP Apps-capable hosts (e.g. claude.ai); paste a payload or open a `#p=` link.
- [Claude Code surface](https://a2uicatalog.ai/surfaces/claude-code): The `a2ui-claude-code` plugin (a Claude Code mod, source `claude-code-surface/` in the GitHub repository) draws atoms natively in Claude Code panes: `/a2ui <payload.json>`, a2uicatalog MCP payloads, animated script progress bars and a long-job dashboard.
- [Android surface](https://a2uicatalog.ai/surfaces/android/): Atoms on Android through Google's `androidx.a2ui` Jetpack Compose renderer. The `atomic-catalog` library (`ai.a2uicatalog:atomic-catalog`, source `android/` in the GitHub repository) registers every atom: Basic Catalog components draw natively in Compose, the rest through the catalog's own renderer in a WebView. Agents that read the app's `a2uiClientCapabilities` send a Basic-Catalog-only version to apps without the library, so a stock app never receives a type it can't draw.
- [Self-host the renderer](https://a2uicatalog.ai/renderer): Deploy your own Apps Script renderer in 4 commands — own the URL, no shared-demo rate limit.

## When to use this

Use the A2UI catalog when you need to SHOW something to a user rather than describe it — a chart, a status board, a step-by-step procedure, a comparison table, a dashboard. Call `list_catalogs` then `get_catalog` to read real field contracts before composing; never guess a field name. Use `render_surface` on MCP Apps-capable hosts to render inline, or `preview_url` elsewhere to get a shareable link.

Do not use it for plain prose answers, for data retrieval (it renders data, it does not fetch it beyond declared sources), or where the host cannot display HTML.

## Writing

Build logs and architecture write-ups from operating this catalog in production — real incidents, real fixes, dated and attributed. Full list below; [sitemap](https://a2uicatalog.ai/blog/sitemap.xml) is the machine-readable version.

- [Building in the Age of Frontier Models: Why Frugality is My Go-To Architecture](https://a2uicatalog.ai/blog/001-frugality-architecture/): Artifact distillation — spend the model once, keep the output forever. Five problems nobody asked me to solve.
- [Rich UI in Gemini Enterprise: A Field Report on A2A Agents and A2UI Primitives](https://a2uicatalog.ai/blog/002-gemini-enterprise-field-report-a2a-a2ui-part1/): Every component in the A2UI v0.8 Basic Catalog tested against a real Gemini Enterprise agent, plus two working demo agents built entirely from them.
- [Rich UI in Gemini Enterprise, Part 2 — The Print-Rendering Workaround for Custom Catalogs](https://a2uicatalog.ai/blog/003-gemini-enterprise-field-report-a2a-a2ui-part2/): Gemini Enterprise only renders 18 standard-catalog primitives; the fix renders custom charts/gauges server-side to an image through the one primitive that always works.
- [The A2UI Catalog Now Renders Inside Claude.ai](https://a2uicatalog.ai/blog/004-mcp-apps-inside-claude-ai/): One connector URL, 474 typed atoms rendering inline in the conversation — no HTML written.
- [Rich UI in Google Chat: a real, self-hostable bot built on the print-channel trick](https://a2uicatalog.ai/blog/005-google-chat-print-channel-bundle/): The self-hostable Cloud Run bundle, a wire-level trace of one request, and the Chat-setup gotchas Google's docs don't lead with.
- [The A2UI Catalog Now Renders Inside ChatGPT](https://a2uicatalog.ai/blog/006-mcp-apps-inside-chatgpt/): Same connector URL, same payloads, a second host — and three latent defects that existing connections had been quietly hiding.
- [MCP Apps Isn't A2UI's Competitor — It's How It Travels](https://a2uicatalog.ai/blog/007-mcp-apps-portability/): Where transport, envelope and document model actually sit — how the same payload reaches Claude, ChatGPT and this site without three separate builds.
- [MCP, A2UI, and a Durable Object per Human](https://a2uicatalog.ai/blog/008-mcp-durable-state/): Where per-user UI state actually lives across MCP, A2UI and A2A — covers Cloudflare's Project Think, Durable Objects per reader, and six real defects found wiring it up.

## Source

- [GitHub repository](https://github.com/a2uicatalog/a2ui): Source, license, and the full atom schema.
- [Claude quickstart](https://raw.githubusercontent.com/a2uicatalog/a2ui/main/docs/quickstart-claude.md): Connect the MCP server, render a first atom, deploy your own renderer.
- [Gemini Enterprise quickstart](https://raw.githubusercontent.com/a2uicatalog/a2ui/main/docs/quickstart-gemini-enterprise.md): BYO-MCP setup for Gemini Enterprise agents.