## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Assistant connections (MCP) let an outside assistant, or another
Paperclip instance, sign in as a person and use the `/mcp/paperclip`
endpoint
> - The feature was behind the experimental `enablePublicMcp` setting.
The setting was off by default and in practice off on Cloud stacks
> - Instance-to-instance work (one person's agent files a task on a
colleague's instance) fails when the receiving instance has the setting
off
> - This pull request moves the feature out of Experimental. It is now
always on, and a stored or Cloud-managed "off" value is ignored
> - The benefit is that every authenticated instance with a public URL,
including Cloud workspaces, accepts assistant connections with no setup
step
## Linked Issues or Issue Description
**Subsystem affected**
Public MCP (`server/src/services/public-mcp/`), instance settings,
Connectors → Assistant Connection (MCP) setup page, Experimental
settings page.
**Problem or motivation**
A remote MCP connector on one instance cannot use another instance's
`/mcp/paperclip` unless an admin on the other instance finds and turns
on an experimental toggle. On Cloud, the toggle is off and is managed by
the fleet. Instance-to-instance delegation therefore does not work by
default.
**Proposed solution**
Remove the gate. Keep `enablePublicMcp` only as a compatibility key, the
same way `enableApps` was graduated: old stored rows, PATCH bodies and
Cloud managed configs still parse, but the effective value is always
`true`.
**Alternatives considered**
An instance-admin kill switch that defaults ON. I did not keep one. Each
person already controls access: a connection exists only after that
person approves OAuth consent for one company, and the person or an
admin can revoke it. Deployment policy (authenticated mode and a valid
public URL) still decides whether the endpoint exists. A second switch
would add a state that can silently break instance-to-instance work
again. A schema migration was also not needed: the value lives in the
`experimental` JSON column, and the stored key becomes inert.
**Roadmap alignment**
Requested by the maintainer to enable instance-to-instance
communication.
## What Changed
- `packages/shared`: `enablePublicMcp` is a deprecated compatibility
key. The schema default is `true`. The feature catalog entry is
"Assistant connections (compatibility)" with both defaults `true`.
- `server` instance settings: normalization always returns
`enablePublicMcp: true`. The Cloud managed overlay skips the key, so a
fleet value of `false` cannot disable it. Removed the key from the Cloud
staging experimental-key list. Removed the client-mirror policy step
that ran only when the toggle changed.
- `server` public MCP: personal discovery, OAuth, tools, setup and event
delivery no longer read instance settings (`isEnabled()` returns `true`
for the personal endpoint without a DB read). Dot, Grok and Muse agent
connections keep their own experimental settings.
- `server` Cloud paths: the client-mirror sync, the hosted event
authority, the ingress-handoff expiry worker and the idle sleep proof
treat the front door as enabled. The warm-standby `503
workspace_unclaimed` behavior is unchanged.
- `server` Dot/Grok gates: they no longer also require
`enablePublicMcp`. Error messages no longer tell people to enable
Assistant connections.
- `ui`: removed the Experimental toggle, the "Enable assistant
connections / Open Experimental settings" block on the Assistant
Connection page, and the "Enable Assistant connections (MCP)" hint in
Dot setup. Updated the Dot and Grok copy.
- Storybook: deleted the Experimental-setting story and removed the
"enable the experiment" step from the journey and presenter.
- Docs: `doc/public-mcp.md` ("Enable an instance", "Start from
Connections", `GET /api/mcp/setup`), `doc/openai-dot-runner.md`,
`doc/idle-grok-dispatch.md`, and the agent-access map.
- Tests: new red/green tests for "enabled with no setting stored" and "a
stored or managed off value is ignored". Removed the tests for the
"disabled" behavior, which no longer exists.
## Verification
- Red/green: with the old source and the new tests,
`instance-settings-readonly.test.ts`,
`instance-settings-service.test.ts` and `public-mcp.test.ts` fail (4
failures, and the public-MCP suite fails in `beforeAll` because
`isEnabled()` was `false` with no setting stored). With the new source
they pass.
- `server`: `public-mcp.test.ts`, instance-settings (readonly, service,
managed overlay), `managed-config`, `cloud-event-authority`,
`events-work`, `dot-runner`, `dot-oauth-onboarding` and
`agent-runtime-assignments`. 354 passed.
- Cloud client-mirror lifecycle
(`client-mirror-lifecycle.postgres.test.ts`, skipped in CI) passed
against a local Postgres 17 with
`PAPERCLIP_MCP_SLEEP_TEST_DATABASE_URL`. 6/6, plus `events-work` 28/28.
- Idle and sleep: `idle-incoming-wake` (service and route),
`idle-deadline-proof`, `idle-incoming-wake-capability`,
`idle-sleep-proof`, `client-mirror-ack`, `recovery-deadline-acceptance`
and `idle-completed-history` pass. The warm-standby test now also
asserts that discovery after the claim does no SQL read.
- `ui`: `InstanceExperimentalSettings`, `AssistantConnection`,
`NewAgentDialog`, `NewAgent` and `ExternalAgentInviteDialog.muse` pass.
267 passed.
- Typecheck: `packages/shared`, `server` and `ui` pass. `node
scripts/check-maps.mjs` passes.
- `pnpm verify`: see the CI checks on this PR.
- After the deploy: confirm
`/.well-known/oauth-protected-resource/mcp/paperclip` and `/mcp/setup`
return 200 on paperclip.staging without changing any setting.
## Risks
- Behavior change: instances that had the setting off now serve
discovery, OAuth and `/mcp/paperclip`. Security invariants are
unchanged: the endpoint is still mounted only in authenticated mode with
a valid public URL, OAuth still needs a real signed-in user's consent,
local implicit board authority cannot approve, and revocation works the
same way.
- Cloud sleep: on a managed stack, the MCP sleep proof blocks sleep
until the client mirror publishes the tenant front door to Cloud. The
client-mirror sync runs at boot and does this once. Stacks that already
had the flag on use this path today. A stack whose Cloud connector
cannot publish the mirror would stay awake. Watch fleet sleep after the
deploy.
- Personal public-MCP requests now read instance settings one time less.
- Fleet admin: the Cloud fleet catalog can still show and set
`enablePublicMcp`. The value is ignored. Removing it from the fleet
catalog is a separate change in the Cloud repo.
- No migration. The `0354` trigger still compares the stored key. That
causes at most one extra connector-runtime invalidation if an old client
writes the key.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use
(shell, file edits, test 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 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
- [x] 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>
10 KiB
Assistant connections (MCP) — agent access
Product map: Assistant connections (MCP).
Feature ID: assistant-connections.
This is a source-reviewed baseline of the public assistant connection boundary. The records distinguish a personal assistant acting as its consenting human from an ordinary Paperclip agent. Review and execute each listed operation before qualifying the complete capability. No live client, consent, or authorization proof is claimed. Follow the map contract.
setup
Capability ID: assistant-connections/setup.
Review: baseline.
API: present — GET /api/mcp/setup for authenticated setup metadata; GET /mcp/setup and GET /mcp/setup.md for enabled public instructions.
Agent access: restricted — an external assistant can read enabled public setup instructions, but authenticated setup management requires a signed-in human session/cloud_tenant source. A Paperclip agent, personal MCP bearer, local implicit board, or human board bearer does not supply that browser identity.
Policy: The configured MCP/authorization origin governs public setup and transport. Authenticated management requires an actual board user from session or cloud_tenant. The copied company hint does not grant membership, scopes, or execution authority. HTTPS is required apart from the defined loopback development exception.
Evidence: source-only — reviewed at 9ef434fe79c57d976b8b03b14c5242db270b8320. Apps setup, public MCP routes, and origin/gate policy.
Verification: not-run — Inspect the invitation/resource/company from a permitted browser, then exercise a remote authorized client call only after separate consent. Reject unsupported management identities and check disabled/unconfigured setup without exposing secrets. Do not count copied instructions as a completed connection.
Gaps: No ordinary-agent self-consent or management path is established. Published plugin distribution, each client’s installation, and hosted interoperability require their own qualification.
consent
Capability ID: assistant-connections/consent.
Review: baseline.
API: present — POST /mcp/oauth/register; GET /mcp/oauth/authorize; GET /api/mcp/requests/{id}; POST /api/mcp/requests/{id}/consent; POST /mcp/oauth/token with authorization-code exchange.
Agent access: restricted — a public client can initiate registration/authorization, but the approval belongs to the real signed-in human. Ordinary agent REST/native call_api cannot manufacture a human session or browser origin to approve itself.
Policy: Public-client authorization uses S256 PKCE, exact callback/resource binding, configured origin, and the live experimental gate. Browser consent requires the authenticated session/cloud_tenant human and a matching configured Origin/Referer. Approval requires active membership in the selected unarchived company; a company hint pins selection. A viewer may approve read only. Granted scopes must be requested and explicitly accepted, and subsequent domain operations retain the person’s current permissions.
Evidence: source-only — reviewed at 9ef434fe79c57d976b8b03b14c5242db270b8320. Public MCP routes, OAuth policy, and consent/device UI.
Verification: not-run — Complete an actual client/browser authorization-code exchange and verify exact person/company/scopes by a remote tool call. Decline or expire another request; reject wrong company/origin/callback/resource/PKCE and scope escalation. A board request without the real consent identity is not acceptance evidence.
Gaps: Source fixtures establish the protocol boundary, not compatibility of every assistant/client callback or hosted signup path. Actual denied/expired browser and client states remain not run.
device-login
Capability ID: assistant-connections/device-login.
Review: baseline.
API: present — POST /mcp/oauth/device_authorization; GET /api/mcp/device with user_code; POST /api/mcp/device/consent; POST /mcp/oauth/token with the device grant.
Agent access: restricted — the device flow lets a configured client wait for human authorization. Its CLI transport does not let a Paperclip agent approve the browser decision or reuse another person’s saved credential.
Policy: Human consent retains the same company membership, viewer/read-only, requested scope, browser-origin, resource, and gate constraints as browser consent. Codes expire and are single-use; polling backoff is persisted. The CLI validates issuer/resource and requires the verification URI at the issuer’s /mcp-device, so its current journey needs matching MCP and authorization origins. It calls paperclip_connection to confirm the approved company before accepting working credentials.
Evidence: source-only — reviewed at 9ef434fe79c57d976b8b03b14c5242db270b8320. Public MCP routes, OAuth policy, and consent/device UI. MCP commands and device/credential client.
Verification: not-run — Complete one real terminal/browser request with explicit company, inspect the approved remote identity, and reuse the saved credential for a bounded read. Reject mistyped/denied/expired/replayed codes, wrong issuer/resource/company, and excess polling without saving an unauthorized credential.
Gaps: Separate authorization-origin support for the CLI is unqualified; the server can return a verification URI that the current CLI rejects. No live CLI device/stdio journey was executed. A credential-transport unit test or local proxy initialization is not proof that the waiting client was authorized.
client-use
Capability ID: assistant-connections/client-use.
Review: baseline.
API: present — POST /mcp/paperclip for MCP tools/list and tools/call. Supported modern request transport also includes server/discover and events/list, events/subscribe, and events/unsubscribe; these are protocol operations, not arbitrary REST endpoints. The private POST /mcp/runner/oauth/cloud-principal identity check is machine-only Cloud control, not an agent entry point.
Agent access: available — a configured external MCP client or the supported CLI proxy acts through the authorizing human’s grant. Each Paperclip native/remote run still needs its own actual admitted client/binding; a personal assistant connection is not automatically an agent tool or credential.
Policy: Every remote call rechecks the experimental gate, resource/client/grant/token status, expiration/revocation, human/company/membership status, scopes, and underlying domain permissions for exactly one company. The public paperclip_call_api tool permits only enumerated capabilities. An MCP bearer cannot authenticate as an ordinary REST board user or agent, and the grant confers no instance-administrator authority. The proxy does not automatically retry writes. The private original-token check requires the existing signed Cloud action, current namespace and the original Dot OAuth restrictions; it creates no board actor or operation permission. See the private authority contract.
Evidence: source-only — reviewed at 9ef434fe79c57d976b8b03b14c5242db270b8320. MCP capabilities, per-call authorization, public MCP routes, and stdio proxy.
Verification: not-run — Prove remote identity, a permitted read and separately authorized additive write with persisted attribution. Assert private/foreign resources, missing write scope, arbitrary call_api operations, disabled gate, membership loss, and misuse of the MCP bearer at ordinary REST. Check actual client discovery rather than a declared scenario tool.
Gaps: Modern event/discovery interoperability, each external client, and all allowlisted capabilities need their own live proof. Local initialize/ping results are not evidence of remote authorization or execution.
revocation
Capability ID: assistant-connections/revocation.
Review: baseline.
API: present — GET /api/mcp/connections; DELETE /api/mcp/connections/{id}; POST /mcp/oauth/revoke for client/token/resource-bound OAuth revocation.
Agent access: restricted — browser management lists/revokes the real signed-in person’s grants. Ordinary agent/local-implicit/MCP bearer identities cannot use that human-management API; a client can revoke only a correctly bound OAuth token.
Policy: Management requires the session/cloud_tenant board user; mutations require the configured browser origin. List/delete are restricted to the current person. Another person’s ID can be a silent no-op. OAuth revocation binds token, client, and resource. Human list/revoke management remains available while enablePublicMcp is off, though remote tool calls do not. Already-delegated work retains its ordinary task lifecycle.
Evidence: source-only — reviewed at 9ef434fe79c57d976b8b03b14c5242db270b8320. Connection management, Apps management, management routes, and grant ownership/revocation.
Verification: not-run — Make a remote read succeed, revoke as the grant owner, and reject the same credential afterward. Check persisted list state, another person’s untouched grant, membership loss, disabled transport with reachable management, and OAuth token/client/resource binding. Verify task cancellation separately if required.
Gaps: Revocation is not remote-provider termination or task cancellation. The account-wide management page lacks the component coverage named by the current-company recipe. No ordinary-agent delegated human-management path or live client revocation proof is claimed.