Appearance
0045: MCP Apps: where GetMy Books shows interactive UI
Proposed 2026-11-02, for the Product Owner (QD-49).
Decided 2026-11-04. Decided by: Product Owner (in chat, choosing the recommended option). QD-49 is answered "allow, within the limits below"; decision 3 records the answer and the pilot.
Context
The MCP Apps extension lets an MCP server hand a Claude client a small HTML page to show inside the conversation, next to the tool reply. Issue #99 asked for an investigation: which clients show it, whether it fits docs/not-doing.md, and whether it is safe, and then a short ADR on whether and where to use it.
Most of the investigation has since been answered by something that shipped. The approval card (plan docs/plans/human-confirmation-for-writes.md, decided 2026-10-01; PRs #122, #126, #127, #130 and #315) is an MCP App. It is the only interactive UI GetMy Books shows today, and it exists for one reason: a Xero write must follow a human action the model cannot see, answer or fake (ADR 0005, AUDIT C5).
What is proven, from the shipped card:
- Clients. Claude Desktop and the claude.ai connector show the card; the Product Owner tried it in Claude Desktop on 2026-10-01, and the deployed connector shows it on claude.ai. Claude Code cannot show it (its terminal has no MCP Apps host), so it cannot approve a write; the text summary is the base for every client. Whether the Claude mobile app shows the card has not been recorded.
- Delivery. The card is one resource,
ui://getmy-books/approval-card.html, served astext/html;profile=mcp-app(src/mcp/approval-card.ts). Its markup, style and script live insrc/mcp/approval-card/and the@modelcontextprotocol/ext-appsclient bundle (pinned, 2.0.3) is inlined into that one page. The page loads nothing from outside: nosrc=orhref=at all (tests/mcp/approval-card-html.test.ts). - Figures. The card shows the summary text and
structuredContentthat code insrc/present/built fromsrc/rules/andsrc/vat/output. It computes nothing and the model writes nothing it shows. - Model boundary. The card's tool,
write_preview_decide, carries_meta.ui.visibility: ["app"], so hosts leave it out of the model's tool list; the preview's one-time token travels in_meta, which the model does not read. In Claude Desktop the model could neither call the tool nor quote the token.
What is not decided is the other use the issue named: a read-only table or chart of books data (an aged-debtors table you can sort, a cash chart, a VAT return laid out like the form). docs/not-doing.md rules out "a dashboard of the books themselves, or a chat UI of our own", because Claude is the interface; docs/vision.md lists the same under what we are not building. ADR 0041 allows the account home and the owners' view because they show the account, subscriptions and usage counts, never books data. A view rendered by Claude, inside the conversation, from a tool reply is arguably still "Claude is the interface". It is also arguably the first step towards the dashboard the rule exists to stop. That is the Product Owner's call, not the agent's.
Decision
- The approval card stays as it is. MCP Apps is the way every Xero write is approved (ADR 0005, the plan above). Nothing here changes it.
- Recorded as settled: the card is shown in Claude Desktop and on claude.ai; Claude Code cannot show it, so a write cannot be approved there and the text summary remains the base reply for every client; the bundle is inlined and pinned, the page loads no outside script or style, and every figure a card shows comes from
src/present/. - QD-49, decided 2026-11-04 (Decided by: Product Owner): allowed. A read-only table or chart of books data, rendered inside Claude from a tool's
structuredContent, counts as "Claude is the interface", not as the dashboarddocs/not-doing.mdrules out, within these limits:- A view renders only the
structuredContentthe tool already returns, built by code insrc/present/fromsrc/rules/andsrc/vat/output; it adds no figure, total, rounding or conversion of its own. Where it orders rows, it orders them by the pence code worked out, never by a figure it read from text. - It is read-only: no button in it calls a tool, it sends no message and puts nothing in Claude's context, and nothing in it is approval.
- It loads no outside script, style, font or image: one page, with the pinned
@modelcontextprotocol/ext-appsbundle inlined, as the card's is (src/mcp/app-page.tsnow serves both). - The text summary stays the base reply, so Claude Code and any client without MCP Apps lose nothing.
- Each view has the two tests the card has: a refactor-guard test over its HTML and a fake-host test of its script.
- The pilot is
payments_aged(SPEC-006 S19, issue #99). The resourceui://getmy-books/aged.html(src/mcp/aged-view.ts, assets insrc/mcp/aged-view/) is linked from the tool's_meta.ui, as the card is from the preview tools. It shows, under the summary's headings, one sortable table per side (owed to you, you owe), one row per contact and a Total row, from cellssrc/present/aged.tsbuilds once for both the summary and the view. Tests:tests/mcp/aged-view-html.test.ts(refactor guard: nosrc=,href=or fetch, no tool call) andtests/mcp/aged-view.test.ts(fake host: the table's cells equal the summary's, one for one). - Exit test (Product Owner, still to run): open
payments_agedfor FEAW in Claude Desktop and on claude.ai; the table's figures match the text summary one for one. The outcome is recorded here.
- A view renders only the
- Unchanged whatever the answer: no MCP Apps view ever shows a figure the model produced; no view is a page of our own outside Claude (the account home and owners' view of ADR 0041 are the only web pages, and they hold no books data); Claude Code approves nothing.
Consequences
- QD-49 is answered (2026-11-04, Product Owner). Its entry in
docs/sge/questions.mdand the ROADMAP decision sheet are updated by the docs owner. docs/not-doing.md's dashboard row keeps its rule and cites this ADR: read-only views of code-built content inside Claude are allowed; a dashboard of the books, or any page of our own holding books data, is still not.- The pilot is one small slice under SPEC-006 (S19), with its own tests. The approval card's page now shares its bundle loading with the view (
src/mcp/app-page.ts); its served HTML is unchanged, byte for byte. payments_aged's reply keeps the summary and JSON text as before;structuredContentadds the view's cells (view), which the JSON text leaves out so the model reads no second copy.- Still to record: the pilot's exit test outcome, and whether the Claude mobile app shows the approval card and the view (Product Owner, the only client the issue named that has not been tried).
Amendment 1: one approval page on the web (DH-7, SPEC-022)
Decided 2026-11-09 by the Product Owner, answering Q1 on PR #382. Drafted the same day for the Product Owner's final read. It takes effect when SPEC-022 ships: this amendment, docs/not-doing.md and the code merge together.
Context. Claude Code cannot show the approval card (decision 2), and closing port 5433 (#73) moves the owners' real work to the deployed endpoint (DH-6). SPEC-022 S6 lets a preview made in Claude Code be approved by a person on the web instead. Decision 4 says no view is a page of our own outside Claude and Claude Code approves nothing; this amendment makes one narrow exception to both.
Decision. One page of our own may show books data: the approval page for a single Xero write preview, https://mcp.getmy.group/approve/<previewId>, within these limits:
- One preview only. It shows the one preview its link names: the summary code built for it (
src/present/), its expiry, Approve and Decline. No list of previews, no navigation to other books data, no search. - Read-only, except Approve and Decline. It shows the preview and edits nothing. Opening it writes nothing. Pressing Approve makes exactly the write the card's Approve makes, through the same claim (SPEC-003 S38, SPEC-011 S4); Decline declines it.
- Behind Cloudflare Access sign-in, as the account pages are (ADR 0041), for a person who may write to that company (SPEC-022). Anyone else, or an expired, declined or written preview, sees no Approve.
- The model cannot approve through it. The link carries no one-time token, and a request without a signed-in person's press of Approve writes nothing. Nothing said in the chat is approval.
- Same page rules as the card. It loads no outside script, style, font or image, computes no figure, and has a refactor-guard test over its HTML.
Unchanged. There is still no dashboard of the books and no other page of our own holding books data. Read-only MCP Apps views inside Claude stay as decision 3 says. Decision 4 now reads: no view is a page of our own outside Claude except this approval page; Claude Code approves nothing in the chat, and a person approves its previews only on this page.