Owns the product
Question and answer contract, API client, status wording, fonts, branding, attribution treatment, HTTP configuration and platform entry points.
One question, end to end
The answer service owns the answer. Ansari owns the application. The SAGA stack connects that meaning to an MCP card.
HostAnsari appSAGA stackAnsari API
HostConversationDiscovers, invokes and displays
→
Ansari appHono + MCP operationDeclares the input, answer envelope and view
↔
Ansari APIComplete answerReturns text and attribution unchanged
→
SAGA stackFaithfulCardRenders inside the host’s card surface
The answer, and every way it can arrive
The application supplies the presentation and every user-facing status sentence. The stack supplies the shared rendering and interaction mechanics.
Illustrative UI only. This is an explanation, not the running SDK card or a live Ansari answer.
What the code does
Image permission and external-link confirmation are different controls. The stack manages content policy and answer-scoped outcomes; the host decides how an allowed external navigation is confirmed.
Fonts before answers
Kitab Regular and Bold are embedded as bytes and loaded through FontFace. Font readiness has its own failure sentence; no device font is silently substituted for an answer.
Reading follows context
readingProfile comes from the stack. Ansari maps host colors, reading tokens and direction without changing answer data or applying a second root scale.
Attribution stays in the answer
The card renders the full answer once. Ansari watches the rendered closing block to style the attribution; the optional framework credit is separate.
Application meaning, shared mechanics
The browser imports one SAGA stack. Hosting adapters inject their platform-specific inputs into one fetch application. Explore a module to see its real source and its boundary.
Owns the card connection
Host bridge, held/latest results, Markdown content, document policy, image consent, host links, own sizing and teardown. Server exports own view linkage; its fetch app owns /mcp admission, request budgets and lifetimes.
Owns the conversation
Tool selection, permissions, discovery/cache behavior, card sandbox and external-navigation experience. The app does not dictate host refresh timing.
Prepare once. Give each request its own lifetime.
The reusable object is the immutable card document. Each MCP request gets a fresh server and budget. Platform shutdown and iframe teardown are separate lifecycles.
One preparation
Independent requests
Try the lifetime model
This small model illustrates ownership; it does not send MCP traffic.
1prepared views
0active calls
0retired calls
Ready. No active request.
60-second application bound
The declared tool bound and each request budget agree. Closing its server releases the lifetime even if no transport was connected. The same lifetime signal aborts the upstream fetch and response-body read; remote backend processing may still continue.
Progress is not answer streaming
SSE can carry client-requested progress. The operation still returns one complete answer. JSON response mode sends the final result; older-host compatibility can use SSE.
· ·
One card. Two hosting artifacts.
The card and server are built together. Node supplies a listener and filesystem access at startup; Workers supplies a fetch entry and bindings. Neither changes the answer contract.
Source + dependencies
Install the public stack
@saga-a2ui/react-mcp-stack 1.0.0-rc.1 +- One card. Two hosting artifacts.
The card and server are built together. Node supplies a listener and filesystem access at startup; Workers supplies a fetch entry and bindings. Neither changes the answer contract.
Source + dependenciesInstall the public stack
@saga-a2ui/react-mcp-stack 1.0.1 react 19.3.1 react-dom 19.3.1 -All five SDK siblings: 1.0.0-rc.1 +Siblings pinned by the stack: + core 1.0.0 · components 1.0.0 + mcp 1.0.2 · react 1.0.0 SDK overrides: dompurify 3.4.17 @hono/node-server 2.1.5 -@a2ui/markdown-it override: 0.2.1The app imports only stack subpaths. SAGA is installed from the public npm registry at one exact release,
1.0.0-rc.1(thenexttag), and the repository root’s one committed lockfile records its registry integrity. No private registry, credential, SDK tarball, SDK workspace link or SDK-package override is involved. The rootpnpm-workspace.yamlkeeps the SDK’s documenteddompurifyand@hono/node-serveroverrides.→Build-time content policyProduce self-contained HTML
Vite + single-file plugin +@a2ui/markdown-it override: 0.2.1The app imports only stack subpaths. SAGA is installed from the public npm registry: the stack
@saga-a2ui/react-mcp-stack@1.0.1plus the siblings it pins exactly. SAGA versions its packages independently, so the siblings need not share the stack’s version; each resolves to exactly the version the stack pins, and the repository root’s one committed lockfile records their registry integrity. No private registry, credential, SDK tarball, SDK workspace link or SDK-package override is involved. The rootpnpm-workspace.yamlkeeps the SDK’s documenteddompurifyand@hono/node-serveroverrides.→Build-time content policyProduce self-contained HTML
Vite + single-file plugin React + card code + CSS embedded Kitab + floral assets application + SDK identity @@ -81,10 +83,10 @@ pnpm --filter ansari-mcp verify # Uncached root-context container qualification -bash apps/mcp/scripts/verify-container.shThe root lockfile is authoritative. Frozen workspace installation and a root-context Docker smoke check protect packaging; they do not establish an actual host connection.
Setting Where it belongs Why it matters Upstream URL, client label, optional auth Node environment / Worker bindings Same client contract; secrets stay out of source. Allowed Host and Origin Named deployment environment Validation matches the selected public endpoint. Dev / Beta / Production Distinct native Wrangler environment configuration Select an explicit target and keep release/rollback decisions separate. Application, SDK and resource identity Built and served card metadata: data-sdk-kind="registry"and the SDK version1.0.0-rc.1Inspect the card actually loaded by the host, rather than assuming its cache is current. +bash apps/mcp/scripts/verify-container.sh Four lifecycles meet at one card
A server release, a host catalog, a request and an embedded view each have a different owner and lifetime. Keeping them distinct explains refreshes, retries and teardown.
01 · Release Build & serve
Install exact packages, build artifacts, configure a named target, start the application and prepare immutable view bytes.
02 · Host catalog Discover & refresh
Register an MCP endpoint and discover its tool and UI association. After a release, verify the card the host loaded carries the current release.
03 · Request Invoke & finish
Send a question, call the API, return one full result and release the per-request server lifetime. Calls remain independent.
04 · View Mount & retire
Connect the bridge, wait for fonts, present the latest result and apply host context. Teardown releases owned browser resources.
What this walkthrough establishes
It explains checked application source, using real names and exact excerpts. The interactive diagrams and card examples are synthetic and make no network requests.
- Runtime and view composition are grounded in the complete application source of app
0.17.1as it is committed in this folder.- SAGA
1.0.0-rc.1is installed from the public npm registry as one exact release; the root lockfile records its registry integrity.- This document is a fresh explanation of the full architecture, not a summary of changes from an earlier version.
What must be verified in a host
- A real tool invocation and an actual embedded answer card.
- Matching application revision, SDK identity and served resource bytes.
- Fonts, language direction, attribution, sizing and the relevant consent interactions.
- First-load success distinguished from recovery after Retry.
Rendering inside ChatGPT, Claude and Alexa+ is a separate host acceptance. Neither this document nor this repository’s automated checks establish it.
Read the source offline
Each path links to its exact source commit on GitHub. The embedded source remains available offline through “Read embedded source”.
The root lockfile is authoritative. Frozen workspace installation and a root-context Docker smoke check protect packaging; they do not establish an actual host connection.
| Setting | Where it belongs | Why it matters |
|---|---|---|
| Upstream URL, client label, optional auth | Node environment / Worker bindings | Same client contract; secrets stay out of source. |
| Allowed Host and Origin | Named deployment environment | Validation matches the selected public endpoint. |
| Dev / Beta / Production | Distinct native Wrangler environment configuration | Select an explicit target and keep release/rollback decisions separate. |
| Application, SDK and resource identity | Built and served card metadata: data-sdk-kind="registry" and the SDK version 1.0.1 | Inspect the card actually loaded by the host, rather than assuming its cache is current. |
Four lifecycles meet at one card
A server release, a host catalog, a request and an embedded view each have a different owner and lifetime. Keeping them distinct explains refreshes, retries and teardown.
Build & serve
Install exact packages, build artifacts, configure a named target, start the application and prepare immutable view bytes.
Discover & refresh
Register an MCP endpoint and discover its tool and UI association. After a release, verify the card the host loaded carries the current release.
Invoke & finish
Send a question, call the API, return one full result and release the per-request server lifetime. Calls remain independent.
Mount & retire
Connect the bridge, wait for fonts, present the latest result and apply host context. Teardown releases owned browser resources.
What this walkthrough establishes
It explains checked application source, using real names and exact excerpts. The interactive diagrams and card examples are synthetic and make no network requests.
- Runtime and view composition are grounded in the complete application source of app
0.17.2as it is committed in this folder. - SAGA is installed from the public npm registry: the stack
1.0.1and the siblings it pins exactly (core,componentsandreact1.0.0,mcp1.0.2); the root lockfile records their registry integrity. - This document is a fresh explanation of the full architecture, not a summary of changes from an earlier version.
What must be verified in a host
- A real tool invocation and an actual embedded answer card.
- Matching application revision, SDK identity and served resource bytes.
- Fonts, language direction, attribution, sizing and the relevant consent interactions.
- First-load success distinguished from recovery after Retry.
Rendering inside ChatGPT, Claude and Alexa+ is a separate host acceptance. Neither this document nor this repository’s automated checks establish it.
Read the source offline
Each path links to its exact source commit on GitHub. The embedded source remains available offline through “Read embedded source”.
Why build on SAGA
Ansari could build this card directly on the MCP Apps SDK. Building on SAGA instead means Ansari starts from A2UI’s published protocol and a complete answer component, so its own code deals with answers and branding rather than MCP Apps wiring.
A published binding contract
A2UI specifies how component properties bind to data-model paths and how model updates converge. SAGA uses the upstream A2UI processor and React surface rather than a second binding engine. Ansari’s card binds two fields: the contract version and the answer Markdown.
A complete answer card
FaithfulCard renders the whole answer: nested lists, quotes, code, mixed-direction text, labelled scrollable tables, and links that open through the host with their hostname shown. It also handles answer replacement and view readiness. Ansari styles its documented surface with its own theme.css.
MCP Apps stays behind the stack
An MCP App has two ends of one iframe channel: the view’s App and the host’s AppBridge, with mirrored methods. A view can ask with requestTeardown(), but only the host’s AppBridge.teardownResource() tears the view down. The specification describes wire messages, with host and view rules side by side, and names neither class. AppBridge’s host role appears only in the overview diagram and its API reference, so a view author has to work out which half applies. Ansari’s source imports nothing from @modelcontextprotocol/ext-apps.
What a direct build would add
Rough estimate for the same card built on ext-apps, React and a maintained Markdown renderer:
- View: about 700–1,500 TS/TSX lines plus 100–200 CSS lines for the rendering rules, host links, readiness, sizing and lifecycle.
- Server: about 50–150 lines for the versioned card resource, output validation, failure mapping, the 60-second deadline and per-request cleanup.
- Together, about 750–1,850 lines, next to the app’s current 1,927 lines of source.
Tests are not counted. No direct version has been built, so these figures are order-of-magnitude estimates, not measured savings.
What Ansari still owns
- What an answer means and every user-facing status sentence.
- The theme, host-color mapping, Kitab fonts, floral artwork and attribution treatment.
- Hono hosting, the Node and Worker entry points, and deployment.
- SAGA upgrades and host acceptance.
In exchange, fixes to parsing, the card and delivery arrive from upstream with their regression tests (saga-a2ui, Apache-2.0).