Skip to content

ADR-022: MCP Apps views, on show and on every post

mm-mcp adopts MCP Apps. Four views exist: a thread and what is unread through show, a post as posted after create_post, dm and group_message, and a proposal after propose_post; this record holds for every one. In a client that renders them, a view puts what the person should see in front of them, laid out as Mattermost lays it out; a client that renders none gets text.

A view sits only on a tool whose every call the person should see, never on a tool the model reads with:

  • show, which the model calls once it has what the person asked to see. Its kinds are thread, a post alone or with its thread, and unreads: the unread channels, mentions and followed threads with unread replies that wait for the person. show reads what it draws itself, from ids, so its counts are Mattermost's and the model cannot put words in a view.
  • Every tool that posts, create_post, dm and group_message, which shows the post as posted.
  • propose_post, which shows the draft it proposes for the person to post, edit or discard (ADR-035).

show is listed to every client, since which tools are listed does not depend on what a client says it can do (ADR-021). A client that declared no views on the call is told that nothing was shown, and nothing is fetched for it. Whether a client renders views is read from each request, because a client may declare it on every request rather than once.

A view draws the structured output of the tool that reads its data, unchanged. show answers a thread with what read_post answers, and unreads with what get_user_channels with unread_only, list_mentions and list_threads with unread_only answer, a page of each, built by the same code; its output schema is one of those shapes, and so is that of the tool only views call, whose answers are read_post's and read_unread's. A tool that posts draws the post it answers with, which names where it went, and propose_post the draft it answers with, which names where it waits. That output travels in structuredContent. MCP Apps names that field for the view, but VS Code hands it to the model in place of the text, and Goose hands the view nothing else (mm-mcp#37). So in VS Code the model may read a thread twice, but never more than the data tool gave it. Nothing in the output exists for the view alone. What the view needs and the model does not, the page works out from what is there; what it needs that the model could use too goes into the data tool, for every client. Avatars, custom emoji, images and file previews the view reads as resources through the host, addressed by the ids and resource addresses the output carries, however large they are. mm-mcp fetches them with its own credential, because the client's webview has none. A host that does not pass a view's resource reads on, or does not hand back an image's bytes, gets initials, emoji names and file cards. Nothing goes in any part of a result that the model must not see, because some client hands each part to its model.

Claude Code is the one exception, by measurement. It passes on none of a view's reads, and it hands a result's _meta to the view and not to its model: a megabyte of it reached no request to the model, in its terminal or its desktop app. So to a client that calls itself claude-code and declares views, and to no other, show adds a thread's pictures to the result's _meta, under mm-mcp/pictures, as data addresses by their resource addresses: each author's picture, each custom emoji and each image's preview, at most 256 KiB each and 1 MiB in all. Claude Code keeps _meta in its transcript on the person's machine, which is why it is bounded. The page takes a carried picture before it reads one, and accepts only an image. Once Claude Code passes a view's reads on, this goes.

What a person does in a view, opening a channel in place or pressing a button, goes through tools that only views call, marked visibility: ["app"]. Each is annotated as what it does, as every tool is (ADR-021): one that changes nothing, such as view_action, as read-only, and one that changes something as writing, so that no client runs it unchecked and a read-only server does not offer it. An action that changes something never goes through a tool annotated read-only. These are the only tools listed by what a client declares: each is listed only to a request that declared views, because a client that does not know MCP Apps ignores the mark and would offer its model a tool that acts without asking, and each refuses a call whose request declared none. A call from a view never asks the person anything, because Goose fails such a question and VS Code hangs on it. A view that is refused a call, as Goose's approval modes refuse every call a view makes, says so and offers to open the place in Mattermost. A view acts only on a click, because clients run a view's code again when a conversation is reopened. It never sends ui/message, which enters the conversation as the person's own words. It may tell the model what happened through ui/update-model-context, in mm-mcp's fixed wording, but Goose does not pass that on, so the model learns an outcome from Mattermost itself.

The unread view lists at most 20 channels, 10 mentions and 10 followed threads, a screen or two, and says when Mattermost has more. It lists a channel by its counts, not its messages: those would cost a request for every channel listed, in every client, since what the view needs goes into the data tool, and the view opens a channel's unread messages in place through view_action, as read_unread reads them. Marking a channel read goes through view_change, annotated as writing, which a server offers only where writes are allowed, as do a proposal's Post, Edit, Discard and Replace mine; it is annotated as destructive too, since a press may replace or delete a draft (ADR-035). The page is told whether its server offers it, as it is told where the server's resources start, so it offers Mark read only where the press can work, in every client; a press is the person's own, so it never asks (ADR-021).

One page draws every view: plain JavaScript and CSS embedded in the binary with go:embed, with no build step and no third-party code, declaring no network domains. Text from Mattermost is never parsed as HTML: the page builds elements through the DOM, renders Markdown with a parser of its own that produces elements, and opens a link only through the host. It takes the host's theme and Mattermost's own wording. A count in a view is Mattermost's, and a view that lists fewer says so.

The page declares fullscreen beside inline, which is what makes a host offer it: Claude Code draws a button of its own beside each view, which opens it in a pane of its own, and VS Code has inline alone. The host gives and takes it. The page fills the frame it is given, and an opened image is alone in that frame, fitted to it, since an image is what cannot wrap to use the room inline and is often why a person opened the post. The page has no button of its own and never asks, since the host's reaches the same frame without taking room from every view.

Add a view only to a tool whose every call the person should see. Build elements, never HTML from strings; the browser tests under the views tag hold the page. Draw a view from the data tool's output, unchanged, and have the view fetch what serves the eye alone as resources. Send what a view does through the tools only views call, and an action that changes something through one annotated as writing.

A person takes in a thread faster laid out as Mattermost lays it out than from a model's account of it, and an image, which a model reads worst, is often why they want to see a post at all. A post is the write a person should always see: an agent posting in twenty channels is as loud for the person it posts for as for the people it posts to. A client spends space on every call of a tool that has a view, whatever the view draws, and a read the model makes for itself should not cost the person that. The text carried in the result lets a stored conversation render without mm-mcp running.

Not chosen

  • A view on each tool that reads, drawing one line unless the person asked to see it: VS Code gives every call of a tool with a view at least 100 pixels, whatever the view draws, so every read would leave a band.
  • The view's data in _meta: Goose replaces a result's _meta with its own before the view sees it.
  • A shape of the view's own beside the data tool's: Two shapes of the same thread drift apart, and in VS Code the model would read whatever the view's shape added.
  • Images in the result, for every client: A client that hands structuredContent to its model would fill its context with megabytes the model cannot use, and one not measured may do the same with _meta.
  • Images through a tool only views call: A client that declares views but ignores visibility would offer every input of that tool to its model, and a resource read lists nothing.
  • An image as base64 in a text resource, which reaches a Goose view intact where a binary resource does not: A resource that declares one type and holds another, to work around one client.
  • A view's own reads, such as paging a thread, as resources, which Goose's approval modes still pass on: Paging or opening something is a query with arguments, which is a tool's, and as resources they would be listed, and attachable to the model, in every client.
  • A channel's first unread lines in the unread view: Every channel listed would cost a request in every client, for lines the view opens in place on a click.
  • Whether writes are allowed, in the result: Goose replaces a result's _meta, and the structured output holds only the data tools' answers; the page, which the server serves, is where its server's settings go.
  • A Mark read that a read-only server refuses: Read-only is the default, so most views would offer a button that never works.
  • An opened image asking for fullscreen: Claude Code lists fullscreen but answers a view's request with inline, and VS Code has inline alone.
  • A component library rendered on the server: A thread and a composer need control over layout and Markdown rendering that a library constrains.
  • React bundled with a build step: Node in every build, and a large bundle in every view, for pages a few hundred lines of plain JavaScript draw.