Files
PaperClipAI/doc/connections/CIRCLEBACK.md
T
DottaandClaude Opus 5.5 8ff45c0fa9 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>
2026-11-12 13:28:05 -06:00

219 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.