## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - MCP Apps (#21119) show interactive widgets from MCP servers, such as Circleback meeting cards, with the agent's reply in the task chat. > - The first version deferred three parts of the MCP Apps spec. A widget could not propose a chat message (`ui/message`). It could not give the agent context (`ui/update-model-context`). It could not go full screen. > - Paperclip also ignored the `icons` that MCP servers declare on tools (SEP-973). > - The security review of #21119 showed what these features need from day one: explicit consent, untrusted-data labels and strict icon sanitizing. > - This pull request adds the three host features and provider tool icons, with those protections built in. > - The benefit is that widgets can now work with the person and the agent, not only display data. ## Linked Issues or Issue Description Refs #21119 **Subsystem affected** MCP Apps host (task chat widgets), tool catalog, run wake prompt. **Problem or motivation** The MCP Apps host refused `ui/message` (-32601), dropped `ui/update-model-context` and kept every view inline. MCP tool `icons` were not parsed or shown. So widgets could not ask the agent a follow-up, the agent could not see what the person selected in a widget, large widgets were cramped, and tool rows used only generic icons. **Proposed solution** Add consent-gated view messages, per-view app context delivered to the task's next run as untrusted data, a full-screen dialog, and sanitized provider icons. Details are under "What Changed". **Alternatives considered** - Send view messages with a new server route that creates the comment itself. Rejected: comment creation has many rules (agent chat ownership, paused conversations, queued delivery, wakeups, receipts). The widget's Send button uses the same send path as the composer. A small route then records which view the comment came from. - Keep the iframe in place for full screen with CSS. Rejected: chat containers can create containing blocks that break `position: fixed`. A moved iframe always reloads, so the dialog hosts a new frame instead. **Roadmap alignment** Continues the MCP feature work after #21119, #21140 and #21219. It does not touch the MCP Tasks work (gateway `tools/call` polling and elicitation). ## What Changed - **`ui/message`.** The host shows "<App> wants to send: …" with **Send** and **Dismiss** under the widget (and inside the full-screen dialog). Nothing is sent before the click. Send posts the text as the viewer's own comment through the chat's normal send path (`handleThreadAdd`). `POST /api/issues/:issueId/mcp-app-views/:viewId/messages` then logs `issue.mcp_app_message_sent`. It accepts only the caller's own comment on the same task, matched by `clientRequestId`, from the last 10 minutes. One proposal per view can wait at a time. The view gets `{}` after the send, or -32000 "Message sending denied" after Dismiss. Only `user` text up to 8,000 characters is accepted. - **`ui/update-model-context`.** `PUT /api/issues/:issueId/mcp-app-views/:viewId/model-context` stores the latest context per view in `tool_mcp_app_views.model_context` (text blocks and `structuredContent`, 16 KB at most). Updates are applied in order and deduped in the browser and on the server. A change logs `issue.mcp_app_context_updated`, and an empty update clears the context. The task's next run gets the three most recently updated contexts as an `## App context (untrusted)` wake-prompt section. The section quotes the data as JSON and says it is third-party data, not instructions. The read runs in parallel with the other run preparation and never fails the run. CLI adapters and the native runner render it through the same `renderPaperclipWakePrompt`. - **Who may do this.** Messages and context need a signed-in person with `issue:comment` on the task. Agents and API keys get 403. Other tasks and companies get 404. `message` and `updateModelContext` are advertised in `hostCapabilities` only where the viewer can send messages. - **Full screen.** The host advertises `availableDisplayModes: ["inline","fullscreen"]` and handles `ui/request-display-mode`. It honors the view's declared modes and answers with the resulting mode. It sends `host-context-changed` with `displayMode` and the container (fixed `height`/`width` in full screen), and again when that container resizes. A new **Open full screen** control sits next to "Widget from …". Full screen is a Paperclip dialog that closes with Exit, Escape or the view's own request. - **Provider tool icons.** `icons` on MCP tool descriptors are sanitized into the new `tool_catalog_entries.icons` column, outside the version hash, so a new icon never quarantines a reviewed tool. Only `https:` URLs and `data:image/*` URIs are kept, and SVG only as `data:`. A `data:` icon is at most 32 KB, a URL at most 2,048 characters, with at most 4 icons per tool. `GET /api/companies/:companyId/tool-icons` lists them keyed by gateway tool name, in one cached request per chat. Task chat tool rows and the app's actions list show them through `ProviderToolIcon`. It renders `<img referrerPolicy="no-referrer">` at a fixed size and never inlines markup. It checks the source again before rendering and falls back to the taxonomy icon. - **Schema.** Migration `0477` adds `tool_catalog_entries.icons`, `tool_mcp_app_views.model_context` and `model_context_updated_at`, all nullable. - **Docs and stories.** `doc/connections/MCP-APPS.md` documents the new behavior, and the finished items are removed from "Limits and follow-ups". `Tasks/MCP App views` has new stories: "View asks to send a message", "Full screen" and "Tool rows with provider icons". The fixture view now uses `ui/message`, `ui/request-display-mode` and `ui/update-model-context`. ## Verification - `pnpm exec vitest run server/src/__tests__/mcp-apps.test.ts server/src/__tests__/tool-catalog-publication.test.ts server/src/__tests__/openapi-routes.test.ts packages/shared/src/mcp-icons.test.ts packages/shared/src/mcp-apps.test.ts`: pass (embedded Postgres). These tests cover: - Context: stored, deduped, logged once, 413 when too large, cleared, scoped to the task and company, refused for agents (403), and rendered into the wake prompt as untrusted data. - Messages: attributed only to the viewer's own recent comment on the same task. A teammate's comment, an unknown request id or an old comment gets 404. An agent gets 403. - Icons: stored sanitized, and the version hash and status do not change. Another company sees nothing. - `cd ui && pnpm exec vitest run src/components/mcp-app/ src/components/ProviderToolIcon.test.tsx src/pages/apps/app-detail/`: 69 pass. These tests cover: - The host protocol for each new method: capabilities, consent wait, one proposal at a time, invalid input, ordered and deduped context, the size limit, and the display-mode rules. - The consent card (nothing sent without Send). - The full-screen dialog (one frame at a time). - Icon rendering (no-referrer `img`, no inline SVG, fallback). - `cd ui && pnpm typecheck` (including Storybook) and `tsc --noEmit` for the server: clean. - Red/green: the new route and host tests fail on `master`, where the routes do not exist and the host answers -32601 or drops updates. The icon descriptor test failed when the publication write was removed. - Not run locally: the full suite, and `packages/adapter-utils/src/server-utils.test.ts › runChildProcess › does not crash when the child closes stdin before a delayed write`. That test times out on this Mac with or without this change, so it is a local platform issue. CI covers both. ## Risks - Migration risk is low: three nullable columns, no backfill. - Every run on a task now does one extra indexed read, in parallel with the other preparation. Errors are logged and the run continues without app context. - If the attribution request fails after the comment is sent, the comment stays without the `mcp_app_message_sent` activity row. This is documented. - Switching between inline and full screen restarts the view, so state inside the widget resets. This is documented as a limit. - Icon names shortened with a hash by the gateway (very long names) do not match, and those rows keep the taxonomy icon. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use and code execution. One subagent (the same model) built the provider-icon part. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [ ] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
12 KiB
MCP Apps: interactive views in the task chat
Some MCP servers attach an interactive view to a tool. When an agent calls the
tool, the view appears in the task chat under the tool row. The first provider
that uses this is Circleback: DisplayMeetings,
DisplayActionItems and DisplayCalendarEvents render meeting, action item and
calendar cards.
The standard
These views are MCP Apps, the first official MCP extension:
- Specification: SEP-1865, version 2026-01-26 (overview).
- Extension id:
io.modelcontextprotocol/ui. - Other hosts: Claude, Claude Desktop, Claude Code, VS Code Copilot, Goose and Postman.
The protocol works like this:
- The tool declares a view. The tool's
_meta.ui.resourceUrinames aui://resource._meta.ui.visibilitylists who may call the tool:"model"means the agent can call it. The default is["model", "app"].- A tool marked
["app"]is hidden from the agent and only the view can call it. - Paperclip also reads the deprecated flat key
_meta["ui/resourceUri"].
- The resource is an HTML document.
resources/readreturns it with the mime typetext/html;profile=mcp-app. The resource's_meta.uican also carry:csp.connectDomains,resourceDomains,frameDomainsandbaseUriDomains;permissions;prefersBorder.
- The host renders the view in a sandboxed iframe. The host and view then
talk JSON-RPC over
postMessage:- The view sends
ui/initializeand the host answers with its capabilities and host context: theme, style variables, locale, size limits and tool info. - The view sends
ui/notifications/initialized. - The host sends
ui/notifications/tool-inputand thenui/notifications/tool-result, which carries the fullCallToolResult, includingstructuredContentand_meta. - After that, the view may send
ui/notifications/size-changed,tools/call,ui/open-link,ui/update-model-contextandping. - Before removing the iframe, the host sends
ui/resource-teardown.
- The view sends
Composio and other aggregators
The Composio Circleback toolkit cannot carry views:
- It has 11 read tools.
- It has none of the
Display*tools. - Composio's meta-tools return plain JSON.
So views need a direct MCP connection, and Circleback is now a native catalog app. When an app has a native entry, search prefers it over its aggregator listing. See CONNECTION-SEARCH.md.
How Paperclip implements it
| Layer | What happens | Code |
|---|---|---|
| Client capability | Paperclip advertises extensions["io.modelcontextprotocol/ui"] when it initializes an MCP session. |
server/src/services/mcp-http.ts |
| Catalog | Each tool's normalized _meta.ui is kept in tool_catalog_entries.ui_meta. It is not part of the version hash, so adding a view never quarantines a reviewed tool. |
server/src/services/tool-access/catalog/ |
| Agent tool list | Tools whose visibility omits "model" are not listed to agents and cannot be called by them. |
isModelVisibleTool in server/src/services/tool-gateway.ts |
| Recording | Each successful call to a tool with a view stores one tool_mcp_app_views row: issue, run, agent, connection, the redacted arguments and the redacted CallToolResult. The tool result _meta is kept here and never sent to the agent. Recording is best effort and never fails the agent's call. |
server/src/services/mcp-app-views.ts |
| API | GET /api/issues/:issueId/mcp-app-views lists a task's views. GET …/:viewId returns the view, reading the ui:// document live through the agent's connection. POST …/:viewId/tool-calls runs a view's tools/call. Reading follows task read access. Tool calls also need the tools:use or tools:manage_connections permission, and only reach tools of the same connection that allow "app". They go through the same policy, Ask-first approval and audit path as a connection test call. |
server/src/routes/mcp-apps.ts |
| Chat | A run's views render with that run's reply, outside the folded tool history, under a "Widget from " label with an "Open full screen" control. Views are keyed by the reply's run, so settled history needs no transcript. A task's views load in one request and are indexed by run once. | ui/src/components/mcp-app/, TaskChatRunnerTurn.tsx and TaskChatThreadView.tsx |
| View messages | A view's ui/message shows a card under the widget: " wants to send: …" with Send and Dismiss. Nothing is sent until the viewer clicks Send. The text is then sent as the viewer's own comment through the chat's normal send path, exactly like a typed message. POST …/:viewId/messages then records issue.mcp_app_message_sent for that comment; it accepts only the caller's own comment on the same task from the last 10 minutes. |
McpAppView.tsx, server/src/routes/mcp-apps.ts |
| View context | A view's ui/update-model-context is stored per view (tool_mcp_app_views.model_context, 16 KB at most) by PUT …/:viewId/model-context. Identical updates are deduped in the browser and on the server; a change logs issue.mcp_app_context_updated; an empty update clears it. The task's next run receives the three most recently updated contexts as an "App context (untrusted)" section of its wake prompt, quoted as JSON data and labelled as third-party data, not instructions. It is read in parallel with the other run preparation and never fails the run. |
server/src/services/mcp-app-views.ts, heartbeat/execution-configuration.ts, renderPaperclipWakePrompt |
| Tool icons | Provider icons (SEP-973) on MCP tools are sanitized into tool_catalog_entries.icons, outside the version hash. Task chat tool rows and the app's actions list show them, falling back to the usual icons. |
server/src/services/tool-access/catalog/, ui/src/components/ProviderToolIcon.tsx |
Sandbox
The view runs in a srcdoc iframe with sandbox="allow-scripts allow-popups allow-popups-to-escape-sandbox". It never gets allow-same-origin. Its origin
is therefore opaque, so it cannot read Paperclip's DOM, cookies or storage, and
it cannot call the Paperclip API.
The spec's double-iframe proxy on a separate origin solves the same problem for hosts that render on their own origin. Paperclip uses a single opaque-origin frame instead and installs the CSP itself:
- The CSP is a
<meta http-equiv>placed before any of the view's markup. - It starts from the spec's restrictive default and adds only well-formed
https://origins that the server declared. - Keywords, schemes, paths and
*are dropped. - Without declared origins,
connect-srcandframe-srcare'none'.
Messages are accepted only from the iframe's own window. The host sends nothing
until the view reports initialized.
The host answers view requests as follows:
ui/open-linkopens onlyhttp(s)URLs, in a new tab without an opener.ui/messagewaits for the viewer's decision: the view hears success only after the comment was sent, and "Message sending denied" when the viewer dismissed it. One proposal per view can wait at a time; further ones are refused until it is settled. Only text from theuserrole is accepted, up to 8,000 characters.ui/update-model-contextis applied in order and deduped. Text blocks andstructuredContentare kept; other content is dropped.ui/request-display-modehonors the view's declaredavailableDisplayModes. The host offersinlineandfullscreen(no picture-in-picture) and answers with the resulting mode. Full screen is a Paperclip dialog; switching modes starts the view again in its new place, since a moved iframe always reloads. The view getshost-context-changedwith the new mode and its container (a fixedheightandwidthin full screen,maxHeightinline) and again when the full-screen container resizes.messageandupdateModelContextare advertised inhostCapabilitiesonly where the viewer can send messages on the task. Without that,ui/messageis refused (method not found) and context updates are accepted and dropped.- Viewers who cannot comment on the task, agents and API keys cannot send a view's messages or set its context.
Tool icons
Icons are untrusted provider data, so they are sanitized when the catalog is refreshed and again before rendering:
- Only
https:URLs anddata:image/*URIs are kept. SVG is accepted only as adata:URI, never from a remote URL, so it cannot change after review. - A
data:icon is at most 32 KB; a URL at most 2,048 characters; at most four icons per tool. Unknown mime types, sizes and themes are dropped. - Icons are always drawn as
<img referrerPolicy="no-referrer">at a fixed size. Markup is never inlined, so an SVG's scripts never run. A broken icon falls back to the taxonomy icon.
Testing plan
| Level | What it proves | Command or location |
|---|---|---|
| Shared unit | _meta.ui parsing (current and legacy keys, visibility, non-ui:// rejected), resource parsing (text and base64, mime check), CSP sanitizing |
pnpm exec vitest run packages/shared/src/mcp-apps.test.ts |
| UI unit | Host protocol: initialize result, nothing sent before initialized, tool input before tool result, tools/call proxy and errors, link and method refusals, teardown. ui/message waits for the viewer and allows one proposal at a time; context updates are ordered, deduped and bounded; display modes honor the view's declaration; capabilities are advertised only when implemented. The consent card and the full-screen dialog. CSP placed before the view's markup. The run index at a realistic size. |
pnpm exec vitest run ui/src/components/mcp-app/ |
| Server integration (embedded Postgres) | Circleback catalog OAuth (DCR) against a fake Circleback server. ui_meta stored. An app-only tool is hidden from the agent. An agent call records one view with input, structured content and _meta, and a call without a view records none. Routes list the view and serve its document and CSP. A view's tool call works, and a model-only tool is refused. Other tasks, other companies and agent actors are refused. A view's context is stored, deduped, bounded, logged, cleared, and rendered for the task's next run as untrusted data. A view's message is attributed only to the viewer's own recent comment on the same task. |
pnpm exec vitest run server/src/__tests__/mcp-apps.test.ts |
| Storybook | The view with the agent's reply, the ready view (Refresh calls a tool), loading, view unavailable, a tool call that needs approval, a view asking to send a message, full screen, and tool rows with provider icons. The fixture view follows the protocol by hand. | Tasks/MCP App views (ui/storybook/stories/tasks/task-chat-mcp-app.stories.tsx) |
| Live end to end | Connect Circleback with a real account and ask an agent for a recap of a recent meeting. Check that the chat shows the meeting cards and that clicking a card opens Circleback. Done on 2026-11-12. The run found the view-size and placement bugs. | Manual, local pnpm dev |
Limits and follow-ups
- Picture-in-picture is not supported. Switching between inline and full screen restarts the view, so state inside the widget resets.
- A view's message is attributed in the activity log by a second request after the comment is sent. If that request fails, the comment stays, without the attribution.
- Icons are shown for tools only, not yet for MCP resources or prompts.
- Views are rendered in the task chat only, not in other transcript surfaces.
- A view document can be at most 4 MB of HTML. Circleback's is about 3.5 MB.
- Local stdio MCP servers are recorded the same way, but no stdio provider with views has been verified yet.