mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-21 19:02:37 +01:00
feat(connections): render MCP Apps views in the task chat, starting with Circleback (#21119)
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Agents reach external apps through MCP connections. Paperclip
records each call and shows it as a tool row in the task chat.
> - MCP Apps (SEP-1865, extension `io.modelcontextprotocol/ui`, spec
2026-01-26) lets an MCP server attach an interactive `ui://` view to a
tool. Claude, Claude Code and VS Code render these views in chat.
Circleback uses them to show meeting cards.
> - Paperclip dropped the tool's `_meta.ui` at discovery and the
result's `_meta` at call time. Its gateway reported MCP App UI as
"unsupported". Circleback was reachable only through Composio, whose
toolkit has no `Display*` tools.
> - This pull request makes Paperclip an MCP Apps host. It also adds
Circleback as a native catalog connection.
> - The benefit is that a Circleback recap in a task shows the same
meeting cards as in Claude, and any other MCP server with views works
the same way.
## Linked Issues or Issue Description
**Subsystem affected**
Connections and apps (remote MCP gateway) and the task chat.
**Problem or motivation**
An agent that uses Circleback in Paperclip can only return text. The
same tools in Claude Code show interactive meeting cards
(`DisplayMeetings`). Paperclip discards the MCP Apps metadata, so it
cannot show them.
**Proposed solution**
Paperclip implements the host side of MCP Apps end to end. It keeps the
tool's view declaration and records each call that has a view. It
renders the view under the tool row in a sandboxed iframe that uses the
MCP Apps postMessage protocol. Circleback becomes a native catalog
connection, so its `Display*` tools are available.
**Alternatives considered**
Composio's `circleback_mcp` toolkit has 11 read tools and no `Display*`
tools, and its meta-tools return plain JSON, so it cannot carry views.
The spec's double-iframe sandbox proxy on a separate origin needs a
second origin that Paperclip does not have. A single opaque-origin
`srcdoc` frame with an injected CSP gives the same isolation.
**Roadmap alignment**
This extends the existing Apps catalog and MCP gateway. It adds no new
integration substrate (decision D4 in doc/connections/README.md).
**Additional context**
The standard, the design and the testing plan are in
`doc/connections/MCP-APPS.md`.
## What Changed
- **Shared:** `packages/shared/src/mcp-apps.ts` adds MCP Apps types,
`_meta.ui` and resource parsing (current and legacy keys), and a CSP
builder that keeps only well-formed `https` origins.
- **DB:** migration `0471` (`online_compatible`) adds
`tool_catalog_entries.ui_meta` and a new `tool_mcp_app_views` table.
- **Server, catalog:** discovery keeps each tool's `_meta.ui`. It is not
part of the version hash, so a view never quarantines a reviewed tool.
- **Server, gateway:**
- Paperclip advertises the MCP Apps client capability when it
initializes a session.
- App-only tools (`visibility: ["app"]`) are hidden from agents.
- The result `_meta` is kept for the view and is not sent to the agent.
- Each successful call to a tool with a view records a view row.
Recording is best effort.
- The gateway's `initialize` now reports `paperclip/mcp-app-ui:
host_rendered`.
- The context protocol (`resources/read`) now uses the injected test
transport, like the other remote calls.
- **Server, routes:** `server/src/routes/mcp-apps.ts`
- `GET /api/issues/:issueId/mcp-app-views` lists a task's views. It
needs task read access.
- `GET /api/issues/:issueId/mcp-app-views/:viewId` returns the view
document, read live through the agent's connection.
- `POST /api/issues/:issueId/mcp-app-views/:viewId/tool-calls` runs the
view's `tools/call`. It needs `tools:use` and reaches only tools of the
same connection that allow `app`. It uses the connection test-call path,
so policy, Ask first and audit apply.
- **UI:** `ui/src/components/mcp-app/`
- The host protocol: `ui/initialize` with theme, style variables and
size limits; tool-input; tool-result; size-changed; `tools/call`;
`ui/open-link` (http and https only); teardown.
- An opaque-origin iframe (`allow-scripts`, never `allow-same-origin`)
with the CSP placed before the view's markup.
- The views of a run render with that run's reply, in the live turn and
in settled history. They are keyed by the reply's run, so history needs
no transcript.
- **Circleback:** a native catalog app (`mcp-oauth`, DCR, `user
user:write`) with:
- the official logo;
- a reviewed risk classifier (Share* tools are writes, Delete* tools are
destructive, Display* tools are reads);
- warnings in the sign-in step;
- `doc/connections/CIRCLEBACK.md`.
Search now prefers a native app over an aggregator listing named "X
MCP".
- **Storybook:** `Tasks/MCP App views` shows the tool row with its view,
the ready state (Refresh calls a tool), loading, view unavailable, and a
tool call that needs approval.
## Verification
- `pnpm exec vitest run packages/shared/src/mcp-apps.test.ts
ui/src/components/mcp-app/`: 19 passed.
- `pnpm exec vitest run server/src/__tests__/mcp-apps.test.ts`: 3
passed, on embedded Postgres. The test connects Circleback through the
catalog with DCR OAuth against a fake Circleback MCP server. It checks:
- `ui_meta` is stored;
- an app-only tool is hidden from the agent;
- an agent call records one view with arguments, structured content and
`_meta`;
- a call without a view records nothing;
- the routes serve the view's HTML and CSP;
- the view's tool call works and a model-only tool is refused;
- another task, another company and an agent actor are refused.
- Circleback connector: 13 focused files, 645 tests passed. These are
the app definitions, search, aggregator fallback, connection intents,
tool policy, `AppsConnect` and `Browse`.
- Typecheck passed for `@paperclipai/shared`, `@paperclipai/server` and
`@paperclipai/ui`. `node scripts/storybook-catalog.mjs` and the
migration compatibility check also passed.
- Storybook check in the browser:
- In both themes, the view runs the handshake, renders the meeting cards
from `structuredContent`, picks up the theme variables, and resizes to
its content.
- Refresh sends `tools/call` and re-renders the cards.
- **Live Circleback end to end** on a local instance, with a real
Circleback account:
- Connected through the catalog entry with Circleback's dynamic client
registration and OAuth.
- Discovery stored the real view declarations:
- `DisplayMeetings` uses `ui://circleback/meetings.v2.html`.
- `DisplayActionItems` and `DisplayCalendarEvents` also have views.
- `ListAssigneeOptions` and `SetCalendarEventRecording` are app-only
helpers with no view. They are hidden from agents.
- A `claude_local` agent called `DisplayMeetings` on two tasks.
- The real 3.5 MB Circleback view rendered the meeting cards with the
agent's reply.
- Clicking a card opened that meeting in Circleback through
`ui/open-link`.
- The live run found two bugs, both fixed in this PR, each with a
regression test:
- The 1 MB tool-result limit blocked the view document.
- Views were hidden inside the folded tool history.
## Risks
- **New migration:** a new table and a nullable column. It is
`online_compatible`.
- **Existing connections:** tools get `ui_meta` on the next catalog
refresh. Until then, no view shows and the tool row is unchanged.
- **Untrusted provider HTML:** the view runs as provider HTML in an
opaque-origin sandbox. It cannot reach Paperclip's session, DOM or API.
Its network access is limited to the origins its server declared. A
view's tool calls use the viewer's permissions and the normal policy and
Ask-first path.
- **Agent tool lists:** app-only tools are removed from them. No current
provider marks tools app-only, so no listed tool disappears.
- **Search:** the change that prefers a native app over an "X MCP"
aggregator listing affects every app.
## Model Used
- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use and
subagents (one subagent authored the Circleback catalog connector).
## 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>
This commit is contained in:
1 parent
6a24b417c0
commit
8ff45c0fa9
67 files changed
+3865
-134
No files matched your search
@@ -0,0 +1,218 @@
|
||||
# Circleback
|
||||
|
||||
Updated: 2026-11-12. Status: catalog definition reviewed against official
|
||||
documentation and live provider metadata; live account qualification
|
||||
outstanding.
|
||||
|
||||
Circleback (`circleback.ai`) records meetings and writes notes, action items
|
||||
and transcripts. Its hosted MCP server also searches the signed-in user's
|
||||
calendar, connected email, people and companies, and manages action items,
|
||||
tags, folders and sharing. It appears in Apps and uses Paperclip's shared
|
||||
remote-MCP connection, vault, catalog, grants, policies, gateway, and audit
|
||||
trail. It is a resource connection, not Paperclip sign-in. No plugin or
|
||||
database migration is required. The only provider-specific runtime code is a
|
||||
reviewed risk classifier (see [Capabilities and policy](#capabilities-and-policy)).
|
||||
|
||||
Paperclip connects to Circleback's hosted MCP server at
|
||||
`https://circleback.ai/api/mcp` (Streamable HTTP) with one method:
|
||||
|
||||
- `mcp-oauth`: browser sign-in through Circleback's dynamic client
|
||||
registration. The connection acts as the user who signs in.
|
||||
|
||||
Circleback documents no API key for its MCP server, so there is no key
|
||||
method.
|
||||
|
||||
This curated connection is the preferred route for Circleback. Composio also
|
||||
lists a Circleback toolkit (`circleback_mcp`), but it exposes only read tools
|
||||
and none of the meeting-card tools. Connection search returns the built-in
|
||||
connection for Circleback requests and does not offer the Composio route
|
||||
beside it (see [Connection search](./CONNECTION-SEARCH.md)). The same URL can
|
||||
also be connected from **Connect your own MCP server**; see
|
||||
[Connecting any remote MCP server](./GENERIC-REMOTE-MCP.md).
|
||||
|
||||
## Service involvement
|
||||
|
||||
Circleback hosts the MCP resource and the authorization server. Paperclip
|
||||
stores the OAuth tokens as secret references, discovers tools with
|
||||
`tools/list`, and sends the token on every governed call. Neither Paperclip ID
|
||||
nor Paperclip Connect participates: dynamic client registration is
|
||||
instance-local, and cloud and self-hosted instances use the same path.
|
||||
|
||||
## Connection flow
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Op as Operator browser
|
||||
participant PC as Paperclip instance
|
||||
participant CB as circleback.ai
|
||||
Op->>PC: Apps, Circleback, Continue to Circleback
|
||||
PC->>CB: POST /api/mcp without a token
|
||||
CB-->>PC: 401 with resource_metadata
|
||||
PC->>CB: GET /.well-known/oauth-protected-resource/api/mcp
|
||||
PC->>CB: GET /.well-known/oauth-authorization-server
|
||||
PC->>CB: POST /api/oauth/register (public client, Paperclip callback)
|
||||
CB-->>PC: client_id
|
||||
PC-->>Op: Redirect to /api/oauth/authorize (PKCE S256, scope user user:write)
|
||||
Op->>CB: Sign in and approve
|
||||
CB-->>Op: Redirect to /api/tools/oauth/callback with code
|
||||
Op->>PC: Callback
|
||||
PC->>CB: POST /api/oauth/access-token (code, verifier, resource)
|
||||
CB-->>PC: Access and refresh tokens
|
||||
PC->>CB: tools/list
|
||||
PC-->>Op: Permissions screen
|
||||
```
|
||||
|
||||
## Endpoints
|
||||
|
||||
| Purpose | URL |
|
||||
| --- | --- |
|
||||
| MCP resource | `https://circleback.ai/api/mcp` |
|
||||
| Protected-resource metadata | `https://circleback.ai/.well-known/oauth-protected-resource/api/mcp` |
|
||||
| Authorization-server metadata | `https://circleback.ai/.well-known/oauth-authorization-server` |
|
||||
| Authorize | `https://circleback.ai/api/oauth/authorize` |
|
||||
| Token | `https://circleback.ai/api/oauth/access-token` |
|
||||
| Dynamic client registration | `https://circleback.ai/api/oauth/register` |
|
||||
| Paperclip callback | `/api/tools/oauth/callback` |
|
||||
|
||||
`app.circleback.ai` serves the same paths with its own issuer and resource
|
||||
(`https://app.circleback.ai/api/mcp`). The definition uses the documented
|
||||
`circleback.ai` host; both hosts are in `urlPatterns`, so a pasted URL on
|
||||
either host opens this connection.
|
||||
|
||||
The authorization server supports `authorization_code` and `refresh_token`,
|
||||
PKCE `S256`, public clients (`token_endpoint_auth_method: none`), and Client ID
|
||||
Metadata Documents. Redirect constraint: `https-or-loopback-http`.
|
||||
|
||||
## Scopes
|
||||
|
||||
Paperclip requests `user user:write`, Circleback's documented default and the
|
||||
scope its unauthenticated 401 challenge names. `user` alone is read-only;
|
||||
write tools then return an error asking the user to reconnect with write
|
||||
access. This is recorded as an explicit review in
|
||||
[`tool-method-permission-reviews.json`](./tool-method-permission-reviews.json).
|
||||
|
||||
## Administrator setup
|
||||
|
||||
Nothing needs to be registered: Paperclip registers its own public client the
|
||||
first time someone connects. The instance needs an HTTPS or loopback origin.
|
||||
|
||||
1. In Paperclip, open **Apps → Browse → Circleback** and click
|
||||
**Continue to Circleback**. The screen lists the sharing warning first.
|
||||
2. Sign in to Circleback and approve access.
|
||||
3. On the connection's **Permissions** screen, set the share and delete
|
||||
actions to **Ask first** or **Off** if agents run unattended.
|
||||
|
||||
To verify, run a read action such as `SearchMeetings` from its **Test** button.
|
||||
To disconnect, remove the connection in Paperclip.
|
||||
|
||||
## Capabilities and policy
|
||||
|
||||
Circleback documents these tools (checked against a live connection on
|
||||
2026-11-12):
|
||||
|
||||
| Group | Tools | Risk |
|
||||
| --- | --- | --- |
|
||||
| Meetings and transcripts | `SearchMeetings`, `ReadMeetings`, `GetTranscriptsForMeetings`, `SearchTranscripts` | read |
|
||||
| Action items, calendar, email | `SearchActionItems`, `SearchCalendarEvents`, `SearchEmails` | read |
|
||||
| People, companies, workspace | `FindProfiles`, `FindCompanies`, `ListTeams`, `ListTags`, `ListFolders`, `ReadFolders`, `SearchSupportArticles` | read |
|
||||
| Meeting cards | `DisplayMeetings`, `DisplayActionItems`, `DisplayCalendarEvents` | read |
|
||||
| Edits | `CreateActionItem`, `UpdateActionItem`, `CreateTag`, `UpdateTag`, `CreateFolder`, `UpdateFolder`, `UpdateMeeting`, `UpdateCalendarEvent` | write |
|
||||
| Outward-facing | `ShareMeeting`, `ShareFolder`, `SubmitFeedback` | write |
|
||||
| Deletes | `DeleteActionItem`, `DeleteTag`, `DeleteFolder` | destructive |
|
||||
|
||||
The generic classifier reads `share` and `submit` as reads, so
|
||||
`server/src/services/connectors/circleback/risk.ts` classifies Circleback by
|
||||
exact tool name. Tools not in the list are writes until reviewed; a provider
|
||||
`destructiveHint` still wins. New tools are not quarantined, matching other
|
||||
MCP-direct catalog connections.
|
||||
|
||||
`ShareMeeting` and `ShareFolder` can share with other people, a team, the
|
||||
whole workspace, or anyone with the link, and can remove access.
|
||||
`SubmitFeedback` sends text to Circleback's team. The method warning and the
|
||||
capability description tell operators to set share and delete actions to Ask
|
||||
first.
|
||||
|
||||
### Meeting cards in chat
|
||||
|
||||
`DisplayMeetings`, `DisplayActionItems` and `DisplayCalendarEvents` render as
|
||||
interactive cards in the task chat through the MCP Apps extension
|
||||
(`io.modelcontextprotocol/ui`): meetings open in Circleback, action items form
|
||||
a checklist, and calendar events show whether Circleback joins. A change made
|
||||
from a card is a call to the matching write tool and follows that tool's
|
||||
policy. Clients without MCP Apps receive the same results as text. See
|
||||
[MCP Apps](./MCP-APPS.md).
|
||||
|
||||
## Transport and auth
|
||||
|
||||
- Transport: `mcp_remote`, Streamable HTTP.
|
||||
- OAuth: DCR (or CIMD when the instance has a public HTTPS URL), public client,
|
||||
PKCE, scopes `user user:write`. Connects as the approving user.
|
||||
- Credential owner: user-delegated; tokens stored as `company_secrets` refs.
|
||||
|
||||
## Resource filters
|
||||
|
||||
None. Circleback documents no query or header options that narrow the hosted
|
||||
server. Access is bounded by the signed-in user's Circleback permissions;
|
||||
narrow further with per-action policies.
|
||||
|
||||
## Manifest
|
||||
|
||||
| Field | Value |
|
||||
| --- | --- |
|
||||
| Slug | `circleback` |
|
||||
| Category | `productivity` |
|
||||
| Method | `mcp-oauth` (`dcr`, S3, scopes `user`, `user:write`) |
|
||||
| Server URL | `https://circleback.ai/api/mcp` |
|
||||
| URL patterns | `https://circleback.ai/*`, `https://app.circleback.ai/*` |
|
||||
| Capability profile | `write`, with the share and delete warning |
|
||||
| Console links | docs `https://circleback.ai/docs/support/platform/circleback-mcp` |
|
||||
|
||||
The definition source is
|
||||
`scripts/app-definition-overrides/circleback.json`, with the research row in
|
||||
`packages/shared/src/self-serve-mcp-research.json`. Regenerate with
|
||||
`node scripts/ingest-app-definitions.mjs --definitions-only`.
|
||||
|
||||
## Wizard path
|
||||
|
||||
`/apps/connect?source=circleback` has one automatic OAuth method, so it opens
|
||||
the direct sign-in screen. That screen repeats the method guidance and both
|
||||
warnings before **Continue to Circleback**. Successful sign-in and tool
|
||||
discovery lead to the connection's Permissions screen.
|
||||
|
||||
## Governance defaults
|
||||
|
||||
- Default profile and bindings: the standard connection profile; every
|
||||
discovered action starts Allowed under the current product default.
|
||||
- Policies: operators narrow share, delete and feedback tools to Ask first or
|
||||
Off on the Permissions screen.
|
||||
- Risk: the reviewed Circleback classifier above.
|
||||
- Quarantine rules: the shared defaults.
|
||||
|
||||
## Brand provenance
|
||||
|
||||
Circleback's site links `https://circleback.ai/logos/circleback_square.png`, a
|
||||
560×560 transparent PNG of its orange "c." mark. It is used unchanged in both
|
||||
themes. The `apple-touch-icon.png` is the same mark on an opaque white
|
||||
background, and `logos/circleback.svg` is the wide wordmark with an embedded
|
||||
bitmap, so neither was used.
|
||||
|
||||
| File | Source | SHA-256 |
|
||||
| --- | --- | --- |
|
||||
| `ui/public/brands/apps/circleback.png` (560×560) | `https://circleback.ai/logos/circleback_square.png` | `dd858dae1efd29d95d46cb3b99a9e27603d50840bf9e3bdac109eb38dc80e3ac` |
|
||||
|
||||
## Validation hook
|
||||
|
||||
- Environment: definition review on 2026-11-12 against `origin/master`; no
|
||||
Circleback account was connected to Paperclip.
|
||||
- Metadata probe: an unauthenticated `initialize` on `/api/mcp` returned HTTP
|
||||
401 with `resource_metadata` and `scope="user user:write"`; both
|
||||
`.well-known` documents returned the endpoints and scopes above, on both
|
||||
`circleback.ai` and `app.circleback.ai`.
|
||||
- Deterministic tests: manifest shape, store visibility, artwork, URL
|
||||
recognition on both hosts, reviewed scopes, the direct sign-in screen with
|
||||
its warnings, risk classification, Browse showing one native card in place
|
||||
of the Composio listing, and connection search preferring the built-in
|
||||
connection.
|
||||
- Connect evidence, catalog evidence, allowed read, governed write, denied
|
||||
case, revoke, audit: not run. The connection still needs the full live
|
||||
lifecycle with a Circleback account before it is considered qualified.
|
||||
@@ -50,7 +50,9 @@ queries to a provider. Broad provider descriptions are not evidence of support.
|
||||
Configured connection metadata remains scoped to the current company and
|
||||
identity. Archived and unauthorized catalogs cannot establish an aggregator route.
|
||||
|
||||
Built-in connections remain preferred for the same app. Existing AI access is
|
||||
Built-in connections remain preferred for the same app. An aggregator listing
|
||||
counts as the same app when its name or any alias matches the built-in name, so
|
||||
Composio's "Circleback MCP" does not appear beside built-in Circleback. Existing AI access is
|
||||
checked through the agent's AI binding and credential selection. An aggregator route still requires a
|
||||
saved provider choice or a verified explicit user request. Fuzzy retrieval never
|
||||
grants consent. A provider connection is not proof that its underlying app is
|
||||
@@ -71,7 +73,7 @@ pnpm exec vitest run packages/shared/src/connection-search.test.ts packages/shar
|
||||
|
||||
The database suite covers the original AgentMail sentence, split names, typos,
|
||||
capability overlap, multiple services, AI discovery, experimental gating,
|
||||
Circleback/Attio/ClickUp, indexed Executor tools, and provider consent. The native
|
||||
Otter.ai/Fathom/Attio/ClickUp, built-in Circleback over its Composio listing, indexed Executor tools, and provider consent. The native
|
||||
tool authority test searches a paragraph longer than the old 200-character limit
|
||||
and then creates a real connection interaction. Existing tests retain checks for
|
||||
private metadata, administrative denials, stale identities, and saved declines.
|
||||
|
||||
@@ -12,7 +12,8 @@ ledger; the counts above are not restated. Later additions: [Neon](./NEON.md)
|
||||
(`mcp-api-key`; 2026-10-06), [Gauge](./GAUGE.md)
|
||||
(`mcp-oauth`, `mcp-api-key`; 2026-10-08), [Ditto](./DITTO.md)
|
||||
(`mcp-oauth`, `mcp-api-key`; 2026-10-10), [Unikraft](./UNIKRAFT.md)
|
||||
(`api-token`; 2026-10-15).
|
||||
(`api-token`; 2026-10-15), [Circleback](./CIRCLEBACK.md)
|
||||
(`mcp-oauth`; 2026-11-12).
|
||||
|
||||
## Shared credential failure
|
||||
|
||||
|
||||
@@ -0,0 +1,113 @@
|
||||
# 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](./CIRCLEBACK.md): `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](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx)
|
||||
([overview](https://modelcontextprotocol.io/docs/extensions/apps)).
|
||||
- Extension id: `io.modelcontextprotocol/ui`.
|
||||
- Other hosts: Claude, Claude Desktop, Claude Code, VS Code Copilot, Goose and Postman.
|
||||
|
||||
The protocol works like this:
|
||||
|
||||
1. **The tool declares a view.** The tool's `_meta.ui.resourceUri` names a
|
||||
`ui://` resource. `_meta.ui.visibility` lists 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"]`.
|
||||
2. **The resource is an HTML document.** `resources/read` returns it with the
|
||||
mime type `text/html;profile=mcp-app`. The resource's `_meta.ui` can also
|
||||
carry:
|
||||
- `csp.connectDomains`, `resourceDomains`, `frameDomains` and `baseUriDomains`;
|
||||
- `permissions`;
|
||||
- `prefersBorder`.
|
||||
3. **The host renders the view in a sandboxed iframe.** The host and view then
|
||||
talk JSON-RPC over `postMessage`:
|
||||
1. The view sends `ui/initialize` and the host answers with its capabilities
|
||||
and host context: theme, style variables, locale, size limits and tool info.
|
||||
2. The view sends `ui/notifications/initialized`.
|
||||
3. The host sends `ui/notifications/tool-input` and then
|
||||
`ui/notifications/tool-result`, which carries the full `CallToolResult`,
|
||||
including `structuredContent` and `_meta`.
|
||||
4. After that, the view may send `ui/notifications/size-changed`,
|
||||
`tools/call`, `ui/open-link`, `ui/update-model-context` and `ping`.
|
||||
5. Before removing the iframe, the host sends `ui/resource-teardown`.
|
||||
|
||||
## Composio and other aggregators
|
||||
|
||||
The [Composio Circleback toolkit](https://docs.composio.dev/toolkits/circleback_mcp)
|
||||
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](./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 <app>" label. 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` |
|
||||
|
||||
### 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-src` and `frame-src` are `'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-link` opens only `http(s)` URLs, in a new tab without an opener.
|
||||
- `ui/message` is refused (method not found), because posting to the task on
|
||||
the user's behalf needs its own consent flow.
|
||||
- `ui/update-model-context` is accepted but not yet sent to the agent.
|
||||
- Display mode is always `inline`.
|
||||
|
||||
## 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. 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. | `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, and a tool call that needs approval. 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
|
||||
|
||||
- Only `inline` display mode is supported. There is no fullscreen or
|
||||
picture-in-picture yet.
|
||||
- A view's `ui/message` and `ui/update-model-context` do not reach the agent yet.
|
||||
- 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.
|
||||
@@ -17,7 +17,7 @@ Runtime authentication: [AI Connections](./AI-CONNECTIONS.md).
|
||||
Long-term memory: [Experimental memory connectors](./MEMORY.md).
|
||||
|
||||
Provider notes: [Google Workspace](./GOOGLE-WORKSPACE.md),
|
||||
[Gmail](./GMAIL.md), [Asana](./ASANA.md), [Sentry](./SENTRY.md), [PostHog](./POSTHOG.md), [Braintrust](./BRAINTRUST.md), [Neon](./NEON.md), [Superagent](./SUPERAGENT.md), [Gauge](./GAUGE.md), [Ditto](./DITTO.md),
|
||||
[Gmail](./GMAIL.md), [Asana](./ASANA.md), [Sentry](./SENTRY.md), [PostHog](./POSTHOG.md), [Braintrust](./BRAINTRUST.md), [Neon](./NEON.md), [Superagent](./SUPERAGENT.md), [Gauge](./GAUGE.md), [Ditto](./DITTO.md), [Circleback](./CIRCLEBACK.md),
|
||||
[1Password](./1PASSWORD.md), [Unikraft](./UNIKRAFT.md), [AgentMail](./AGENTMAIL.md), [Telem.AI](./TELEM.md), [iMessage Photon](./IMESSAGE-PHOTON.md),
|
||||
[Enterpret](./ENTERPRET.md), [Supabase](./SUPABASE.md), and
|
||||
[Vercel](./vercel.md). Optional credential custody:
|
||||
|
||||
@@ -614,6 +614,26 @@
|
||||
"liveProof": "not-run",
|
||||
"keyPermissions": "Use an API key for an account with write access to the meetings your agents need to share, rename, move or turn into soundbites. Paperclip cannot increase the key\u2019s permissions."
|
||||
},
|
||||
{
|
||||
"app": "circleback",
|
||||
"method": "mcp-oauth",
|
||||
"auth": "oauth",
|
||||
"policy": "explicit",
|
||||
"requestedScopes": [
|
||||
"user",
|
||||
"user:write"
|
||||
],
|
||||
"capability": "write",
|
||||
"supportedActions": "Search and read meetings, notes, transcripts, action items, calendar events, connected email threads, people and company profiles, tags, folders, teams and support articles; show meetings, action items and calendar events as MCP Apps cards; create, update and delete action items, tags and folders; update meeting notes, tags and folders and upcoming calendar events' private notes and tags; share meetings and folders with people, teams, the workspace or anyone with the link, or remove access; send feedback to Circleback. Access is bounded by the signed-in user's Circleback permissions.",
|
||||
"evidence": [
|
||||
"https://circleback.ai/docs/support/platform/circleback-mcp",
|
||||
"https://circleback.ai/.well-known/oauth-protected-resource/api/mcp",
|
||||
"https://circleback.ai/.well-known/oauth-authorization-server"
|
||||
],
|
||||
"reviewedAt": "2026-11-12",
|
||||
"liveProof": "not-run",
|
||||
"evidenceLimit": "Public metadata and the provider's tool reference only. Circleback documents scope=user user:write as its default grant and scope=user as read-only; write tools then fail and ask the user to reconnect. The unauthenticated 401 challenge also names scope=\"user user:write\". No Paperclip account connection, discovery, governed write or revocation was run."
|
||||
},
|
||||
{
|
||||
"app": "gauge",
|
||||
"method": "mcp-oauth",
|
||||
|
||||
Reference in new issue
Block a user