paperclip/doc/plans
Dotta d387cc0ff0
feat(connections): add managed external MCP connectors (#12346)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Connection intents need secure provider implementations to complete
setup.
> - Some providers use managed OAuth or external credential brokers.
> - Those tokens must stay out of durable Paperclip state and fail
closed when refresh fails.
> - This pull request adds managed connector backends and the required
storage contract.
> - The benefit is safer provider setup with governed credential
lifecycles.

## Linked Issues or Issue Description

Refs #11965

This is stack 8 of 11. It depends on stack 7 and replaces another
reviewable part of #11965.

## What Changed

- Add managed Google Workspace and external connector backends.
- Add Vercel Connect support without storing provider bearer tokens.
- Add replay-safe migration 0232 and its generated snapshot.
- Fail closed and clear stale token bindings when organization OAuth
refresh needs reauthorization.

## Verification

- `pnpm --filter @paperclipai/server typecheck`
- `pnpm --filter @paperclipai/server exec vitest run
src/__tests__/tool-access-service.test.ts`
- Result: 194 tests passed.
- `pnpm --filter @paperclipai/db check:migrations`
- `pnpm build`
- `pnpm exec vitest run --project @paperclipai/server
server/src/services/remote-url-credentials.test.ts` (5 passed, including
URL userinfo vault extraction)

## Risks

- Broker metadata errors can block provider setup.
- OAuth refresh failure disables the shared organization connection
until reauthorization.
- Migration 0232 is generated, ordered after 0231, and safe to replay.

> I checked `ROADMAP.md`. This stack continues the existing app
connection work from #11965 and does not duplicate another planned item.

## Model Used

OpenAI Codex, GPT-5. The runtime model ID and context window were not
exposed. The model used reasoning, tool use, and code execution.

## 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 linked the public source pull request with `Refs #`
- [x] I have not referenced internal or instance-local Paperclip issues
or links
- [x] My branch name describes the change 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
2026-08-29 12:08:34 -05:00
..
2026-02-16-module-system.md
2026-02-18-agent-authentication-implementation.md
2026-02-18-agent-authentication.md
2026-02-19-agent-mgmt-followup-plan.md
2026-02-19-ceo-agent-creation-and-hiring.md
2026-02-20-issue-run-orchestration-plan.md
2026-02-20-storage-system-implementation.md
2026-02-21-humans-and-permissions-implementation.md
2026-02-21-humans-and-permissions.md
2026-02-23-cursor-cloud-adapter.md
2026-02-23-deployment-auth-mode-consolidation.md
2026-03-10-workspace-strategy-and-git-worktrees.md
2026-03-11-agent-chat-ui-and-issue-backed-conversations.md
2026-03-13-TOKEN-OPTIMIZATION-PLAN.md
2026-03-13-agent-evals-framework.md
2026-03-13-company-import-export-v2.md
2026-03-13-features.md
2026-03-13-paperclip-skill-tightening-plan.md
2026-03-13-plugin-kitchen-sink-example.md
2026-03-13-workspace-product-model-and-work-product.md
2026-03-14-adapter-skill-sync-rollout.md
2026-03-14-billing-ledger-and-reporting.md
2026-03-14-budget-policies-and-enforcement.md
2026-03-14-skills-ui-product-plan.md
2026-03-17-docker-release-browser-e2e.md
2026-03-17-memory-service-surface-api.md
2026-03-17-release-automation-and-versioning.md
2026-04-06-smart-model-routing.md
2026-04-06-subissue-creation-on-issue-detail.md
2026-04-07-issue-detail-speed-and-optimistic-inventory.md
2026-04-07-pi-hooks-survey.md
2026-04-08-agent-browser-process-cleanup-plan.md
2026-04-08-agent-os-follow-up-plan.md
2026-04-08-agent-os-technical-report.md
2026-04-12-vscode-task-interoperability-plan.md
2026-04-24-external-object-reference-backfill.md
2026-04-26-plugin-secret-ref-company-scope.md
2026-05-05-scaled-kanban-board-design.md
2026-05-05-scaled-kanban-board.md
2026-05-06-llm-wiki-paperclip-asset-security-gate.md
2026-05-23-cli-api-parity-openapi-reference.ts
2026-05-23-cli-api-parity.md
2026-05-26-skills-cli-catalog-contract.md
2026-06-03-low-trust-review-contract.md
2026-06-05-agent-access-mcp-runtime-slots-adr.md
2026-08-26-self-serve-mcp-connections.md feat(connections): add managed external MCP connectors (#12346) 2026-08-29 12:08:34 -05:00
workspace-product-model-and-work-product.md
workspace-technical-implementation.md