## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Agents call connected apps while they work on tasks. > - Some app tools include a widget that Paperclip shows with the reply. > - GitHub identity lookups include a profile widget. Repeated lookups fill the reply with copies of the same card. > - This pull request omits the known GitHub identity view when Paperclip selects reply widgets. > - The benefit is that task replies show useful app results while identity calls remain in the tool history. ## Linked Issues or Issue Description **What happened?** A task that reads GitHub activity showed four copies of the connected account's profile widget. Each copy came from a successful `get_me` call. Paperclip showed these intermediate lookup results with the reply. **Expected behavior** GitHub identity lookups stay in the folded tool history. Other app widgets keep their normal reply placement. **Steps to reproduce** 1. Connect GitHub through its MCP server. 2. Run a task that calls `get_me` several times to find the connected account. 3. Open the task reply. Each lookup adds a profile card. **Paperclip version or commit** Reproduced in the UI tests against base commit `8285a81280db`. **Deployment mode** Authenticated server. The rendering path is shared with local instances. Related work: [MCP Apps support](https://github.com/paperclipai/paperclip/pull/21119), [MCP Apps reply views](https://github.com/paperclipai/paperclip/pull/21266). Searched open issues and PRs for `get_me`, GitHub widgets, and MCP Apps. No duplicate fix was found. ## What Changed - Omit a view from the reply index only when its upstream tool is `get_me` and its resource is `ui://github-mcp-server/get-me`. - Apply the filter before the per-run widget limit. This covers saved history and live replies through their shared index. - Add tests for repeated saved identity calls, widget pagination, and other GitHub and app views. - Document the display policy in the MCP Apps guide. The MCP Apps UI owns reply selection. Tool execution, view storage, API responses, and the folded tool history keep their existing behavior. ## Verification - Red-green reproduction: the three new regression tests failed before the source change and passed after it. - `pnpm exec vitest run ui/src/components/mcp-app/`: 6 files, 36 tests passed. - `pnpm --filter @paperclipai/ui typecheck`: passed after building the worktree's missing SDK declarations with `pnpm --filter @paperclipai/plugin-sdk ensure-build-deps`. The first typecheck failed because those generated declarations were absent. - `git diff --check`: passed. Reviewed the diff for secrets, personal data, and run artifacts. - `pnpm verify --explain`: exited 2 because the guide is a global CI input. Required CI must supply broad coverage. An earlier selection was invalidated by the guide edit and was rerun. - Browser acceptance and a deployed staging check have not been run. The saved-widget regression uses the shared React reply component. - [Greptile review](https://github.com/paperclipai/paperclip/pull/22217#issuecomment-6988213101): 5/5 for head `c842d21bff6de1b2084593abfff69e789775b163`, with no actionable findings or unresolved review threads. Required CI is still running. ## Risks - Low risk. The display filter matches one known tool and resource pair. Other widgets remain visible. - This release hides GitHub profile cards even when a task intentionally calls this tool to read a profile. The text result remains in the tool history. - No schema migration or stored-data cleanup is required. Existing saved cards disappear from replies after the updated UI loads. ## Model Used - OpenAI GPT-6.1 Sol (`gpt-6.1-sol`) through Codex in T3 Code, with xhigh reasoning effort, tool use, and code execution. ## 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 - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge Co-authored-by: Paperclip <noreply@paperclip.ing>
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 |
GitHub's get_me profile view (ui://github-mcp-server/get-me) is omitted from
reply widgets, including views saved by earlier runs. Identity lookups remain
in the folded tool history. Other app views keep their normal reply placement.
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.