mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-21 10:52:06 +01:00
## 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>
219 lines
10 KiB
Markdown
219 lines
10 KiB
Markdown
# 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.
|