MCP Integration Overview
A2UI and the Model Context Protocol (MCP) integrate in four ways depending on whether your application or an external MCP client owns the outer host, and whether the MCP server returns structured JSON data, reusable A2UI layout templates, or sandboxed HTML apps.
Choose an MCP integration pattern
Use the table below to pick the guide that matches your host environment and MCP server output:
| Your goal | Outer host | MCP server output | Guide |
|---|---|---|---|
| Invoke headless MCP tools from A2UI inputs and buttons | Your A2UI web app | JSON or plain-text tool results | Call MCP Tools from A2UI |
| Return reusable A2UI layouts and per-call data from tools | Your A2UI web app | a2ui:// templates (application/a2ui+json) | Serve A2UI Layouts from an MCP Server |
| Embed third-party interactive HTML widgets on an A2UI surface | Your A2UI web app | ui:// HTML apps (text/html;profile=mcp-app) | Embed MCP Apps in A2UI Surfaces |
| Display A2UI surfaces inside Claude Desktop, Cursor, or VS Code | External MCP Apps host | ui:// HTML bundle containing an A2UI renderer | Render A2UI Inside an MCP App |
How the patterns fit together
- When you own the web application,
@a2ui/catalog-mcpconnects your Lit, React, or Angular renderer directly to MCPClientsessions. Surfaces can call tools withcallMcpTooland write returned JSON into the surface Data Model (Call MCP Tools from A2UI), or mount third-partyui://HTML widgets inside a double-iframe sandbox withMcpApp(Embed MCP Apps in A2UI Surfaces). - When an MCP server emits A2UI messages (
application/a2ui+json), it can publish declarative component layouts asa2ui://resources and return compactupdateDataModelupdates fromtools/call(Serve A2UI Layouts from an MCP Server). If the outer client supports MCP Apps (ui://HTML iframes) rather than A2UI natively, your server can package an A2UI web renderer inside theui://HTML bundle itself (Render A2UI Inside an MCP App).