feat(apps): add experimental MCP aggregator connectors (#13755)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Its tool gateway applies company access rules and approval controls
to connected apps.
> - MCP aggregators expose many apps through one provider endpoint.
> - Each aggregator needs its own credential, catalog, grants, and
lifecycle in Paperclip.
> - This pull request adds independent Zapier, Arcade, Composio Connect,
and Executor setup with a common Access → Connect layout.
> - A default-off MCP aggregators flag lets operators opt in while we
complete provider acceptance tests.
> - Agents use the normal Paperclip permissions, Test screen, and
gateway after setup.

## Linked Issues or Issue Description

**Subsystem affected**

Apps, connection setup, shared contracts, and the remote MCP gateway.

**Problem or motivation**

Aggregator endpoints need clear provider setup and correct MCP sessions.
Generic setup does not explain each provider's authentication or broad
execution tools. Provider approval must preserve the original execution
instead of replaying a write.

**Proposed solution**

Add four separate connectors behind Settings → Experimental → MCP
aggregators. Start with human and agent access, then connect the
endpoint and read its tools. Enable tools by default. Use the existing
Permissions and Test screens after setup. Keep legacy Composio API-key
and child connections intact.

**Alternatives considered**

A shared connection for all providers would mix credentials and access
rules. Separate provider-specific permission and test screens would
duplicate existing controls. Vercel Connect is outside this change.

**Roadmap alignment**

Extends the existing MCP Tool Gateway & Apps capability and the
Connected Apps roadmap area. This work was requested and reviewed by the
maintainer.

Related work: #11894, #12630, #12632, #12634, and #12906 concern the
legacy Composio broker. #13102 also covers remote MCP pagination. This
change preserves the broker path and adds initialized sessions, response
matching, and provider resume handling alongside pagination.

## What Changed

- Add branded setup and interactive Storybooks for Zapier, Arcade,
Composio Connect, and Executor. Use the existing access controls and
normal action tests. Do not request a connection name or action choices
during setup.
- Add the default-off `enableMcpAggregators` flag to settings, managed
feature metadata, the catalog, and setup guards. Hidden connections keep
running. Legacy Composio connections remain unchanged.
- Reuse the vault, grants, policy, and catalog models. Support OAuth
discovery, bearer tokens, custom headers, and credential-bearing URLs.
Add no database tables or migrations.
- Initialize and retain Streamable HTTP sessions by connection and
effective credentials. Read paginated catalogs and match streaming
responses to request IDs.
- Classify unfamiliar aggregator tools as writes despite upstream
read-only hints; only exact reviewed read capabilities enter the
read-only allowlist. Legacy Composio child behavior is preserved.
- Preserve provider authorization links and execution IDs. Support
Executor approve/resume, decline, and cancel without automatic replay of
uncertain writes.
- Preserve Off and Ask first choices during refresh and reconnect. Allow
new tools and retire removed tools. Keep agent access updates atomic and
preserve an empty agent selection.
- Document connector UX rules, provider branding sources, and live
acceptance results.
- Stabilize the existing Sentry release fixture after its repeated CI
failure by reusing one module mock; production Sentry behavior is
unchanged.

## Verification

- Final head `d11781970`: [CI
run](https://github.com/paperclipai/paperclip/actions/runs/35633534900)
passed, including broad typecheck, test shards, build, and E2E. All 54
checks pass; 2 optional checks are skipped. Greptile is 5/5, Security
Scan passes, and all review threads are resolved.

- Passed 27 focused connector Vitest checks and 18 connector-only
Storybook browser checks before the flag change. All 85 stories rendered
at desktop and narrow widths.
- Passed 5 connector lifecycle/server checks and 7 selected flag checks
after adding the flag. The latter cover settings, managed defaults,
cached catalog visibility, and all four setup routes.
- Review fixes passed 13 risk/handoff/lifecycle checks, dedicated
session-expiration and transport regressions, 13 selected
connector/gateway CI cases, and 10 selected setup/reconnect UI cases. A
real Composio connection-list call also succeeded through the refreshed
UI on `9ab115f71`.
- UI and server TypeScript checks passed. UI build, Storybook build,
token gates, and diff whitespace checks passed during implementation.
- Real browser and real Paperclip agent tests passed for Arcade,
Composio, and Executor. Tested action permissions, denied agent access,
reconnect, disconnect, and isolation. Tested Arcade catalog
additions/removal and Executor provider approve/resume, decline, and
cancel.
- Zapier live acceptance is incomplete. Its dedicated provider server is
configured, but its credential-copy dialog returned an empty clipboard
through browser automation. No live Zapier action is claimed.
- The three isolated Sentry release cases pass after the CI fixture fix.
- Local verification is deliberately narrow at the maintainer's request.
The full local suite, recursive typecheck, and repository-wide build
were not run. CI provides the broader checks.

## Risks

- Shared MCP transport changes affect other remote MCP servers. Protocol
fixtures cover initialized sessions, streaming response matching,
pagination, and isolation.
- Broad execution tools remain broad permissions. The provider governs
actions inside those tools.
- Provider handoff links are retained briefly in memory. After a server
restart, a one-time link may require reopening the provider dashboard.
Paperclip does not replay the original call.
- Zapier remains unproven live. Custom-header imports and self-hosted
endpoints have fixture coverage rather than a separate live account for
every variant.
- Turning the experimental flag off hides setup; it does not revoke
existing credentials or stop existing connections.

## Model Used

OpenAI GPT-6 through Codex, with reasoning, repository tools, shell
execution, and browser automation. The exact runtime model ID and
context-window size are not exposed in this session. A separate
Anthropic-backed Paperclip agent performed live gateway acceptance
tasks.

## 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
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

doc/connections/CONNECTOR-PLAYBOOK.md

@@ -438,6 +438,26 @@ Avoid separate methods for:
 The default setup screen should ask only for information required to make the
 connection work or enforce a real tenant boundary. Follow these rules:
 
+- Do not ask for a Paperclip **Connection name** during setup. Derive the display
+  name from the provider and observed account/workspace identity. A provider-required
+  app/bot name is a separate configuration requirement, not a connection label.
+- Use the traditional Gmail/Google Docs setup structure: a compact horizontal
+  progress header and **Access → Connect**, without a numbered sidebar,
+  tool-permissions step or optional Test step. Authentication and successfully
+  reading the tool catalog are enough to complete setup. Do not require a sample
+  action or add an empty-catalog onboarding detour. Reuse the existing access screen:
+  “Which humans can use this credential?” and “Which agents can use this connection?”
+- After setup, use the regular connection **Permissions** screen: reuse its
+  canonical searchable Actions list, Read/Write filters, Off / Ask first / Allowed
+  controls and per-action Test dialog. Do not build a parallel permissions list or
+  provider-specific testing page. Discovery errors stay inline on Connect; an empty
+  returned catalog belongs to the ordinary saved-connection state.
+- Enable every discovered tool automatically. Put later Allowed / Ask first / Off
+  controls in management, separate from connection access. Reconnect and refresh
+  retain existing restrictions; new tools are Allowed under the existing access rules.
+- Show browser sign-in/pending/return only for a real OAuth handoff supported by
+  the chosen authentication. Zapier's pasted MCP URL or bearer token requires no
+  Paperclip sign-in window. Advanced token/header setups need no invented OAuth step.
 - Put optional narrowing in fields marked `advanced: true`.
 - Give hidden fields a `defaultValue`; never create a hidden required field the
   server cannot fill.
@@ -841,8 +861,9 @@ At minimum, add or update tests in these layers:
   declared.
 - Finish setup resumes the exact draft using `resumeConnectionId`.
 - Optional customer OAuth details stay folded when automatic OAuth exists.
-- Setup success leads to the connection's Test page, or to Permissions when a
-  separate agent-resource assignment is the next step. Follow the
+- Successful authentication and tool discovery finish setup and lead to the
+  connection's regular Permissions screen. Testing is available there through each
+  action's Test button; it is never an onboarding step. Follow the
   [connection UX guidance](#connection-ux-and-user-journeys).
 - Interactive Storybooks cover setup and ongoing task interactions, including
   relevant failure states; the walkthrough matches the implemented journey.

doc/connections/REMOTE-MCP-BRAND-SOURCES.md

@@ -0,0 +1,16 @@
+# MCP connector brand assets
+
+Retrieved 2026-09-21 from the providers’ own sites for the independent connector
+design review. Brand-library membership does not publish a catalog connector.
+The four connectors are available for setup only when the MCP aggregators experimental flag is enabled.
+Zapier and Composio reuse the existing reviewed local marks.
+
+| File | Source | SHA-256 |
+| --- | --- | --- |
+| `ui/public/brands/apps/arcade.png` | [Arcade site touch icon](https://www.arcade.dev/_astro/webclip.BYnZsC5R.png), linked from [arcade.dev](https://www.arcade.dev/) | `5b3704e210b6dc70fffab260d5416624f37db19108399a6d2c18c848d33465ad` |
+| `ui/public/brands/apps/executor.png` | [Executor site icon](https://executor.sh/favicon-192.png), linked from [executor.sh](https://executor.sh/) | `e5fd761a0cd80d51d451cc06e9e6d0236dcc39317248a13ac5db5fcf4d52d0ca` |
+
+Both files preserve provider artwork without recoloring. The shared AppLogo
+provides the standard gray frame and contained padding. Arcade’s SVG favicon
+wrapped embedded raster content; the 180px touch icon linked by the same official
+page was used to satisfy the repository’s artwork safety checks.

doc/connections/REMOTE-MCP-LIVE-ACCEPTANCE.md

@@ -0,0 +1,76 @@
+# Independent MCP connectors — acceptance, 2026-09-21
+
+Test environment: an isolated development worktree with a fresh database and organization. No production data was cloned. The API served the compiled UI with browser-reachable OAuth callbacks. Detailed account and local-instance evidence remains in a private acceptance report.
+
+**This PR delivers default-off experimental support at the maintainer's request. General provider acceptance remains incomplete: Zapier needs its generated credential entered before live validation can finish.** Three providers have real browser and real agent proof. Simulations are recorded separately below. The maintainer's subsequent delivery instruction was to put these connectors behind an experimental MCP aggregators flag and open a PR with passing checks. The Zapier gap is an explicit limitation of that experimental scope, not a claim that the connector playbook's full provider acceptance is complete. Complete that acceptance before promoting the feature out of experimental status.
+
+## Experimental rollout
+
+Setup is behind **Settings → Experimental → MCP aggregators** (`enableMcpAggregators`). It defaults off on self-hosted and managed instances. When off, all four fresh catalog entries are hidden and direct setup, reconnect setup, and OAuth-start requests are rejected server-side. Existing connections keep running and remain available for management. Legacy Composio API-key/child connections are unchanged. An in-progress OAuth callback may complete; the flag does not revoke already issued credentials or grants.
+
+Focused regression tests cover flag defaults, persistence, managed metadata, cached catalog visibility, all four direct setup routes, and server-side rejection before network/credential writes.
+
+## Live results
+
+| Provider | Functional correctness | UX readiness | Observed account, catalog, and actual results |
+| --- | --- | --- | --- |
+| Arcade | Passed OAuth setup, Test, real agent, Off, Ask first, denied agent, catalog additions/removal, reconnect, disconnect, and restoration. | Ready for the tested gateway OAuth flow after the fixes below. | Dedicated test gateway with a verified GitHub account. Started with 4 exposed tools, added two read actions, then removed one (5 remain). `Github.GetRepository` returned `paperclipai/paperclip`, branch `master`, repository ID `1170821064`. |
+| Composio | Passed default endpoint OAuth, Test, real agent, Off, Ask first, denied agent, refresh, reconnect, disconnect, and restoration. | Ready for Composio Connect. Optional GitHub app consent remains at GitHub's user-verification screen; this does not block the verified DeepWiki action. | Verified provider account; 11 meta tools. Search discovered `DEEPWIKI_MCP_READ_WIKI_STRUCTURE`; Multi Execute returned the real Paperclip documentation hierarchy, 1 success / 0 errors. The real agent repeated discovery and execution. |
+| Executor | Passed workspace OAuth, Test, real agent, Off, Ask first, denied agent, refresh, reconnect, disconnect, and restoration. Provider approve/resume, decline, cancel, and Paperclip approval → provider approval were exercised. | Ready for the tested hosted workspace with model-side resume. Decline/cancel copy now describes the deliberate outcome rather than suggesting a retry. | Dedicated test workspace with a verified provider account; 7 tools. Execution returned integration slugs `executor`, `context7`. A disposable Context7 read paused for approval; resuming the same execution returned real React library IDs. |
+| Zapier | Live proof blocked after provider setup; production integration and deterministic tests are implemented. | Approved setup design and Storybook checks pass. Real URL-paste workflow still needs completion. | Created a dedicated Managed-mode server with Google Sheets Find Spreadsheet / Get Spreadsheet by ID, using an existing test account. Its generated credential is masked. Copy buttons returned an empty clipboard through automation. No Paperclip credential has been entered or live tool call made. |
+
+The real Paperclip agent used a vaulted model credential. No secret value is stored in this report or the source tree.
+
+### Agent evidence
+
+- Gateway acceptance task: six real gateway calls; Arcade repository read and Executor skills → search → integrations list.
+- Execution and disabled-tool task: Composio discovery and DeepWiki execution returned actual headings including Overview, Core Concepts, Getting Started, Server Architecture, and User Interface. Arcade's Off tool was absent from callable discovery. Executor public helper paths were readable and executable.
+- Revocation and access-denial task: disconnected Arcade exposed no tools; ungranted Composio exposed no tools and reported that identity/access needed review. Executor remained available and returned its actual integration list. This verifies cross-connection isolation through a real agent.
+
+### Governance and lifecycle evidence
+
+- Arcade CountStargazers Off prevented a Test call and disappeared from the real agent's tool surface. GetRepository Ask first made no call until “Allow once”; the saved Test result then showed the actual repository response.
+- Composio Multi Execute Off prevented Test execution. Search Ask first completed only after Paperclip review. Removing all agent access made Search Off despite its saved Ask first choice.
+- Executor skills Off prevented testing. Removing agent access also prevented execute despite an Ask first choice. A separately allowed execution paused at the provider, preserving its execution ID. Inline acceptance resumed that ID; decline and cancel each stopped their respective execution. Paperclip Ask first → Allow once → provider pending survived navigation to Review and back.
+- Arcade catalog refresh enabled newly added GetFileContents and GetIssue automatically, preserved CountStargazers Off and GetRepository Ask first, and removed GetIssue after its removal upstream. Composio/Executor refreshes retained their stable catalogs and rules. Provider-controlled additions to Composio's meta catalog were not manufactured; changed-catalog fixtures cover the common path.
+- All three OAuth reconnects retained an empty agent selection and existing Off/Ask first choices. Reloaded screens agreed with effective Test access.
+- Disconnected each through the real UI. Subsequent requests for previously valid Test actions returned HTTP 404 `tool_not_found` for all three. Reconnected through Apps and verified fresh Arcade repository, Composio search, and Executor skills calls. The three connections are left connected with default permissions for review.
+- Removed the temporary Executor `context7.*` approval policy after testing. The dedicated test gateway, Zapier server, and Context7 connection remain available for review. Existing unrelated provider configurations were not changed.
+
+## Defects found, fixed, and retested
+
+1. Enabled DCR ownership for direct MCP OAuth; Composio no longer incorrectly requires a configured client ID.
+2. Added explicit provider authorization/approval states, validated handoff links, execution identifiers, and resume controls. Executor's `resume.content` must be a JSON string; corrected it after an observed provider rejection and retested successfully.
+3. Added an object JSON editor for open-ended schemas. Composio's nested `arguments` object was otherwise impossible to enter. The real Multi Execute call passed afterward.
+4. Corrected broad execution risk classification and the false JWT redaction of three exact public Executor helper selectors. Actual secrets, bearer assignments, and arbitrary dotted values retain redaction. The execution acceptance task verified the selectors live.
+5. Prevented app-generated Ask first policies from granting access to an ungranted agent. Negative fixture and live Test/agent checks pass.
+6. Allowed an empty selected-agent list and made installation reach plus permission binding updates atomic. OAuth completion no longer substitutes all agents for an empty saved selection. Real reconnects and a dedicated OAuth callback regression pass.
+7. Refreshed permission caches with the catalog so newly added tools display Allowed immediately.
+8. Retired disappeared tools in stored discovery, not merely the refresh response. Reappearing tools keep existing restrictions. The regression checks persisted database state; the Arcade removal was retested live.
+9. Prevented retries of an already-approved provider-pending runtime call from starting another execution. The fixture verifies one dispatch and retained execution identity. Test requires an explicit Reset before starting another approval-controlled call.
+10. Added production Reconnect, Manage in provider, and Disconnect controls using the same management component as Storybook. Saved access loading and setup failures remain actionable.
+
+## Supporting checks
+
+All newly added isolated checks passed, with one test worker:
+
+- 27 Vitest checks: protocol (7), provider pending (5), connector lifecycle/governance/OAuth (4), redaction (2), shared contracts (7), schema form (2).
+- 18 connector-only Storybook browser checks: four complete setup journeys, four draft/auth journeys, desktop/narrow state matrices, keyboard recovery, Zapier's absence of OAuth, normal Test states, and Executor approve/decline/cancel.
+- All 85 connector stories rendered at 1280px/dark and 390px/light without page errors or horizontal overflow. Inspected generated setup and Test screenshots. Evidence is under `tests/storybook-visual/test-results/remote-mcp/` (ignored local test output).
+- UI and server direct TypeScript checks, token gates, UI build, Storybook build, and `git diff --check` passed.
+- **No full repository test suite, recursive typecheck, or repository-wide build was run locally**, following the maintainer's explicit resource constraint. The PR's CI runs the required broad typecheck, test shards, and build; those gates must pass before handoff. Narrow local verification is not a waiver of CI. No schema migration or lockfile change is included.
+
+Storybook links: `apps-connections-zapier--complete-setup-journey`, `apps-connections-arcade--complete-setup-journey`, `apps-connections-composio--complete-setup-journey`, `apps-connections-executor--complete-setup-journey`. `apps-connections-executor--provider-handoff-after-setup` uses mocked responses and makes no real authorization request.
+
+## Remaining work and limits
+
+PR review regressions: expired MCP sessions now trigger one safe discovery handshake; action calls fail visibly and wait for an explicit retry. Provider handoff detection recognizes protocol/provider envelopes rather than arbitrary app-data statuses. Buffered transports preserve response-ID matching, size limits, and distinct error codes. Dedicated regression checks and selected existing connector/gateway cases pass. Ordinary connector resume/reconnect continues through its existing controller.
+
+Aggregator action risk is conservative: an unfamiliar or renamed tool defaults to write risk even if the provider advertises it as read-only. Only an explicit reviewed allowlist receives read risk; annotations can still escalate it. This affects risk labels and risk-based governance, not the approved default-enabled behavior or saved Off/Ask first choices. Legacy Composio child connections retain their existing classification path.
+
+- Paste Zapier's generated Full URL into the already-open local Zapier setup field (not chat), then complete its browser Test, agent, governance, refresh, and lifecycle acceptance. Do not rotate the displayed credential unnecessarily.
+- Optional Composio GitHub account authorization awaits the user's GitHub verification. The no-auth DeepWiki app path is proven; GitHub app execution is not claimed.
+- Hosted OAuth paths were tested live. Custom-header/session imports, credential-bearing URLs, protocol URL elicitation, pagination edge cases, and revocation races have deterministic fixture coverage rather than separate live accounts/endpoints for every variant.
+- Provider auth links are kept briefly in memory; durable records retain redacted handoff/execution identifiers. After an application restart, a one-time auth link may need reopening from the provider dashboard. Calls are never automatically replayed to recover it.
+
+Completion still requires observed live results for Zapier. Passing stories and fixtures do not substitute for that proof.

doc/design/COMPONENT-INVENTORY.md

@@ -6,6 +6,20 @@ Run scope: `ui/src/components/` and `ui/src/pages/` on branch `design/token-extr
 
 ## Counts
 
+### Independent MCP connection setup — 2026-09-21
+
+`ui/src/features/connections/remote-mcp/RemoteMcpConnectionSetup.tsx` is the controlled
+Access → Connect and management composition for Zapier, Arcade,
+Composio and Executor. It reuses Gmail’s StepHeader and AccessStepContent, plus SetupWizardFooter,
+AppLogo, InlineBanner and existing form/dialog primitives. Saved connections reuse
+the canonical PermissionsPanel ActionsSection and its ActionTestDialog; there is
+no separate setup test or permission list. Each
+provider has an independent state and controller. It does not initiate network
+authentication requests or persist credentials. The shared Test dialog uses normal
+API calls, intercepted by scoped in-memory Storybook fixtures. The first milestone is design review; production
+routes do not use it yet. See `/design-guide` and Storybook **Apps / Connections**
+for the provider variants and complete interactive state matrix.
+
 Execution recovery reuses the existing transcript header and task status. Routine phases add no list badges, status cards, or reconciliation dialogs. Only a transient reconnection changes the header text. Automatic recovery decisions remain in the local run log. Storybook **Tasks / Execution recovery** demonstrates quiet task lists, native and legacy transcript headers, and dashboard composition.
 
 | Area | Count |

doc/plans/2026-09-21-independent-mcp-connectors.md

@@ -0,0 +1,220 @@
+# Four independent MCP connectors
+
+Branch: `codex/unified-mcp-connectors`
+Worktree: dedicated checkout on `codex/unified-mcp-connectors`
+Base: `b19307758`
+
+Zapier, Arcade, Composio and Executor each have their own connection, credentials,
+catalog, agent access, permissions, sessions and lifecycle. Their setup shares the
+same structure: **Access → Connect**. Underlying apps remain managed
+in the provider; Paperclip does not create child connections for every app.
+
+## Delivery checkpoints
+
+- [x] Create the fresh worktree.
+- [x] Build controlled application views and four interactive Storybook groups.
+- [x] Review the designs with the user and incorporate revisions.
+- [x] Wire the reviewed views to production APIs and implement shared protocol support.
+- [ ] Conduct real browser acceptance testing for all four providers, fix and retest.
+- [x] Complete the user-authorized narrow checks: new isolated tests, direct UI/server typechecks, token gates, UI and Storybook builds. Full repository suites/builds were explicitly excluded.
+
+Design review is complete and the user authorized production integration and live browser testing. The implementation is running in fresh local data. Three providers have real browser and agent proof; Zapier is waiting for a credential handoff. See [the current acceptance report](../connections/REMOTE-MCP-LIVE-ACCEPTANCE.md). Simulations are not live proof.
+
+## Review links and operation
+
+The review server uses the build from this worktree on port 6137:
+
+| Provider | Complete journey |
+| --- | --- |
+| Zapier | `apps-connections-zapier--complete-setup-journey` |
+| Arcade | `apps-connections-arcade--complete-setup-journey` |
+| Composio | `apps-connections-composio--complete-setup-journey` |
+| Executor | `apps-connections-executor--complete-setup-journey` |
+
+Choose who can use the connection, continue, then use **Use example configuration**. The separate
+**Storybook simulation** area supplies provider responses and browser sign-in or
+completion events. After connection, Test opens the regular per-action dialog with
+scoped mock API responses; approval requests stay pending in this preview. Provider links are intercepted by this simulator;
+they do not open real authorization pages. Example catalogs and schemas are
+representative, not production constants. Never enter real credentials here.
+
+Each provider group exposes initial access, selected agents, URL and advanced
+setup, connecting, invalid URL, rejected credentials, unreachable endpoint,
+and post-setup permissions/management states. Successful authentication and catalog
+discovery complete setup. There is no empty-catalog or Test setup step. Tool restrictions
+and action tests use the regular Permissions screen after setup. All new tools are enabled automatically.
+
+Browser sign-in pending/return/cancel stories apply only to Arcade, Composio and
+Executor OAuth configurations. Zapier uses the pasted URL/token without an OAuth
+handoff. Upstream app authorization and Executor resume now use the shared
+post-setup Test dialog; bespoke setup test stories
+have been removed. Narrow access, connection details
+and tool management are directly accessible.
+
+### Design feedback incorporated — 2026-09-21
+
+- Reuse the actual Gmail `AccessStepContent` and `StepHeader`: human credential
+  sharing and agent reach come before credentials, with compact top progress bars.
+- Remove Connection name, the numbered sidebar and setup tool-permission controls.
+- Finish setup as soon as authentication and tool discovery succeed, with all
+  tools enabled. Remove the empty-catalog story and every setup Test step.
+- Reuse the actual Permissions `ActionsSection` and `ActionTestDialog` after setup,
+  including search, Read/Write filters, permission radios and per-action testing.
+- Keep tool restrictions in management, separate from who can use the connection.
+- Remove Zapier OAuth stories/options and unsupported provider resume examples.
+- Update the canonical connector playbook and local `chat-connector-ux` skill with
+  these conventions, including the explicit prohibition on setup connection names.
+
+Drafts live only in React state in the previews and clear on reload. The production
+controller must persist progress through refresh and OAuth redirects using the
+existing server draft and vault mechanisms. Do not copy preview persistence into
+production.
+
+To rebuild and serve:
+
+```sh
+pnpm --filter @paperclipai/ui build-storybook
+node scripts/serve-storybook-static.mjs --port 6137
+```
+
+## Provider setup contracts
+
+| Provider | New setup | Permission boundary |
+| --- | --- | --- |
+| Zapier | Paste generated secret-bearing URL; alternatively endpoint plus bearer token. | Recommend Managed mode for individual action controls. Agentic mode exposes discovery/execution tools; permissions cover the whole exposed call. |
+| Arcade | Paste gateway URL and sign in through the gateway’s configured User Source. Advanced: bearer API key plus `Arcade-User-ID`. | Actual exposed gateway tools. Individual apps can require further authorization. |
+| Composio | Prefill `https://connect.composio.dev/mcp`, then authenticate. Advanced: externally configured session URL and headers. | Connect’s discovery, execution, connection-management and sandbox tools. Direct-tools sessions can expose individual actions. |
+| Executor | Paste hosted workspace URL or reachable self-hosted HTTP endpoint and authenticate. Advanced user API key when supported. | Execution and helper tools; action policies remain in Executor. Preserve execution and MCP session identity for resume. |
+
+The production catalog always comes from discovery, never the Storybook fixture.
+Only expose a pending-state recovery action when the actual provider response and
+protocol support it. Executor’s browser approval/resume is a specific supported
+pattern; implement it in the shared post-setup Test dialog, not in onboarding.
+
+Existing Composio project-API-key and child connections must remain supported.
+New direct-MCP setup must not migrate their credentials or grants. Narrow legacy
+broker checks by setup/transport instead of treating all Composio connections as
+parent brokers. Vercel Connect remains a separate follow-up: its documented role
+supplies credentials for an app’s MCP connection rather than this aggregator flow.
+
+Research references (checked 2026-09-21):
+
+- Zapier [setup](https://docs.zapier.com/mcp/get-started/connect/other) and [tool modes](https://docs.zapier.com/mcp/overview/how-tools-work).
+- Arcade [MCP gateways](https://docs.arcade.dev/en/operate/governance/mcp-gateways).
+- Composio [Connect](https://docs.composio.dev/docs/composio-connect) and [sessions](https://docs.composio.dev/docs/sessions-via-mcp).
+- Executor [MCP proxy](https://executor.sh/docs/mcp-proxy) and [implementation](https://github.com/UsefulSoftwareCo/executor).
+- Vercel [AI SDK and MCP integration](https://vercel.com/docs/connect/frameworks/ai-sdk-and-mcp).
+
+## Production implementation scope
+
+The views live in `ui/src/features/connections/remote-mcp/`; fixtures and the
+simulator live under `ui/storybook/`. Reuse the views in the production controller
+and keep the stories synchronized. The production controller is routed into Apps.
+
+1. **Definitions and contracts:** give all four providers independent catalog
+   definitions, setup/branding metadata and capabilities. Permit branded setup
+   and configuration imports to use OAuth discovery, bearer tokens, custom
+   headers and credential-bearing URLs. Extend existing connection/test types
+   with provider presentation and upstream pending state. No new connection
+   model or database tables are planned.
+2. **MCP transport:** complete initialized Streamable HTTP operation, paginated
+   `tools/list`, response matching by JSON-RPC ID, and session continuity across
+   execution/resume. Existing `server/src/services/mcp-http.ts` and tool-access
+   discovery need this work; a one-request proxy is insufficient.
+3. **Gateway governance:** enforce company membership, agent grant and tool
+   permission on both discovery and invocation, including resume. Allow new
+   catalog entries under existing connection access; preserve explicit Off and
+   Ask first, remove disappeared tools, and audit changes. Broad-tool permission
+   covers the entire exposed call.
+4. **Authentication and recovery:** keep credentials/catalogs/policies/sessions
+   isolated by connection and effective identity. Use the vault, endpoint
+   validation and secret redaction. Preserve execution IDs and handle provider
+   authorization URLs and URL elicitation in both runtime and Test. Never
+   automatically repeat a call when a write may already have happened. Disconnect
+   must revoke access and invalidate sessions without affecting other connections.
+5. **UI controller:** connect these controlled views to `ConnectionSetupFlow`,
+   current permissions and Test interfaces, draft storage, OAuth and existing
+   service APIs. Resolve provider pending actions using observed capabilities.
+   Save errors remain visible and do not pretend to persist a draft. The test’s
+   acting agent uses the same effective rules as a real agent gateway call.
+6. **Verification:** protocol/governance fixtures, Storybook interaction and
+   visual checks, token gates, Storybook build, then required repository typecheck,
+   tests and build. Run the final checks on the integrated production change.
+
+## Historical design milestone verification
+
+Review environment: macOS, this worktree, static Storybook, example company,
+agents and catalogs. Browser UI simulation and production acceptance are recorded
+separately. Screenshots generated by the browser suite are local test evidence;
+they are not Linux visual-regression baselines.
+
+Commands:
+
+```sh
+pnpm --filter @paperclipai/ui typecheck
+pnpm check:token-gates
+pnpm exec vitest run ui/src/components/SetupWizard.test.tsx ui/src/components/JsonSchemaForm.test.tsx ui/src/features/connections/ConnectionSetupFlow.architecture.test.ts ui/src/pages/apps/app-detail/TestPanel.test.tsx
+pnpm --filter @paperclipai/ui build-storybook
+pnpm exec playwright test --config tests/storybook-visual/remote-mcp-connections.config.ts
+```
+
+Observed fixes during review: Save & exit now explicitly avoids submitting its
+form; schema inputs expose accessible names; setup reuses the Gmail access choices and compact top progress header; newly discovered fixture tools default to Allowed without resetting saved
+restrictions. The shared components retain their existing behavior otherwise.
+
+### Design revision verification (before production integration)
+
+- UI typecheck, token gates, 34 focused tests and Storybook build passed.
+- All 15 browser checks passed, including four complete Access → Connect journeys
+  that finish with zero action calls and every discovered action Allowed.
+- The canonical Permissions action list and Test dialog cover effective agent
+  access, denied agents, disabled tools, success, errors and pending approval.
+  Permission changes survive catalog refresh and reconnect; disconnect blocks use.
+- All 82 stories render at 1280px/dark and 390px/light without page errors or
+  horizontal overflow: Zapier 18, Arcade 21, Composio 22, Executor 21.
+- Browser inspection confirmed Zapier goes straight from Connect to saved
+  permissions, then opens the shared Test dialog. Narrow Permissions screenshots
+  for Zapier/Composio and the shared Test dialog were visually reviewed.
+- Fake credentials stay out of browser storage, and scoped test requests never
+  leave the Storybook mock. No real provider action ran.
+
+Screenshots are local test evidence in
+`tests/storybook-visual/test-results/remote-mcp/`. Earlier 117/122-story results
+included the removed setup Test flow and are superseded by this revision.
+
+The removed simulations were never live provider proof. Production results and the final narrow check commands are recorded in the acceptance report. The user subsequently prohibited running the full suite locally; that later constraint supersedes the earlier repository-wide verification plan.
+
+Dependency installation previously used the pinned pnpm after a base-branch
+patch/lockfile mismatch (`postgres@3.4.9`); the tracked lockfile was restored.
+No dependency or lockfile changes are included.
+
+## Current live acceptance
+
+See [REMOTE-MCP-LIVE-ACCEPTANCE.md](../connections/REMOTE-MCP-LIVE-ACCEPTANCE.md) for provider-specific results, actual agent task links, fixes, retests, and remaining gaps.
+
+- Arcade, Composio, and Executor: real OAuth, catalog, Test and agent calls observed; governance and lifecycle exercised.
+- Zapier: dedicated provider server configured, but its generated secret URL still needs to be pasted into the local setup form. No live execution proof is claimed.
+- Supporting checks: 27 newly added isolated Vitest checks, 18 connector-only Storybook checks, 85 stories at desktop/narrow widths, direct UI/server typechecks, token gates, UI build, and Storybook build passed. One test worker; no full repository suite or recursive build/typecheck.
+
+The isolated test instance has a fresh database and a browser-reachable OAuth callback. All three tested connections were restored after revocation checks and are available for review.
+
+For **each** provider, record environment, account identity, observed catalog,
+journeys, actual results, useful screenshots, defects/fixes/retests and gaps:
+
+1. Discover it from Apps, connect it, and verify account and catalog.
+2. Assign agent access and exercise Allowed, Ask first and Off.
+3. Run a useful action in Test and verify its external result; use disposable
+   data for writes.
+4. Have a real Paperclip agent call through the Paperclip gateway. Verify an
+   ungranted agent and disabled tool are denied.
+5. Exercise applicable provider authorization/approval, including Executor resume
+   without starting a second execution.
+6. Add/remove tools upstream and refresh. New tools become Allowed; prior Off and
+   Ask first remain. Confirm reload, draft return, reconnect and disconnect.
+7. Change this connection and prove the other connections remain unaffected.
+8. Assess redirects, transient errors, duplicate writes, copy, keyboard access,
+   desktop and narrow layouts. Fix defects and repeat affected journeys.
+
+Completion requires observed live results for **all four**, with functional
+correctness and UX readiness assessed separately. Storybook successes do not
+check any live acceptance box.