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 public 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 and request-lifetime attachment.
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 0.7.6 ++ 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.
Ansari Owns the product
Question and answer contract, API client, status wording, fonts, branding, attribution treatment, HTTP configuration and platform entry points.
SAGA stack 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
/mcpadmission, request budgets and lifetimes.Host 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 preparationIndependent requestsTry the lifetime model
This small model illustrates ownership; it does not send MCP traffic.
1prepared views0active calls0retired callsReady. 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 + dependenciesInstall the SAGA 1.0 candidate
@saga-a2ui/react-mcp-stack + 0.0.0-candidate.g8b4d987dd233 react 19.3.1 react-dom 19.3.1 -All five SDK siblings: 0.7.6 -@a2ui/markdown-it override: 0.2.1The app imports only stack subpaths. The application pins these exact public npm packages in the repository root’s one committed lockfile; no SDK source checkout, local tarball or package-manager override for SAGA is involved.
→Build-time content policyProduce self-contained HTML
Vite + single-file plugin +All five SDK siblings: same version + apps/mcp/candidates/ (SDK 8b4d987) +@a2ui/markdown-it override: 0.2.1The app imports only stack subpaths. The manifest pins the SAGA 1.0 release candidate, packed from the SDK’s source at commit
8b4d987and committed underapps/mcp/candidates/until1.0.0-rc.1is on the npm registry. The rootpnpm-workspace.yamloverrides the five siblings to those tarballs, and the root’s one committed lockfile records their integrity. No private registry or credential is involved.→Build-time content policyProduce self-contained HTML
Vite + single-file plugin React + card code + CSS embedded Kitab + floral assets application + SDK identity @@ -67,21 +69,22 @@ Worker: pnpm build:worker Wrangler deploy --dry-run - dist-worker/ bundle + HTMLA dry-run build does not publish or deploy a Worker.
Identity follows the final bytes
Build stamps app + SDK identity + dist-worker/ bundle + HTMLA dry-run build does not publish or deploy a Worker.
The address names the compatibility line
Build stamps app + SDK identity ↓ Runtime stamps release / revision ↓ -operationViewFromHtml(final HTML) +operationViewFromHtml(final HTML, + major: VIEW_MAJOR = 1) ↓ -content-addressed MCP resourceA changed release marker can legitimately change the resource URI. The same URI must link discovery, tool results and resource reads.
Validate the installation and artifacts
pnpm install --frozen-lockfile \ +ui://views/answer-card.v1.htmlA release stamp or a compatible card change keeps the address and changes only the bytes. Only a change an already-loaded card cannot handle increases
VIEW_MAJOR. The same URI links discovery, tool results and resource reads.Validate the installation and artifacts
pnpm install --frozen-lockfile \ --strict-peer-dependencies 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 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.
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 host sees the current resource identity.
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.16.6as it is committed in this folder.- SAGA
0.7.6is 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”.
- 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.
01 · Protocol 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.
02 · Component 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.03 · Shielding MCP Apps stays behind the stack
An MCP App has two ends of one iframe channel: the view’s
Appand the host’sAppBridge, with mirrored methods. A view can ask withrequestTeardown(), but only the host’sAppBridge.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 content-addressed 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,394 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).
| 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; a candidate SDK is data-sdk-kind="candidate" with its source commit and tarball sha256 | 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.0as it is committed in this folder. - SAGA is the 1.0 release candidate
0.0.0-candidate.g8b4d987dd233, packed from SDK commit8b4d987and committed underapps/mcp/candidates/; the root lockfile records the tarballs’ 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).