DottaandPaperclip
8f40b4ad4b
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - App connections give agents controlled access to external services.
> - Managed Google Workspace methods depend on profiles enabled for each
Paperclip instance.
> - The catalog used those profiles, but connection creation used static
availability and rejected enabled connections.
> - Switching capabilities also reset personal ownership to company-wide
ownership.
> - This PR uses the same availability rules for catalog and setup, and
preserves supported ownership choices.
> - Paperclip is the default Google authentication method. A small link
opens custom OAuth settings when needed.
> - Local and cloud instances can start the selected Workspace
connection without broadening its audience.
## Linked Issues or Issue Description
**What happened?**
A fresh enrolled instance showed managed Google Workspace apps as
available. The issue was first found with Gmail. Selecting Continue to
sign in returned HTTP 422 with “This app does not have an available
connection method.” Changing from Read & create drafts to Read only also
reset Just me to company-wide ownership.
**Expected behavior**
Start Google authorization for an enabled profile. Keep personal
ownership when the selected method supports it. Reject profiles that the
instance cannot use.
**Steps to reproduce**
1. Start a fresh source test-drive and enroll the instance with
Paperclip Cloud.
2. Open Apps and select Gmail.
3. Select Just me and choose the agents that can use the connection.
4. Continue to setup and select Read only.
5. Go back to inspect ownership, then continue to sign in.
**Paperclip version or commit**
Reproduced on master commit 250deab910.
The fix is rebased onto current master.
**Deployment mode**
Local source test-drive. Regression tests also cover authenticated cloud
mode, HTTPS callbacks, and instance credentials supplied through
environment variables.
Related PRs: #13098 preserves task context through enrollment and OAuth.
#12619 introduced the managed Google Workspace rollout. This PR fixes
availability validation and ownership changes in that setup flow.
## What Changed
- Share instance-specific managed-method filtering between catalog
discovery and connection creation.
- Keep stored managed methods recognizable during callback, refresh, and
revoke.
- Preserve credential ownership when switching to another method that
supports it.
- Replace the Google authentication radio cards with a small Use your
own Google OAuth app link. Reveal custom fields only when selected, with
a Use Paperclip instead link to return. Associate the toggle with its
labeled field region for screen readers.
- Test all 16 managed Google Workspace profiles in local and
authenticated cloud modes, including cloud environment credentials and
unavailable profiles.
- Test ownership across all nine Workspace app cards, including
capability changes, authentication changes, and enrollment return.
- Document the shared availability and ownership behavior.
## Verification
- All 135 setup tests pass after the UI change. The focused connector
and service suites also passed before this presentation-only change.
- The expanded Workspace matrix includes 32 local/cloud callback cases,
16 cloud environment-identity cases, 32 unavailable-profile cases, and
18 UI ownership cases.
- `pnpm -r typecheck`, `pnpm build`, and `pnpm check:token-gates` pass.
UI typecheck and token gates also pass on final commit `2071002d6`.
- Browser tests cover Gmail, Calendar, Chat, Docs, Drive, People,
Sheets, Slides, and Workspace Search in an isolated source test-drive.
- Each app reaches Google sign-in with its expected read-only scopes.
Personal ownership persists after capability or authentication changes.
Chat also resumes its saved setup with read-only access intact.
- Browser verification of the new layout: custom fields start hidden,
the small link reveals them, and keyboard activation of Use Paperclip
instead hides them. Personal ownership and read-only selection persist.
- Google consent was not granted. Live provider reads and a deployed
cloud instance remain unverified.
- The local repository-wide suite was stopped at the maintainer's
request. Full CI verification passed for final commit `2071002d6`: 31
successful checks, two optional Storybook checks skipped. This includes
repository tests, browser E2E, typecheck, build, and canary dry run.
Greptile reviewed that commit at 5/5 with no outstanding findings.
## Risks
- The shared availability helper affects all managed connectors. It
filters methods by the instance's advertised profiles and does not
mutate the static catalog.
- Stored connections can resolve their managed method after availability
changes. The broker still enforces current access during authorization
and refresh.
- No database migration or provider scope change is included.
## Model Used
OpenAI Codex (GPT-6), with reasoning, code editing, shell tools, and
browser automation. The session does not expose an exact runtime model
ID or context-window size.
## 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>
7.8 KiB
Google Workspace connections
Paperclip presents Google Workspace as nine independent Apps entries, not as one combined Google connection:
- Gmail
- Google Drive
- Google Docs
- Google Sheets
- Google Slides
- Google Calendar
- Google Chat
- Google People
- Google Workspace Search
Each entry creates its own connection, consent grant, capability catalog, policy, audit trail, and reconnect/revoke lifecycle. Connecting Drive does not create a Docs or Sheets connection, and connecting Gmail does not enable Workspace Search.
Google's hosted Workspace MCP servers are Developer Preview services. The app cards remain independent even when several services use the same customer-owned Google OAuth client or the same Paperclip Cloud broker deployment.
Developer Preview enrollment
Google grants preview access to the specific Workspace email addresses and Google Cloud project numbers registered with the program. Submitting the form is not the approval signal:
- Google first sends a Google Group membership notification after verifying the Workspace account.
- Google then sends a final confirmation after registering the Cloud project, usually within a couple of days. This final email is the signal that MCP testing can begin.
- If no final confirmation arrives within a week, check spam and contact the Developer Preview program team from the program page.
Enrollment does not authorize every user of an OAuth client. Additional tester emails and Cloud projects must be added through Google's member request forms. Google's preview terms also prohibit making a pre-GA integration available to end users outside the enrolled company or domain unless Google grants explicit permission. Consequently, Paperclip-managed Google OAuth is limited to registered internal testers during preview. Other companies must enroll their own Workspace testers and Cloud project and use a customer-owned OAuth app until Google makes Workspace MCP generally available.
App matrix
| App card | MCP endpoint | Capability choices |
|---|---|---|
| Gmail | https://gmailmcp.googleapis.com/mcp/v1 |
Read only; read and create drafts |
| Google Drive | https://drivemcp.googleapis.com/mcp/v1 |
Read only; read and create files |
| Google Docs | https://docsmcp.googleapis.com/mcp/v1 |
Read only; read and edit |
| Google Sheets | https://sheetsmcp.googleapis.com/mcp/v1 |
Read only; read and edit; share selected sheets with the robot account |
| Google Slides | https://slidesmcp.googleapis.com/mcp/v1 |
Read only; read and edit |
| Google Calendar | https://calendarmcp.googleapis.com/mcp/v1 |
Read only; read and manage events |
| Google Chat | https://chatmcp.googleapis.com/mcp/v1 |
Read only; read and send messages |
| Google People | https://people.googleapis.com/mcp/v1 |
Read contacts |
| Google Workspace Search | https://workspacemcp.googleapis.com/mcp/v1 |
Search Workspace |
The setup flow asks for the capability first. When the managed method is available, it uses Paperclip by default. A small Use your own Google OAuth app link reveals the custom client fields; Use Paperclip instead returns to the managed method. The available authentication methods are:
- Connect with Paperclip uses the Paperclip Cloud broker when that exact
profile is returned for this enrolled instance by the signed
POST https://my.paperclip.app/v1/connector/instance-statusrequest. The anonymous capabilities document is global discovery only and never enables an internal-pilot method locally. - Use your own Google OAuth app uses customer-supplied OAuth credentials and the app definition's exact reviewed scopes.
- Use the Paperclip robot account remains an additional Google Sheets-only option for explicitly shared spreadsheets.
Before Google consent, the setup flow asks whether the credential is for just the connecting user or for any human in the company. A personal choice stores the tokens only on that user's grant. A company choice stores them on the default organization grant, while still recording which signed-in Google principal completed consent so refresh and reconnect stay bound to that principal.
Catalog discovery and connection creation use the same signed, instance-specific profile availability. Local enrollment files and Cloud-delivered environment identities follow this same path; neither enables managed methods globally in the static app definitions. Saved connections remain recognizable for OAuth callback, refresh, and revoke, while the broker enforces current profile access. Switching capability or authentication methods preserves the selected credential owner when the new method supports that owner.
Broker profiles
The Paperclip-managed method signs every broker request with one explicit profile. The broker binds that profile into sessions, one-time claims, sealed token envelopes, and refresh. Per-profile removal is local-only for managed Google grants. Google's revocation endpoint can invalidate all grants for the same user and managed client, so Paperclip does not call it while removing one Workspace profile.
| App | Read profile | Write profile |
|---|---|---|
| Gmail | gmail.read |
gmail.draft |
| Drive | drive.read |
drive.write |
| Docs | docs.read |
docs.write |
| Sheets | sheets.read |
sheets.write |
| Slides | slides.read |
slides.write |
| Calendar | calendar.read |
calendar.write |
| Chat | chat.read |
chat.write |
| People | people.read |
— |
| Workspace Search | workspace-search.read |
— |
Every new signed request includes a profile. The Cloud broker rejects a request whose provider, profile, or exact scope set does not match its closed registry.
Instance configuration
All Paperclip-managed Google methods use the existing enrolled-instance keys:
PAPERCLIP_CLOUD_CONNECTOR_BASE_URL=https://my.paperclip.app
PAPERCLIP_CLOUD_CONNECTOR_ENVIRONMENT=production
PAPERCLIP_CLOUD_CONNECTOR_INSTANCE_ID=inst_example
PAPERCLIP_CLOUD_CONNECTOR_SIGN_PRIVATE_KEY=...
PAPERCLIP_CLOUD_CONNECTOR_SEAL_PRIVATE_KEY=...
No per-app client secret is stored on the Paperclip instance for the managed path. For customer-owned OAuth, the setup flow collects that customer's Google OAuth client ID and secret and stores them through the normal instance-vault path.
Cloud-hosted stacks receive these values through the existing per-stack secret
delivery path. A self-hosted instance creates its keys during enrollment and
stores them with owner-only permissions in the instance's ignored secret
directory. The setup page supplies its authenticated same-origin HTTPS address
to enrollment, so a normal Tailscale-hosted self-hoster does not need to edit
config.json or set PAPERCLIP_PUBLIC_URL; the enrolled origin becomes the
durable callback binding. The former PAPERCLIP_ID_CONNECTOR_* values use an incompatible
Paperclip ID protocol and are not read aliases. Enroll with Paperclip Cloud and
reconnect legacy grants before their old access tokens expire.
The gallery requests the broker capability document with a short cache. A Paperclip-managed method is omitted unless its exact profile is enabled at the broker; the independent app card and customer-owned OAuth method remain available. This supports profile-by-profile rollout and rollback without collapsing the nine cards into one app.
See Gmail connection for the detailed enrollment, signing, encryption, environment-isolation, and security review runbook inherited by all profiles.
Safety boundary
Every Google profile has an explicit MCP tool allowlist. Unknown Developer Preview tools default to disabled. Read profiles expose only reviewed read operations. Write profiles add only the reviewed write operations for their app; destructive or unreviewed tools do not become available merely because Google adds them upstream.