From 8ff45c0fa90cb8a7beeb2b919bd0cd4364b05a9d Mon Sep 17 00:00:00 2001
From: Dotta <34892728+cryppadotta@users.noreply.github.com>
Date: Thu, 12 Nov 2026 13:28:05 -0600
Subject: [PATCH] feat(connections): render MCP Apps views in the task chat,
starting with Circleback (#21119)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
## 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
---
doc/connections/CIRCLEBACK.md | 218 +++++++++++
doc/connections/CONNECTION-SEARCH.md | 6 +-
doc/connections/CONNECTOR-PERMISSION-AUDIT.md | 3 +-
doc/connections/MCP-APPS.md | 113 ++++++
doc/connections/README.md | 2 +-
.../tool-method-permission-reviews.json | 20 +
.../src/migrations/0473_elite_kat_farrell.sql | 29 ++
...{0468_snapshot.json => 0473_snapshot.json} | 370 +++++++++++++++++-
packages/db/src/migrations/meta/_journal.json | 7 +
packages/db/src/schema/index.ts | 1 +
packages/db/src/schema/tool_access.ts | 34 ++
.../shared/src/app-definitions-url.test.ts | 2 +
.../shared/src/app-definitions.generated.ts | 53 +--
packages/shared/src/app-definitions.test.ts | 41 +-
.../src/app-definitions/circleback.json | 52 +++
packages/shared/src/index.ts | 1 +
packages/shared/src/mcp-apps.test.ts | 92 +++++
packages/shared/src/mcp-apps.ts | 223 +++++++++++
.../shared/src/self-serve-mcp-research.json | 3 +-
packages/shared/src/types/tool-access.ts | 3 +
.../app-definition-overrides/circleback.json | 52 +++
.../connection-aggregator-fallback.test.ts | 30 +-
.../__tests__/connector-tool-policy.test.ts | 23 ++
server/src/__tests__/mcp-apps.test.ts | 365 +++++++++++++++++
server/src/__tests__/openapi-routes.test.ts | 1 +
server/src/__tests__/tool-gateway.test.ts | 2 +-
server/src/app.ts | 2 +
server/src/routes/mcp-apps.ts | 92 +++++
server/src/routes/openapi.ts | 16 +
server/src/routes/tool-access.ts | 55 ++-
server/src/routes/tool-gateway.ts | 4 +-
server/src/services/connection-intents.ts | 5 +-
.../services/connectors/circleback/risk.ts | 45 +++
server/src/services/connectors/tool-policy.ts | 4 +
server/src/services/mcp-app-views.ts | 128 ++++++
server/src/services/mcp-http.ts | 4 +-
.../tool-access/catalog/descriptors.ts | 4 +
.../tool-access/catalog/publication.ts | 4 +-
server/src/services/tool-gateway.ts | 259 ++++++++++--
.../runner-e2e/source-sdk-public-inputs.json | 15 +-
ui/public/brands/apps/circleback.png | Bin 0 -> 9887 bytes
ui/public/brands/apps/manifest.json | 6 +
ui/src/api/mcpApps.ts | 12 +
ui/src/components/TaskChatThread.tsx | 5 +
.../components/mcp-app/McpAppFrame.test.tsx | 109 ++++++
ui/src/components/mcp-app/McpAppFrame.tsx | 145 +++++++
.../mcp-app/McpAppIssueContext.test.tsx | 100 +++++
.../components/mcp-app/McpAppIssueContext.tsx | 73 ++++
.../mcp-app/McpAppTurnViews.test.tsx | 79 ++++
ui/src/components/mcp-app/McpAppTurnViews.tsx | 98 +++++
ui/src/components/mcp-app/McpAppView.test.tsx | 45 +++
ui/src/components/mcp-app/McpAppView.tsx | 84 ++++
.../components/mcp-app/mcp-app-host.test.ts | 163 ++++++++
ui/src/components/mcp-app/mcp-app-host.ts | 241 ++++++++++++
.../mcp-app/mcp-app-matching.test.ts | 45 +++
ui/src/components/mcp-app/mcp-app-matching.ts | 32 ++
.../task-chat/TaskChatRunnerTurn.tsx | 2 +
.../task-chat/TaskChatThreadView.tsx | 10 +-
.../components/task-chat/task-chat-adapter.ts | 1 +
.../components/task-chat/task-chat-model.ts | 2 +
.../connections/ConnectionSetupFlow.tsx | 7 +-
ui/src/lib/app-gallery-copy.ts | 4 +
ui/src/lib/queryKeys.ts | 4 +
ui/src/pages/apps/AppsConnect.test.tsx | 19 +
ui/src/pages/apps/Browse.test.tsx | 104 ++---
.../tasks/task-chat-mcp-app.stories.tsx | 93 +++++
ui/storybook/support/mcp-app/fixtures.ts | 133 +++++++
67 files changed, 3865 insertions(+), 134 deletions(-)
create mode 100644 doc/connections/CIRCLEBACK.md
create mode 100644 doc/connections/MCP-APPS.md
create mode 100644 packages/db/src/migrations/0473_elite_kat_farrell.sql
rename packages/db/src/migrations/meta/{0468_snapshot.json => 0473_snapshot.json} (99%)
create mode 100644 packages/shared/src/app-definitions/circleback.json
create mode 100644 packages/shared/src/mcp-apps.test.ts
create mode 100644 packages/shared/src/mcp-apps.ts
create mode 100644 scripts/app-definition-overrides/circleback.json
create mode 100644 server/src/__tests__/mcp-apps.test.ts
create mode 100644 server/src/routes/mcp-apps.ts
create mode 100644 server/src/services/connectors/circleback/risk.ts
create mode 100644 server/src/services/mcp-app-views.ts
create mode 100644 ui/public/brands/apps/circleback.png
create mode 100644 ui/src/api/mcpApps.ts
create mode 100644 ui/src/components/mcp-app/McpAppFrame.test.tsx
create mode 100644 ui/src/components/mcp-app/McpAppFrame.tsx
create mode 100644 ui/src/components/mcp-app/McpAppIssueContext.test.tsx
create mode 100644 ui/src/components/mcp-app/McpAppIssueContext.tsx
create mode 100644 ui/src/components/mcp-app/McpAppTurnViews.test.tsx
create mode 100644 ui/src/components/mcp-app/McpAppTurnViews.tsx
create mode 100644 ui/src/components/mcp-app/McpAppView.test.tsx
create mode 100644 ui/src/components/mcp-app/McpAppView.tsx
create mode 100644 ui/src/components/mcp-app/mcp-app-host.test.ts
create mode 100644 ui/src/components/mcp-app/mcp-app-host.ts
create mode 100644 ui/src/components/mcp-app/mcp-app-matching.test.ts
create mode 100644 ui/src/components/mcp-app/mcp-app-matching.ts
create mode 100644 ui/storybook/stories/tasks/task-chat-mcp-app.stories.tsx
create mode 100644 ui/storybook/support/mcp-app/fixtures.ts
diff --git a/doc/connections/CIRCLEBACK.md b/doc/connections/CIRCLEBACK.md
new file mode 100644
index 00000000000..c74ac4ea3ad
--- /dev/null
+++ b/doc/connections/CIRCLEBACK.md
@@ -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.
diff --git a/doc/connections/CONNECTION-SEARCH.md b/doc/connections/CONNECTION-SEARCH.md
index 594b10a66ec..0ae27347ea9 100644
--- a/doc/connections/CONNECTION-SEARCH.md
+++ b/doc/connections/CONNECTION-SEARCH.md
@@ -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.
diff --git a/doc/connections/CONNECTOR-PERMISSION-AUDIT.md b/doc/connections/CONNECTOR-PERMISSION-AUDIT.md
index 9c70b98e7ca..d6c5265ee4d 100644
--- a/doc/connections/CONNECTOR-PERMISSION-AUDIT.md
+++ b/doc/connections/CONNECTOR-PERMISSION-AUDIT.md
@@ -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
diff --git a/doc/connections/MCP-APPS.md b/doc/connections/MCP-APPS.md
new file mode 100644
index 00000000000..a457bf1b2bb
--- /dev/null
+++ b/doc/connections/MCP-APPS.md
@@ -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 " 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 `` 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.
diff --git a/doc/connections/README.md b/doc/connections/README.md
index ab5f12475cf..b93ec6709d2 100644
--- a/doc/connections/README.md
+++ b/doc/connections/README.md
@@ -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:
diff --git a/doc/connections/tool-method-permission-reviews.json b/doc/connections/tool-method-permission-reviews.json
index 405ad058330..9aff2b163af 100644
--- a/doc/connections/tool-method-permission-reviews.json
+++ b/doc/connections/tool-method-permission-reviews.json
@@ -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",
diff --git a/packages/db/src/migrations/0473_elite_kat_farrell.sql b/packages/db/src/migrations/0473_elite_kat_farrell.sql
new file mode 100644
index 00000000000..5bced602669
--- /dev/null
+++ b/packages/db/src/migrations/0473_elite_kat_farrell.sql
@@ -0,0 +1,29 @@
+CREATE TABLE "tool_mcp_app_views" (
+ "id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+ "company_id" uuid NOT NULL,
+ "invocation_id" uuid,
+ "issue_id" uuid,
+ "run_id" uuid,
+ "agent_id" uuid,
+ "responsible_user_id" text,
+ "connection_id" uuid NOT NULL,
+ "catalog_entry_id" uuid,
+ "application_name" text NOT NULL,
+ "tool_name" text NOT NULL,
+ "upstream_tool_name" text NOT NULL,
+ "resource_uri" text NOT NULL,
+ "tool_input" jsonb DEFAULT '{}'::jsonb NOT NULL,
+ "tool_result" jsonb NOT NULL,
+ "created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "tool_catalog_entries" ADD COLUMN "ui_meta" jsonb;--> statement-breakpoint
+ALTER TABLE "tool_mcp_app_views" ADD CONSTRAINT "tool_mcp_app_views_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "tool_mcp_app_views" ADD CONSTRAINT "tool_mcp_app_views_invocation_id_tool_invocations_id_fk" FOREIGN KEY ("invocation_id") REFERENCES "public"."tool_invocations"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "tool_mcp_app_views" ADD CONSTRAINT "tool_mcp_app_views_issue_id_issues_id_fk" FOREIGN KEY ("issue_id") REFERENCES "public"."issues"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "tool_mcp_app_views" ADD CONSTRAINT "tool_mcp_app_views_run_id_heartbeat_runs_id_fk" FOREIGN KEY ("run_id") REFERENCES "public"."heartbeat_runs"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "tool_mcp_app_views" ADD CONSTRAINT "tool_mcp_app_views_agent_id_agents_id_fk" FOREIGN KEY ("agent_id") REFERENCES "public"."agents"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "tool_mcp_app_views" ADD CONSTRAINT "tool_mcp_app_views_connection_id_tool_connections_id_fk" FOREIGN KEY ("connection_id") REFERENCES "public"."tool_connections"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "tool_mcp_app_views" ADD CONSTRAINT "tool_mcp_app_views_catalog_entry_id_tool_catalog_entries_id_fk" FOREIGN KEY ("catalog_entry_id") REFERENCES "public"."tool_catalog_entries"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "tool_mcp_app_views_issue_idx" ON "tool_mcp_app_views" USING btree ("company_id","issue_id","created_at");--> statement-breakpoint
+CREATE INDEX "tool_mcp_app_views_connection_idx" ON "tool_mcp_app_views" USING btree ("connection_id");
\ No newline at end of file
diff --git a/packages/db/src/migrations/meta/0468_snapshot.json b/packages/db/src/migrations/meta/0473_snapshot.json
similarity index 99%
rename from packages/db/src/migrations/meta/0468_snapshot.json
rename to packages/db/src/migrations/meta/0473_snapshot.json
index 899f79e1f2b..45d0244b9e7 100644
--- a/packages/db/src/migrations/meta/0468_snapshot.json
+++ b/packages/db/src/migrations/meta/0473_snapshot.json
@@ -1,6 +1,6 @@
{
- "id": "c06d4653-b3df-4e3e-bbf9-6de9b37cf806",
- "prevId": "426d1f42-0983-4c6b-bb8d-5c798eee915a",
+ "id": "f14430e8-1ebf-414a-8c89-93c32740c4e6",
+ "prevId": "77704cfc-2cbe-41de-9d2c-5225b8466646",
"version": "7",
"dialect": "postgresql",
"tables": {
@@ -1417,6 +1417,34 @@
"concurrently": false,
"method": "btree",
"with": {}
+ },
+ "activity_log_company_handled_for_created_idx": {
+ "name": "activity_log_company_handled_for_created_idx",
+ "columns": [
+ {
+ "expression": "company_id",
+ "isExpression": false,
+ "asc": true,
+ "nulls": "last"
+ },
+ {
+ "expression": "(\"details\" ->> 'handledForUserId')",
+ "asc": true,
+ "isExpression": true,
+ "nulls": "last"
+ },
+ {
+ "expression": "created_at",
+ "isExpression": false,
+ "asc": true,
+ "nulls": "last"
+ }
+ ],
+ "isUnique": false,
+ "where": "(\"activity_log\".\"details\" ->> 'handledForUserId') IS NOT NULL",
+ "concurrently": false,
+ "method": "btree",
+ "with": {}
}
},
"foreignKeys": {
@@ -16340,6 +16368,18 @@
"primaryKey": false,
"notNull": false
},
+ "default_decision_owner_user_id": {
+ "name": "default_decision_owner_user_id",
+ "type": "text",
+ "primaryKey": false,
+ "notNull": false
+ },
+ "budget_owner_user_id": {
+ "name": "budget_owner_user_id",
+ "type": "text",
+ "primaryKey": false,
+ "notNull": false
+ },
"require_board_approval_for_new_agents": {
"name": "require_board_approval_for_new_agents",
"type": "boolean",
@@ -22302,6 +22342,18 @@
"type": "timestamp with time zone",
"primaryKey": false,
"notNull": false
+ },
+ "dispatching_at": {
+ "name": "dispatching_at",
+ "type": "timestamp with time zone",
+ "primaryKey": false,
+ "notNull": false
+ },
+ "dispatch_lease_expires_at": {
+ "name": "dispatch_lease_expires_at",
+ "type": "timestamp with time zone",
+ "primaryKey": false,
+ "notNull": false
}
},
"indexes": {
@@ -35606,6 +35658,34 @@
"method": "btree",
"with": {}
},
+ "heartbeat_runs_queued_created_idx": {
+ "name": "heartbeat_runs_queued_created_idx",
+ "columns": [
+ {
+ "expression": "company_id",
+ "isExpression": false,
+ "asc": true,
+ "nulls": "last"
+ },
+ {
+ "expression": "created_at",
+ "isExpression": false,
+ "asc": true,
+ "nulls": "last"
+ },
+ {
+ "expression": "id",
+ "isExpression": false,
+ "asc": true,
+ "nulls": "last"
+ }
+ ],
+ "isUnique": false,
+ "where": "\"heartbeat_runs\".\"status\" = 'queued'",
+ "concurrently": true,
+ "method": "btree",
+ "with": {}
+ },
"heartbeat_runs_cost_accounting_pending_idx": {
"name": "heartbeat_runs_cost_accounting_pending_idx",
"columns": [
@@ -36235,6 +36315,12 @@
"primaryKey": false,
"notNull": false
},
+ "fingerprint": {
+ "name": "fingerprint",
+ "type": "text",
+ "primaryKey": false,
+ "notNull": false
+ },
"created_at": {
"name": "created_at",
"type": "timestamp with time zone",
@@ -51040,6 +51126,12 @@
"primaryKey": false,
"notNull": false
},
+ "decision_owner_user_id": {
+ "name": "decision_owner_user_id",
+ "type": "text",
+ "primaryKey": false,
+ "notNull": false
+ },
"target_date": {
"name": "target_date",
"type": "date",
@@ -53594,6 +53686,12 @@
"primaryKey": false,
"notNull": true
},
+ "pending_delete_object_key": {
+ "name": "pending_delete_object_key",
+ "type": "text",
+ "primaryKey": false,
+ "notNull": false
+ },
"created_at": {
"name": "created_at",
"type": "timestamp with time zone",
@@ -53617,6 +53715,21 @@
"concurrently": false,
"method": "btree",
"with": {}
+ },
+ "runner_api_response_reservations_asset_idx": {
+ "name": "runner_api_response_reservations_asset_idx",
+ "columns": [
+ {
+ "expression": "asset_id",
+ "isExpression": false,
+ "asc": true,
+ "nulls": "last"
+ }
+ ],
+ "isUnique": false,
+ "concurrently": false,
+ "method": "btree",
+ "with": {}
}
},
"foreignKeys": {
@@ -57422,6 +57535,12 @@
"notNull": true,
"default": "'{}'::jsonb"
},
+ "ui_meta": {
+ "name": "ui_meta",
+ "type": "jsonb",
+ "primaryKey": false,
+ "notNull": false
+ },
"risk_level": {
"name": "risk_level",
"type": "text",
@@ -59547,6 +59666,253 @@
"checkConstraints": {},
"isRLSEnabled": false
},
+ "public.tool_mcp_app_views": {
+ "name": "tool_mcp_app_views",
+ "schema": "",
+ "columns": {
+ "id": {
+ "name": "id",
+ "type": "uuid",
+ "primaryKey": true,
+ "notNull": true,
+ "default": "gen_random_uuid()"
+ },
+ "company_id": {
+ "name": "company_id",
+ "type": "uuid",
+ "primaryKey": false,
+ "notNull": true
+ },
+ "invocation_id": {
+ "name": "invocation_id",
+ "type": "uuid",
+ "primaryKey": false,
+ "notNull": false
+ },
+ "issue_id": {
+ "name": "issue_id",
+ "type": "uuid",
+ "primaryKey": false,
+ "notNull": false
+ },
+ "run_id": {
+ "name": "run_id",
+ "type": "uuid",
+ "primaryKey": false,
+ "notNull": false
+ },
+ "agent_id": {
+ "name": "agent_id",
+ "type": "uuid",
+ "primaryKey": false,
+ "notNull": false
+ },
+ "responsible_user_id": {
+ "name": "responsible_user_id",
+ "type": "text",
+ "primaryKey": false,
+ "notNull": false
+ },
+ "connection_id": {
+ "name": "connection_id",
+ "type": "uuid",
+ "primaryKey": false,
+ "notNull": true
+ },
+ "catalog_entry_id": {
+ "name": "catalog_entry_id",
+ "type": "uuid",
+ "primaryKey": false,
+ "notNull": false
+ },
+ "application_name": {
+ "name": "application_name",
+ "type": "text",
+ "primaryKey": false,
+ "notNull": true
+ },
+ "tool_name": {
+ "name": "tool_name",
+ "type": "text",
+ "primaryKey": false,
+ "notNull": true
+ },
+ "upstream_tool_name": {
+ "name": "upstream_tool_name",
+ "type": "text",
+ "primaryKey": false,
+ "notNull": true
+ },
+ "resource_uri": {
+ "name": "resource_uri",
+ "type": "text",
+ "primaryKey": false,
+ "notNull": true
+ },
+ "tool_input": {
+ "name": "tool_input",
+ "type": "jsonb",
+ "primaryKey": false,
+ "notNull": true,
+ "default": "'{}'::jsonb"
+ },
+ "tool_result": {
+ "name": "tool_result",
+ "type": "jsonb",
+ "primaryKey": false,
+ "notNull": true
+ },
+ "created_at": {
+ "name": "created_at",
+ "type": "timestamp with time zone",
+ "primaryKey": false,
+ "notNull": true,
+ "default": "now()"
+ }
+ },
+ "indexes": {
+ "tool_mcp_app_views_issue_idx": {
+ "name": "tool_mcp_app_views_issue_idx",
+ "columns": [
+ {
+ "expression": "company_id",
+ "isExpression": false,
+ "asc": true,
+ "nulls": "last"
+ },
+ {
+ "expression": "issue_id",
+ "isExpression": false,
+ "asc": true,
+ "nulls": "last"
+ },
+ {
+ "expression": "created_at",
+ "isExpression": false,
+ "asc": true,
+ "nulls": "last"
+ }
+ ],
+ "isUnique": false,
+ "concurrently": false,
+ "method": "btree",
+ "with": {}
+ },
+ "tool_mcp_app_views_connection_idx": {
+ "name": "tool_mcp_app_views_connection_idx",
+ "columns": [
+ {
+ "expression": "connection_id",
+ "isExpression": false,
+ "asc": true,
+ "nulls": "last"
+ }
+ ],
+ "isUnique": false,
+ "concurrently": false,
+ "method": "btree",
+ "with": {}
+ }
+ },
+ "foreignKeys": {
+ "tool_mcp_app_views_company_id_companies_id_fk": {
+ "name": "tool_mcp_app_views_company_id_companies_id_fk",
+ "tableFrom": "tool_mcp_app_views",
+ "tableTo": "companies",
+ "columnsFrom": [
+ "company_id"
+ ],
+ "columnsTo": [
+ "id"
+ ],
+ "onDelete": "cascade",
+ "onUpdate": "no action"
+ },
+ "tool_mcp_app_views_invocation_id_tool_invocations_id_fk": {
+ "name": "tool_mcp_app_views_invocation_id_tool_invocations_id_fk",
+ "tableFrom": "tool_mcp_app_views",
+ "tableTo": "tool_invocations",
+ "columnsFrom": [
+ "invocation_id"
+ ],
+ "columnsTo": [
+ "id"
+ ],
+ "onDelete": "set null",
+ "onUpdate": "no action"
+ },
+ "tool_mcp_app_views_issue_id_issues_id_fk": {
+ "name": "tool_mcp_app_views_issue_id_issues_id_fk",
+ "tableFrom": "tool_mcp_app_views",
+ "tableTo": "issues",
+ "columnsFrom": [
+ "issue_id"
+ ],
+ "columnsTo": [
+ "id"
+ ],
+ "onDelete": "cascade",
+ "onUpdate": "no action"
+ },
+ "tool_mcp_app_views_run_id_heartbeat_runs_id_fk": {
+ "name": "tool_mcp_app_views_run_id_heartbeat_runs_id_fk",
+ "tableFrom": "tool_mcp_app_views",
+ "tableTo": "heartbeat_runs",
+ "columnsFrom": [
+ "run_id"
+ ],
+ "columnsTo": [
+ "id"
+ ],
+ "onDelete": "set null",
+ "onUpdate": "no action"
+ },
+ "tool_mcp_app_views_agent_id_agents_id_fk": {
+ "name": "tool_mcp_app_views_agent_id_agents_id_fk",
+ "tableFrom": "tool_mcp_app_views",
+ "tableTo": "agents",
+ "columnsFrom": [
+ "agent_id"
+ ],
+ "columnsTo": [
+ "id"
+ ],
+ "onDelete": "set null",
+ "onUpdate": "no action"
+ },
+ "tool_mcp_app_views_connection_id_tool_connections_id_fk": {
+ "name": "tool_mcp_app_views_connection_id_tool_connections_id_fk",
+ "tableFrom": "tool_mcp_app_views",
+ "tableTo": "tool_connections",
+ "columnsFrom": [
+ "connection_id"
+ ],
+ "columnsTo": [
+ "id"
+ ],
+ "onDelete": "cascade",
+ "onUpdate": "no action"
+ },
+ "tool_mcp_app_views_catalog_entry_id_tool_catalog_entries_id_fk": {
+ "name": "tool_mcp_app_views_catalog_entry_id_tool_catalog_entries_id_fk",
+ "tableFrom": "tool_mcp_app_views",
+ "tableTo": "tool_catalog_entries",
+ "columnsFrom": [
+ "catalog_entry_id"
+ ],
+ "columnsTo": [
+ "id"
+ ],
+ "onDelete": "set null",
+ "onUpdate": "no action"
+ }
+ },
+ "compositePrimaryKeys": {},
+ "uniqueConstraints": {},
+ "policies": {},
+ "checkConstraints": {},
+ "isRLSEnabled": false
+ },
"public.tool_mcp_gateway_tokens": {
"name": "tool_mcp_gateway_tokens",
"schema": "",
diff --git a/packages/db/src/migrations/meta/_journal.json b/packages/db/src/migrations/meta/_journal.json
index 7238172ae7a..c9b59045d74 100644
--- a/packages/db/src/migrations/meta/_journal.json
+++ b/packages/db/src/migrations/meta/_journal.json
@@ -3298,6 +3298,13 @@
"when": 1794503924304,
"tag": "0472_runner_api_capture_pending_deletes",
"breakpoints": true
+ },
+ {
+ "idx": 473,
+ "version": "7",
+ "when": 1794508336827,
+ "tag": "0473_elite_kat_farrell",
+ "breakpoints": true
}
]
}
\ No newline at end of file
diff --git a/packages/db/src/schema/index.ts b/packages/db/src/schema/index.ts
index 7812dfde547..e189d96a0de 100644
--- a/packages/db/src/schema/index.ts
+++ b/packages/db/src/schema/index.ts
@@ -190,6 +190,7 @@ export {
toolGatewaySessions,
connectionTokenIssuances,
toolInvocations,
+ toolMcpAppViews,
toolActionRequests,
toolCallEvents,
toolRateLimitCounters,
diff --git a/packages/db/src/schema/tool_access.ts b/packages/db/src/schema/tool_access.ts
index 9fe6662d314..968795a13d0 100644
--- a/packages/db/src/schema/tool_access.ts
+++ b/packages/db/src/schema/tool_access.ts
@@ -19,6 +19,7 @@ import type {
ConnectionAgentInstructions,
ConnectionTokenIssuanceOutcome,
ConnectionTokenIssuancePath,
+ McpAppToolUi,
McpConnectionCredentialRef,
ToolActionRequestStatus,
ToolApplicationStatus,
@@ -382,6 +383,8 @@ export const toolCatalogEntries = pgTable(
inputSchema: jsonb("input_schema").$type>().notNull().default({}),
outputSchema: jsonb("output_schema").$type>(),
annotations: jsonb("annotations").$type>().notNull().default({}),
+ /** Normalized MCP Apps `_meta.ui` declaration (`ui://` view), when the tool has one. */
+ uiMeta: jsonb("ui_meta").$type(),
riskLevel: text("risk_level").$type().notNull().default("read"),
isReadOnly: boolean("is_read_only").notNull().default(true),
isWrite: boolean("is_write").notNull().default(false),
@@ -809,6 +812,37 @@ export const toolInvocations = pgTable(
],
);
+/**
+ * One completed call to a tool that declares an MCP Apps view. Holds what the
+ * task chat needs to render the view: the call's arguments and its redacted
+ * result. The view document itself is read from the connection on demand.
+ */
+export const toolMcpAppViews = pgTable(
+ "tool_mcp_app_views",
+ {
+ id: uuid("id").primaryKey().defaultRandom(),
+ companyId: uuid("company_id").notNull().references(() => companies.id, { onDelete: "cascade" }),
+ invocationId: uuid("invocation_id").references(() => toolInvocations.id, { onDelete: "set null" }),
+ issueId: uuid("issue_id").references(() => issues.id, { onDelete: "cascade" }),
+ runId: uuid("run_id").references(() => heartbeatRuns.id, { onDelete: "set null" }),
+ agentId: uuid("agent_id").references(() => agents.id, { onDelete: "set null" }),
+ responsibleUserId: text("responsible_user_id"),
+ connectionId: uuid("connection_id").notNull().references(() => toolConnections.id, { onDelete: "cascade" }),
+ catalogEntryId: uuid("catalog_entry_id").references(() => toolCatalogEntries.id, { onDelete: "set null" }),
+ applicationName: text("application_name").notNull(),
+ toolName: text("tool_name").notNull(),
+ upstreamToolName: text("upstream_tool_name").notNull(),
+ resourceUri: text("resource_uri").notNull(),
+ toolInput: jsonb("tool_input").$type>().notNull().default({}),
+ toolResult: jsonb("tool_result").$type>().notNull(),
+ createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+ },
+ (table) => [
+ index("tool_mcp_app_views_issue_idx").on(table.companyId, table.issueId, table.createdAt),
+ index("tool_mcp_app_views_connection_idx").on(table.connectionId),
+ ],
+);
+
export const toolActionRequests = pgTable(
"tool_action_requests",
{
diff --git a/packages/shared/src/app-definitions-url.test.ts b/packages/shared/src/app-definitions-url.test.ts
index 7378d29fd84..56792d6745a 100644
--- a/packages/shared/src/app-definitions-url.test.ts
+++ b/packages/shared/src/app-definitions-url.test.ts
@@ -14,6 +14,8 @@ describe("tool app gallery URL matching", () => {
expect(getAppDefinitionForUrl("https://workspace.google.com/")?.slug).toBe("google-workspace");
expect(getAppDefinitionForUrl("https://mcp.neon.tech/mcp")?.slug).toBe("neon");
expect(getAppDefinitionForUrl("https://app.withgauge.com/mcp")?.slug).toBe("gauge");
+ expect(getAppDefinitionForUrl("https://circleback.ai/api/mcp")?.slug).toBe("circleback");
+ expect(getAppDefinitionForUrl("https://app.circleback.ai/api/mcp")?.slug).toBe("circleback");
expect(getAppDefinitionForUrl("https://api.dittowords.com/v2/mcp")?.slug).toBe("ditto");
expect(getAppDefinitionForUrl("https://www.superagent.sh/mcp")?.slug).toBe("superagent");
});
diff --git a/packages/shared/src/app-definitions.generated.ts b/packages/shared/src/app-definitions.generated.ts
index d74319a5c96..e314e97d3b5 100644
--- a/packages/shared/src/app-definitions.generated.ts
+++ b/packages/shared/src/app-definitions.generated.ts
@@ -83,30 +83,31 @@ import a81 from "./app-definitions/clickup.json" with { type: "json" };
import a82 from "./app-definitions/klaviyo.json" with { type: "json" };
import a83 from "./app-definitions/ditto.json" with { type: "json" };
import a84 from "./app-definitions/braintrust.json" with { type: "json" };
-import a85 from "./app-definitions/google-workspace.json" with { type: "json" };
-import a86 from "./app-definitions/gmail.json" with { type: "json" };
-import a87 from "./app-definitions/google-drive.json" with { type: "json" };
-import a88 from "./app-definitions/google-docs.json" with { type: "json" };
-import a89 from "./app-definitions/google-sheets.json" with { type: "json" };
-import a90 from "./app-definitions/google-slides.json" with { type: "json" };
-import a91 from "./app-definitions/google-calendar.json" with { type: "json" };
-import a92 from "./app-definitions/google-chat.json" with { type: "json" };
-import a93 from "./app-definitions/google-people.json" with { type: "json" };
-import a94 from "./app-definitions/google-workspace-search.json" with { type: "json" };
-import a95 from "./app-definitions/openai.json" with { type: "json" };
-import a96 from "./app-definitions/openrouter.json" with { type: "json" };
-import a97 from "./app-definitions/xai.json" with { type: "json" };
-import a98 from "./app-definitions/google.json" with { type: "json" };
-import a99 from "./app-definitions/bedrock.json" with { type: "json" };
-import a100 from "./app-definitions/responses-api.json" with { type: "json" };
-import a101 from "./app-definitions/messages-api.json" with { type: "json" };
-import a102 from "./app-definitions/chat-completions-api.json" with { type: "json" };
-import a103 from "./app-definitions/local.json" with { type: "json" };
-import a104 from "./app-definitions/1password.json" with { type: "json" };
-import a105 from "./app-definitions/daytona.json" with { type: "json" };
-import a106 from "./app-definitions/monday.json" with { type: "json" };
-import a107 from "./app-definitions/paperclip-notebook.json" with { type: "json" };
-import a108 from "./app-definitions/unikraft.json" with { type: "json" };
-import a109 from "./app-definitions/speko.json" with { type: "json" };
+import a85 from "./app-definitions/circleback.json" with { type: "json" };
+import a86 from "./app-definitions/google-workspace.json" with { type: "json" };
+import a87 from "./app-definitions/gmail.json" with { type: "json" };
+import a88 from "./app-definitions/google-drive.json" with { type: "json" };
+import a89 from "./app-definitions/google-docs.json" with { type: "json" };
+import a90 from "./app-definitions/google-sheets.json" with { type: "json" };
+import a91 from "./app-definitions/google-slides.json" with { type: "json" };
+import a92 from "./app-definitions/google-calendar.json" with { type: "json" };
+import a93 from "./app-definitions/google-chat.json" with { type: "json" };
+import a94 from "./app-definitions/google-people.json" with { type: "json" };
+import a95 from "./app-definitions/google-workspace-search.json" with { type: "json" };
+import a96 from "./app-definitions/openai.json" with { type: "json" };
+import a97 from "./app-definitions/openrouter.json" with { type: "json" };
+import a98 from "./app-definitions/xai.json" with { type: "json" };
+import a99 from "./app-definitions/google.json" with { type: "json" };
+import a100 from "./app-definitions/bedrock.json" with { type: "json" };
+import a101 from "./app-definitions/responses-api.json" with { type: "json" };
+import a102 from "./app-definitions/messages-api.json" with { type: "json" };
+import a103 from "./app-definitions/chat-completions-api.json" with { type: "json" };
+import a104 from "./app-definitions/local.json" with { type: "json" };
+import a105 from "./app-definitions/1password.json" with { type: "json" };
+import a106 from "./app-definitions/daytona.json" with { type: "json" };
+import a107 from "./app-definitions/monday.json" with { type: "json" };
+import a108 from "./app-definitions/paperclip-notebook.json" with { type: "json" };
+import a109 from "./app-definitions/unikraft.json" with { type: "json" };
+import a110 from "./app-definitions/speko.json" with { type: "json" };
import type { AppDefinition } from "./types/app-definition.js";
-export const APP_DEFINITIONS=[a0,a1,a2,a3,a4,a5,a6,a7,a8,a9,a10,a11,a12,a13,a14,a15,a16,a17,a18,a19,a20,a21,a22,a23,a24,a25,a26,a27,a28,a29,a30,a31,a32,a33,a34,a35,a36,a37,a38,a39,a40,a41,a42,a43,a44,a45,a46,a47,a48,a49,a50,a51,a52,a53,a54,a55,a56,a57,a58,a59,a60,a61,a62,a63,a64,a65,a66,a67,a68,a69,a70,a71,a72,a73,a74,a75,a76,a77,a78,a79,a80,a81,a82,a83,a84,a85,a86,a87,a88,a89,a90,a91,a92,a93,a94,a95,a96,a97,a98,a99,a100,a101,a102,a103,a104,a105,a106,a107,a108,a109] as AppDefinition[];
+export const APP_DEFINITIONS=[a0,a1,a2,a3,a4,a5,a6,a7,a8,a9,a10,a11,a12,a13,a14,a15,a16,a17,a18,a19,a20,a21,a22,a23,a24,a25,a26,a27,a28,a29,a30,a31,a32,a33,a34,a35,a36,a37,a38,a39,a40,a41,a42,a43,a44,a45,a46,a47,a48,a49,a50,a51,a52,a53,a54,a55,a56,a57,a58,a59,a60,a61,a62,a63,a64,a65,a66,a67,a68,a69,a70,a71,a72,a73,a74,a75,a76,a77,a78,a79,a80,a81,a82,a83,a84,a85,a86,a87,a88,a89,a90,a91,a92,a93,a94,a95,a96,a97,a98,a99,a100,a101,a102,a103,a104,a105,a106,a107,a108,a109,a110] as AppDefinition[];
diff --git a/packages/shared/src/app-definitions.test.ts b/packages/shared/src/app-definitions.test.ts
index 3c048c63a6d..54cf668cf97 100644
--- a/packages/shared/src/app-definitions.test.ts
+++ b/packages/shared/src/app-definitions.test.ts
@@ -294,7 +294,7 @@ describe("AppDefinition catalog", () => {
"google-workspace-search",
]),
);
- expect(SELF_SERVE_MCP_CANDIDATES).toHaveLength(65);
+ expect(SELF_SERVE_MCP_CANDIDATES).toHaveLength(66);
expect(BLOCKED_MCP_PROVIDERS.map((entry) => entry.slug)).toEqual([
"g2",
"vercel",
@@ -460,15 +460,15 @@ describe("AppDefinition catalog", () => {
expect(channel("slack")?.guidanceMd).toContain("reactions");
expect(channel("slack")?.guidanceMd).toContain("direct messages");
});
- it("keeps a complete, unique, dated evidence ledger for all 69 researched MCP providers", () => {
+ it("keeps a complete, unique, dated evidence ledger for all 70 researched MCP providers", () => {
// Ledger-wide date reflects the last full re-verification (2026-08-26);
// later provider additions carry their own research evidence, but
// bumping the shared date would overstate freshness for the other providers.
expect(SELF_SERVE_MCP_RESEARCH.verifiedAt).toBe("2026-08-26");
- expect(SELF_SERVE_MCP_RESEARCH.entries).toHaveLength(69);
+ expect(SELF_SERVE_MCP_RESEARCH.entries).toHaveLength(70);
expect(
new Set(SELF_SERVE_MCP_RESEARCH.entries.map((entry) => entry.slug)),
- ).toHaveProperty("size", 69);
+ ).toHaveProperty("size", 70);
for (const entry of SELF_SERVE_MCP_RESEARCH.entries) {
expect(new URL(entry.docsUrl).protocol).toBe("https:");
expect(new URL(entry.serverUrl).protocol).toBe("https:");
@@ -905,7 +905,7 @@ describe("AppDefinition catalog", () => {
"ticktick",
"xero",
]);
- expect(APP_STORE_DEFINITIONS).toHaveLength(88);
+ expect(APP_STORE_DEFINITIONS).toHaveLength(89);
const connectableSlugs = new Set(
CONNECTABLE_APP_DEFINITIONS.map((entry) => entry.slug),
);
@@ -1340,6 +1340,37 @@ describe("AppDefinition catalog", () => {
]);
expect(method!.tenantFields?.[0]?.options?.map((option) => option.value)).toEqual(["dal", "fra", "sfo", "sin", "was"]);
});
+ it("connects Circleback's hosted server with browser sign-in and its documented read/write scopes", () => {
+ const circleback = APP_DEFINITIONS.find((app) => app.slug === "circleback")!;
+ expect(circleback).toMatchObject({
+ name: "Circleback",
+ categories: ["productivity"],
+ urlPatterns: ["https://circleback.ai/*", "https://app.circleback.ai/*"],
+ docsUrl: "https://circleback.ai/docs/support/platform/circleback-mcp",
+ branding: { logoUrl: "/brands/apps/circleback.png" },
+ redirectConstraints: "https-or-loopback-http",
+ });
+ expect(APP_STORE_DEFINITIONS.some((app) => app.slug === "circleback")).toBe(true);
+ expect(CONNECTABLE_APP_DEFINITIONS.some((app) => app.slug === "circleback")).toBe(true);
+ // Circleback documents no API key for its MCP server.
+ expect(circleback.methods).toHaveLength(1);
+ expect(circleback.methods[0]).toMatchObject({
+ key: "mcp-oauth",
+ label: "Sign in with Circleback",
+ transport: "mcp_remote",
+ auth: "oauth",
+ ownershipModes: ["dcr"],
+ riskTier: "S3",
+ // `user` alone is read-only; write tools then ask the user to reconnect.
+ defaults: { serverUrl: "https://circleback.ai/api/mcp", scopesHint: ["user", "user:write"] },
+ capabilityProfile: { key: "write", description: expect.stringContaining("Set share and delete actions to Ask first") },
+ });
+ expect(circleback.methods[0]!.tenantFields ?? []).toEqual([]);
+ expect(circleback.methods[0]!.warnings).toEqual([
+ expect.stringContaining("A Circleback account"),
+ expect.stringContaining("anyone with the link"),
+ ]);
+ });
it("connects Gauge's hosted server with browser sign-in or an organization API key", () => {
const gauge = APP_DEFINITIONS.find((app) => app.slug === "gauge")!;
expect(gauge).toMatchObject({
diff --git a/packages/shared/src/app-definitions/circleback.json b/packages/shared/src/app-definitions/circleback.json
new file mode 100644
index 00000000000..2b05e87c356
--- /dev/null
+++ b/packages/shared/src/app-definitions/circleback.json
@@ -0,0 +1,52 @@
+{
+ "schemaVersion": 1,
+ "slug": "circleback",
+ "name": "Circleback",
+ "description": "Search meeting notes, transcripts, action items, calendar events and emails, and show meetings as cards in chat.",
+ "categories": [
+ "productivity"
+ ],
+ "featured": false,
+ "branding": {
+ "logoUrl": "/brands/apps/circleback.png"
+ },
+ "urlPatterns": [
+ "https://circleback.ai/*",
+ "https://app.circleback.ai/*"
+ ],
+ "docsUrl": "https://circleback.ai/docs/support/platform/circleback-mcp",
+ "redirectConstraints": "https-or-loopback-http",
+ "methods": [
+ {
+ "key": "mcp-oauth",
+ "label": "Sign in with Circleback",
+ "transport": "mcp_remote",
+ "auth": "oauth",
+ "ownershipModes": [
+ "dcr"
+ ],
+ "whenToUse": "Use browser sign-in for Circleback's hosted MCP server.",
+ "defaults": {
+ "serverUrl": "https://circleback.ai/api/mcp",
+ "scopesHint": [
+ "user",
+ "user:write"
+ ]
+ },
+ "guidanceMd": "Sign in to Circleback and approve access. The connection acts as the Circleback user who signs in and sees the meetings, action items, calendar events and connected email that user can see. Write tools start enabled and remain governed by Paperclip's action policies.",
+ "warnings": [
+ "A Circleback account. The connection reads the signed-in user's meetings, transcripts, calendar and connected email.",
+ "Circleback share tools can share meetings and folders with other people or anyone with the link, and delete tools cannot be undone. Set share and delete actions to Ask first before agents run unattended."
+ ],
+ "consoleLinks": {
+ "docs": "https://circleback.ai/docs/support/platform/circleback-mcp"
+ },
+ "riskTier": "S3",
+ "capabilityProfile": {
+ "key": "write",
+ "label": "Read and write",
+ "description": "Search and read meetings, transcripts, action items, calendar events and email, and manage action items, tags, folders and meeting notes. Circleback share tools can share meetings and folders with other people or anyone with the link, and delete tools cannot be undone. Set share and delete actions to Ask first before agents run unattended."
+ }
+ }
+ ]
+}
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index 58b6dac8a1f..f9865d8aa6a 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -2961,3 +2961,4 @@ export {
issueActivityChangesTaskIdentity,
} from "./issue-activity-identity.js";
export { recognizeLinkPreview, type LinkPreviewTarget, type LinkPreviewState, type LinkPreview, type LinkPreviewResult } from "./link-preview.js";
+export * from "./mcp-apps.js";
diff --git a/packages/shared/src/mcp-apps.test.ts b/packages/shared/src/mcp-apps.test.ts
new file mode 100644
index 00000000000..848f3247bdc
--- /dev/null
+++ b/packages/shared/src/mcp-apps.test.ts
@@ -0,0 +1,92 @@
+import { describe, expect, it } from "vitest";
+import {
+ MCP_APP_MIME_TYPE,
+ buildMcpAppCsp,
+ mcpAppToolCallableFromApp,
+ mcpAppToolVisibleToModel,
+ readMcpAppResource,
+ readMcpAppToolUi,
+ sanitizeMcpAppCspSource,
+} from "./mcp-apps.js";
+
+describe("readMcpAppToolUi", () => {
+ it("reads _meta.ui.resourceUri with the default visibility", () => {
+ expect(readMcpAppToolUi({ ui: { resourceUri: "ui://circleback/meetings" } })).toEqual({
+ resourceUri: "ui://circleback/meetings",
+ visibility: ["model", "app"],
+ });
+ });
+
+ it("accepts the deprecated flat key and an explicit visibility", () => {
+ expect(readMcpAppToolUi({ "ui/resourceUri": "ui://x/view" })?.resourceUri).toBe("ui://x/view");
+ const appOnly = readMcpAppToolUi({ ui: { resourceUri: "ui://x/view", visibility: ["app", "bogus"] } });
+ expect(appOnly?.visibility).toEqual(["app"]);
+ expect(mcpAppToolVisibleToModel(appOnly)).toBe(false);
+ expect(mcpAppToolCallableFromApp(appOnly)).toBe(true);
+ });
+
+ it("keeps visibility for an app-only helper without a view", () => {
+ const helper = readMcpAppToolUi({ ui: { visibility: ["app"] } });
+ expect(helper).toEqual({ resourceUri: null, visibility: ["app"] });
+ expect(mcpAppToolVisibleToModel(helper)).toBe(false);
+ expect(mcpAppToolVisibleToModel(readMcpAppToolUi({ ui: { resourceUri: "https://evil.example", visibility: ["app"] } }))).toBe(false);
+ expect(mcpAppToolVisibleToModel(readMcpAppToolUi({ ui: { visibility: [] } }))).toBe(false);
+ });
+
+ it("ignores tools without a ui:// view", () => {
+ expect(readMcpAppToolUi(undefined)).toBeNull();
+ expect(readMcpAppToolUi({ ui: { resourceUri: "https://evil.example/view" } })).toBeNull();
+ expect(mcpAppToolVisibleToModel(null)).toBe(true);
+ });
+});
+
+describe("readMcpAppResource", () => {
+ const uri = "ui://circleback/meetings";
+ it("reads text content with its csp and border hints", () => {
+ const resource = readMcpAppResource({
+ contents: [{
+ uri,
+ mimeType: MCP_APP_MIME_TYPE,
+ text: "hi",
+ _meta: { ui: { csp: { resourceDomains: ["https://cdn.circleback.ai"] }, prefersBorder: false } },
+ }],
+ }, uri);
+ expect(resource).toMatchObject({ html: "hi", prefersBorder: false, csp: { resourceDomains: ["https://cdn.circleback.ai"] } });
+ });
+
+ it("decodes base64 blob content", () => {
+ const blob = Buffer.from("