## 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>
33 KiB
Public Paperclip MCP connection
The first-release implementation connects an external assistant as a person to one explicitly selected company. It exposes first-party task operations and keeps normal Paperclip authorization, scheduling, attribution, budgets and approvals. The existing named agent gateways and native runner checks remain separate. The accepted roadmap is in the implementation plan.
Enable an instance
Assistant connections are on for every authenticated instance with a public URL, including Paperclip Cloud workspaces. There is no setting to turn on. Apply database migrations with the normal instance upgrade workflow.
Use the instance's configured authentication public URL, or explicitly set:
PAPERCLIP_PUBLIC_URL=https://YOUR-PAPERCLIP-HOST
The retired PAPERCLIP_PUBLIC_MCP_ENABLED variable has no effect. The former
experimental enablePublicMcp setting is a compatibility key only: stored, patched
and Cloud-managed values are accepted but ignored, so an old "off" value cannot
disable discovery, sign-in, tools or event delivery. To stop an individual
assistant, revoke its connection. OpenAI Dot, Grok Bot and Muse agent connections
keep their own experimental settings.
The URL must be an origin without a path, credentials, query or fragment. HTTP
is allowed only for localhost/loopback development. Use authenticated deployment with real user accounts and company
memberships; local implicit board authority and agent/board API keys cannot
approve user OAuth connections. Configure TRUST_PROXY correctly at your edge.
The endpoint is POST /mcp/paperclip, using stateless Streamable HTTP with JSON
responses. GET/SSE sessions are unnecessary. Each invocation verifies its bearer
token again; normal API endpoints do not accept these OAuth tokens. Public
installation requires a reachable HTTPS deployment. Private self-hosted
instances require a directly reachable endpoint; no managed relay is included.
Unclaimed Cloud warm-standby instances return 503 workspace_unclaimed for MCP
setup, discovery and protocol requests without reading the database. The event
poller also stays idle until the instance is claimed. After claim, both resume
without a restart and remain subject to normal authorization.
Start from Connections
Inside your organization, open Connectors → Assistant Connection (MCP) → Set up. This connects an outside assistant to Paperclip using your human account; no agent is selected or impersonated.
Click Copy invitation to copy the message and preview it in the shared animated
setup prompt, then paste it into your assistant. Client-specific instructions are
under Set up manually, in the icon-labeled tab bar. The invitation’s public
setup link contains an optional organization ID,
never a credential. It does not reveal the organization before sign-in or grant
access. Approval happens when the assistant starts its connection. The setup page
is server-rendered at /mcp/setup; /mcp/setup.md and Accept: text/markdown
provide the same version-aware instructions for assistants without browser access.
Set up manually contains commands for Codex, Claude Code, OpenCode, browser
connectors and headless clients. Browser clients may require adding a connector
in their settings; reading an invitation cannot install one. A running client may
need a restart or a fresh conversation to load its tools. Verify the organization
with paperclip_connection before doing work. Keep existing client configuration,
and use a distinct server name when another Paperclip instance is already present.
For OpenCode, merge the displayed mcp.paperclip entry into your project’s
opencode.json, run opencode mcp auth paperclip there, approve the organization,
then start opencode web. Restart an already-running OpenCode after authentication.
An assistant invoking authorization through a shell tool must keep the command
alive in a persistent terminal or background process and share its approval URL
immediately. OpenCode's callback deadline still applies: a URL from a timed-out
command cannot complete sign-in. Start a fresh request, or have the user run the
command in their own terminal if the host cannot preserve it across turns.
Never add upstream model keys to the MCP URL or config; the assistant’s model connection is configured separately.
Consent names the client when available and shows its identifying URL with a site icon. The first available organization is selected initially; requested write access starts checked when the selected role permits it. Changing organization or refetching does not undo a write-access opt-out. Nothing is authorized until Connect organization is clicked. Organization creation stays outside consent.
Return to the same Connections entry to see your connected assistants, their
read/write access, and revoke access. The list refreshes after consent and only
shows your active grants for the selected organization. Each connection shows your
profile avatar and defaults to a name such as “Dotta’s Codex connection.” Revoked
connections disappear from the list; their audit records remain. The legacy
/assistant-connections URL remains available for account-wide management.
GET /api/mcp/setup returns enabled: true (kept for older clients), the
canonical endpoint, invitation URL and copyable invitation to
authenticated browser/Cloud users. It cannot grant
access, accepts no destination URL, never reflects forwarded hosts, and is not
available to agent keys, MCP bearer tokens, or implicit local authority.
Connect an assistant directly
Once the instance is reachable, an existing team member can connect without a store listing. For Codex CLI:
codex mcp add paperclip --url https://YOUR-PAPERCLIP-HOST/mcp/paperclip
codex mcp login paperclip --scopes paperclip:read,paperclip:write,paperclip:configure,offline_access
For Claude Code:
claude mcp add --transport http paperclip https://YOUR-PAPERCLIP-HOST/mcp/paperclip
Open Claude Code's /mcp menu and authenticate the Paperclip server. Both flows
open browser sign-in and consent: review the selected organization (or choose one for a direct instance connection) and review the write-access checkbox. It starts checked when the assistant requests
writes and your organization role allows them; uncheck it for read-only access. Read-only consent cannot delegate work.
Ask the assistant to identify the connected organization and list its agents, then ask
it to delegate a small task to an available agent. The returned task link is the
durable reference. In a later conversation, ask for that task's progress and
report. Configure the agent's provider credentials, execution environment and
budget in Paperclip before expecting it to run; the assistant connection does
not supply them. Revocation is available at /assistant-connections.
The optional workflow packages teach team review, delegation and result retrieval. Build them for the same endpoint before installing locally. Public ChatGPT/Codex and Claude directory installation requires the separate deployment and submission work below.
Headless device login and stdio bridge
With a CLI build that includes this feature:
paperclipai mcp login --device --url https://YOUR-PAPERCLIP-HOST/mcp/paperclip
paperclipai mcp proxy --url https://YOUR-PAPERCLIP-HOST/mcp/paperclip
Add --company <organization UUID> to login to restrict the consent choice.
Login prints a human verification URL and code. Open that URL, sign in, compare
the code, and approve or decline. The private device code and issued tokens stay
inside the CLI. Configure the second command as a local stdio MCP server in a host
without native device support. Do not copy tokens into chat or MCP configuration.
The CLI stores credentials separately under $PAPERCLIP_HOME/mcp (default
~/.paperclip/mcp), with a private directory and files, atomic replacement and a
cross-process refresh mutex. It forwards only to the exact bound resource and
rejects redirects. A failed write is never retried automatically because it may
already have completed. Revoke access from Connections when finished.
The device endpoint is /mcp/oauth/device_authorization, browser verification is
/mcp-device, and the token endpoint accepts the RFC 8628 device grant. Pending
requests have separately hashed codes, ten-minute expiry, five-second initial
polling, persistent backoff and atomic redemption. Shared database quotas bound
new requests. Consent uses the same company, role, scope, grant, audit and
revocation checks as browser OAuth. This is human authorization, not client
credentials or agent impersonation.
Tenant Cloud gateways forward setup and device protocol requests without browser cookies. Browser approval remains authenticated. The central directory broker does not advertise device or CIMD support until separately implemented.
Identity and consent
- Protected-resource discovery:
/.well-known/oauth-protected-resource/mcp/paperclip. - Authorization-server discovery:
/.well-known/oauth-authorization-server. - Public-client registration:
/mcp/oauth/register. - Authorization, token and revocation endpoints:
/mcp/oauth/authorize,/mcp/oauth/token,/mcp/oauth/revoke. - Browser consent:
/mcp-connect/:requestId. - User connection management:
/assistant-connections.
Consent identifies the registered client and its identifying origin. Client names are self-reported; verify the receiving domain before approving an unexpected request. The hosted organization chooser also identifies the original client and callback origin before its tenant handoff.
An uncached remote client-metadata lookup consumes a database-backed admission receipt before fetching: at most 60 attempts per instance and six per source per rolling minute, shared by browser and device authorization across server replicas. Receipts store only a source hash and expiry, and failed lookups or mismatched redirects still consume the quota. Invalid resources and scopes are rejected without fetching. The network request runs after the admission transaction commits, so slow clients cannot hold its database lock. Reusing already-validated metadata within its cache lifetime consumes no fetch capacity, so clients shared by users behind one proxy do not charge the same lookup on every connection.
Client ID Metadata Documents (CIMD) and dynamic registration both support public
clients. CIMD uses an HTTPS client ID URL with an exact matching client_id,
required registered redirects, a 32 KiB response limit, a bounded cache, and
guarded DNS/HTTP fetching that rejects private networks and redirects. Supplied
names are not proof of a brand identity. Client documents can list capabilities
used with other servers; Paperclip retains only its implemented grants. Extra
capabilities such as Claude web’s JWT-bearer grant do not enable that grant here.
Verified native loopback callbacks may vary only their port; the exact authorized
callback remains bound to code redemption. Authorization responses include iss.
Resource metadata advertises resource scopes; refresh capability is advertised
in authorization-server metadata.
Dynamic registration uses public clients, exact registered HTTPS redirect URIs
(or HTTP loopback), authorization code flow, S256 PKCE and exact resource
binding to the endpoint. Authorization requests expire in ten minutes; codes
expire one minute after consent and are single-use. Access tokens expire in
fifteen minutes. offline_access issues a thirty-day rotating refresh token for
personal assistant connections. Dedicated Dot agent connections instead receive
rotating refresh tokens without an inactivity expiry: they stay connected until
revoked or their agent/operator loses access. Migration 0319_heavy_captain_midlands.sql
removes the old expiry from valid, unused Dot refresh tokens on unrevoked grants.
Expired credentials remain expired.
Replaying a consumed refresh token still revokes its entire grant. Tokens and codes
are hashed at rest. paperclip:read is required; paperclip:write adds only task
work and attachment mutations on direct connections. The paperclip:configure
scope covers allowed configuration operations. One Write all of your Paperclip
data consent checkbox approves both requested mutation scopes. Scope expansion
requires a new consent flow; the directory broker retains its original operations.
Each grant records the person, client, company, resource and scopes. Membership and company availability are rechecked at execution. Instance admin status does not elevate a grant beyond that company's role. Consent/revocation require an authenticated browser and the configured origin. Client registration does not fetch redirect URLs or accept arbitrary tool destinations. Rate limiting at the public edge is required in addition to the bounded per-process auth limiter. Registration also has a database-enforced limit of 60 new clients per minute and 10,000 unconsented clients shared across replicas. Expired authorization requests and never-consented clients older than one hour are collected during registration. Clients with grants are retained, preserving their connections and audit/mutation history.
Revocation blocks future calls; it does not cancel already delegated work or undo in-flight mutations. Manage existing tasks and execution in Paperclip. Audit records identify the human caller and connection/client for mutations. OAuth credential bodies and redirect locations are redacted from HTTP logs.
Original directory tool surface
| Tool | Effect |
|---|---|
paperclip_connection |
Person, company, scopes, connection management link |
paperclip_list_agents |
Safe agent summary and availability |
paperclip_list_people |
Active human members: user ID, name and role (no email) |
paperclip_list_projects |
Safe project summary |
paperclip_search_tasks |
Bounded task search with offset pagination |
paperclip_read_task |
Current task plus recent comments/history |
paperclip_create_task |
Task for an agent, a person or no one; only an agent assignee is scheduled |
paperclip_add_comment |
Human feedback; may wake or queue work |
paperclip_list_deliverables |
Documents, attachments and work-product references |
paperclip_read_document |
Durable document body and current revision |
paperclip_pending_approvals |
Pending approvals and existing decision links |
paperclip_create_task takes at most one of assigneeAgentId and
assigneeUserId, the same fields as the REST issues API; passing both is a
validation error. An agent assignee is submitted to normal scheduling and may
start a run that spends the company's budget. A person (a userId from
paperclip_list_people) or no assignee creates a todo task without waking any
agent, so a connection from another Paperclip instance can file work without
spending the receiving company's budget. A person outside the company is
rejected by the normal REST assignment check, identically to an unknown user ID.
Every company-scoped call requires its explicit authorized company ID. The server emits bounded projections without upstream credentials. Direct connections can read the allowed operating configuration through the expanded tools below. URLs include the company's prefix so unrelated browser company selection cannot redirect the user to a different team's approval interface.
Writes require a UUID requestId, unique per intended action. A durable receipt
is reserved before dispatch, keyed by person, company, operation and request ID (with the originating grant recorded for audit). Matching
retries, including after a new authorization grant, replay the recorded result; changed arguments are rejected. A concurrent
or unconfirmed result is reported as outcome: unknown. Inspect the task and
comments before another action; never retry with a new ID to force success.
A known HTTP rejection is recorded and replayed as outcome: rejected.
The REST bridge dispatches only paths constructed by the closed tool catalog, with a request-local verified actor. Existing handlers enforce all domain checks and own their transaction/scheduling semantics. Receipts do not turn existing asynchronous scheduling into an exactly-once execution guarantee. Creating a task is not proof that an agent started or finished it.
Hosted onboarding and release gates
Create a hosted organization through Cloud before approving a connection. Provisioning, mission/template selection, model credentials, execution capacity and spending remain owned by Cloud. Installing a plugin never provisions a company or starts paid agents.
This repository implements the instance-side connection and vendor packages. The companion Cloud implementation supplies the stable public resource, an account-to-stack OAuth broker, explicit organization selection and a return from hosted organization creation. Its public connection screen resumes normal sign-in, lists authorized organizations, reports provisioning/sleeping states, and links to tenant setup for mission, templates, execution and spending.
The Cloud broker forwards the original PKCE challenge to tenant OAuth, validates the resulting person, and wraps tenant credentials in encrypted tokens bound to client, workspace and resource. Every call rechecks current Cloud membership and verified routing; the tenant rechecks company permissions and revocation. Cloud stores request metadata and code hashes, not raw tenant tokens. Unknown mutation outcomes preserve the existing request-ID receipt contract.
Deploy both sides before hosted use. Cloud's tenant front door forwards only exact discovery, OAuth protocol and MCP paths without minting human authority; consent and management retain normal browser entry. The Cloud broker remains opt-in and requires its own durable OAuth state and encryption key from the provider secret store. Installing these source packages does not deploy an endpoint, open signup, register a listing, or provision execution capacity.
Before release, exercise actual ChatGPT/Codex and Claude connections against a staging HTTPS deployment, including client registration, consent, refresh, revocation, reconnect, task delegation and retrieval from another conversation. Prove scheduled execution on a controlled agent and the new-user Cloud return journey. Local OAuth interoperability has been verified with Codex CLI 0.153.4 and Claude Code 2.1.245, using disposable Cloud/tenant fixtures. Protocol tests, CLI login and local package validation do not replace these release gates.
External sessions acting as agents, task leases and third-party granted tools remain the second/third releases; do not add generic executors to this public catalog to implement them.
Registration also enforces shared source quotas (6 per minute and 30 unconsented clients) using a resource-bound hash of the trusted request IP; raw addresses are not stored. Configure trusted proxies correctly. Authorization starts atomically remove expired requests and enforce 10 pending-consent requests per client and 1,000 instance-wide, independently of further client registrations. Existing grants remain usable when anonymous registration or authorization is throttled.
Private Dot original-token authority
POST /mcp/runner/oauth/cloud-principal is a machine-only Cloud-to-tenant
identity check for the existing assistant-connections/client-use boundary.
It is not an agent-facing REST/MCP tool, a consent endpoint, or a board-control
operation. Normal hostname, runtime-claim and unclaimed-standby checks run
before principal resolution. The route uses the same normally constructed Dot OAuth owner; an
absent owner or current namespace fails closed.
The caller needs an existing Cloud signature for the closed
mcp-dot:principal action and the original Dot access token. The existing
signature/nonce verifier applies, with at most a 60-second action lifetime.
The request ID binds a UUID and the SHA-256 digest of this ordered, UTF-8 JSON
field tuple:
["paperclip-dot-original-principal-v1", "mcp-dot:principal", expectedInstanceId,
canonicalVerifiedResource, upstreamClientId, selectingUserId,
requestedCompanyId ?? null, accessToken]
This covers every accepted body field, independent of JSON property order.
The raw request is limited to 16 KiB; compressed bodies, invalid UTF-8, malformed
JSON and unknown fields are rejected. The resource must be the current origin's
/mcp/runner. The stack, claim, instance, origin and connector identity must
remain current before and after the OAuth call. OAuth authenticates the original
token once and retains its client, selected user, company, purpose, scope,
membership and feature checks. The reply contains only the checked user,
company, grant, client, resource and agent-purpose identity. It creates no board
actor, grant, agent binding or execution authority.
The original token and signed request remain credentials. Request/response headers, bodies, raw buffers, query data and reflected errors must not enter logs on accepted or refused paths. The application uses a closed log projection for this reserved path, including malformed variants; operators must keep the same restriction at proxies. The Cloud caller requires the already verified current instance and HTTPS tenant route, refuses redirects, and checks the bounded reply and current namespace again.
This private boundary does not advertise or enable a hosted Dot profile, grant anonymous wake authority, or change Personal MCP. Hosted discovery, wake, capability, operation, event, retry/reactivation and revocation lifecycles and Muse integration remain separate requirements. A controlled local HTTP proof does not establish durable Cloud server bootstrap or a deployed provider path.
Task monitoring with MCP Events
The same authenticated endpoint now supports MCP 2.0 (2026-07-28) alongside
legacy MCP. It advertises events through server/discover and implements
events/list, events/subscribe, and events/unsubscribe. MCP 2.0 requests
include matching MCP-Protocol-Version/Mcp-Method headers, per-request version
and client-capability metadata, and Mcp-Name for tool calls. Existing
initialize-based direct clients receive the same expanded tool catalog. The central
directory broker keeps its original ten-tool connection.
| Event | Required filters | Payload |
|---|---|---|
paperclip.task.status_changed |
companyId, taskId; optional statuses |
Task ID, status, company ID and task link |
paperclip.task.comment_created |
companyId, taskId |
Task/company IDs, comment ID and task link |
paperclip.task.document_updated |
companyId, taskId |
Task/company IDs, document key, revision and task link |
In an Events-capable ChatGPT Work Cloud chat or dot, ask, for example: “Watch this task. When it finishes, read its report and tell me the result.” The host supplies a callback URL and signing secret and owns refresh/unsubscribe. Rescan the plugin's MCP server to discover the event catalog. Installing or connecting alone does not start monitoring. Claude and other clients without Events support can continue retrieving results through the read tools.
Callback and hosted-authority verification reserve durable capacity before any remote request. Across replicas, at most 2 verifications per grant, 8 per company and 32 per instance can run concurrently. Attempts are bounded to 30 per grant, 200 per company and 1,000 per instance per minute, including failed verification. New monitors reserve subscription quota before verification; leases expire after one minute. Network waits hold no database transaction, and expired, cancelled or revoked requests cannot finalize a subscription.
Delivery uses a verified HTTPS callback, Standard Webhooks HMAC signatures, public-address DNS pinning on every connection, and no redirects. Callback URLs, current/previous signing keys and hosted authorization proofs are encrypted with the existing instance secrets master key. Back up that key with the database. Callback bodies contain bounded references, not comment/document text; clients must read current authorized state before responding or taking an action.
Subscriptions last at most 24 hours (default), with a 30-second minimum. Hosted
subscriptions last at most five minutes and never outlive the broker access
proof: refresh the OAuth token before refreshing a subscription when necessary.
The tenant verifies that proof through the fixed PAPERCLIP_CLOUD_API_ORIGIN
broker before each delivery, checking current Cloud membership as well as local
company membership, grant revocation and task access. A compatible Cloud broker
must be deployed first for hosted Events. Direct connections to a Cloud tenant
without a broker authority proof cannot create event subscriptions.
Subscriptions and delivery receipts persist across restarts. Activity is scanned without a moving timestamp high-water mark; unique receipts prevent duplicate queue entries and concurrent workers claim deliveries atomically. Delivery is at least once, with up to six attempts and exponential backoff. IDs stay stable across retries while signatures receive fresh timestamps. HTTP 410 stops a monitor; 413 and other permanent failures are not retried. Secret rotation signs with both keys for five minutes. Expired subscriptions and their receipts are removed on the next admission or after seven days; active quotas are 20 per grant, 100 per company and 1,000 per instance. Unsubscribe frees the subscription and its receipts.
This release returns cursor: null: it does not offer protocol replay after an
expired/stopped subscription. Use task history and document tools to recover
missed changes. In-flight requests may finish during unsubscribe/revocation;
subsequent attempts recheck access. Events are data, and may be duplicated or
out of order. Do not post comments merely to acknowledge comments or documents,
which would risk a feedback loop. Approval decisions remain in Paperclip.
See OpenAI's MCP Events guide for currently supported client surfaces. Actual staging ChatGPT subscription, plugin rescan and event-triggered response are still deployment acceptance gates; local protocol and paid model tests do not establish store/UI readiness.
Storybook previews
Run pnpm storybook and open the Assistant connections group. The stories
render the production consent and connection-management pages,
including read-only roles, loading, empty, unavailable, pending, revoked, and
failed-save states. Interactive stories verify organization-switch consent reset,
revocation, and settings rollback. All MCP actions use per-story in-memory
fixtures; no credentials are issued and no work is delegated.
The Cloud repository's web Storybook has Assistant connections / Hosted
connection for sign-in, organization selection, and the create-and-return
flow. OAuth redirects between the two services remain mocked in these previews.
Guided assistant walkthrough
Open Assistant connections → Start here → Guided walkthrough for a presenter-led story about Alex connecting Acme Research. Each step explains where Alex is, what to try, what happens next, and a question to discuss. Next/Back and numbered chapters control the explanation independently of the interactive product preview; Reset this screen restores that step’s fixture. Each screen starts fresh, so sample state does not persist between chapters.
The Cloud walkthrough covers sign-in, choosing or creating an organization, readiness, and the handoff. The Paperclip walkthrough covers organization consent, example delegation and retrieval conversations, and revocation. Assistant conversations are explicitly illustrative; product screens use isolated service fixtures. No paid work or real OAuth runs here.
Local cross-links expect Paperclip Storybook on port 6106 and Cloud on 6107. The default scripts use port 6006; launch these in separate terminals with explicit overrides:
# From the Paperclip repository's ui/ directory:
pnpm exec storybook dev --port 6106 --config-dir storybook/.storybook --no-open
# From the paperclip-cloud repository's web/ directory:
npm run storybook -- --port 6107
When published elsewhere, open the companion Storybook separately. Each walkthrough works independently. Navigation check is a separate interaction story so the presentation itself never advances automatically.
One organization from Cloud through consent
Cloud selects an organization once and sends its registry company ID as the
optional OAuth company_id parameter. Paperclip persists it as
mcp_oauth_requests.requested_company_id, filters the consent response to that
company, and rejects approval for any other company even if the user belongs to
both. It is a scope restriction, never a substitute for active membership or
explicit read/write consent. A deleted, archived, or inaccessible company cannot
fall back to another one. The UI shows the fixed organization and permissions,
with cancel/reconnect guidance if it is unavailable.
Direct instance requests without company_id retain their organization picker.
There is no separate “team” entity in this flow. Cloud’s organization maps to its
stack’s primary Paperclip company; the stack is hosting infrastructure. The hosted
walkthrough uses Consent → Hosted organization; direct selection, read-only,
and unavailable-organization variants remain separately inspectable.
Apply the additive nullable request-column migration before running this tenant version, and deploy tenant support before the Cloud broker that sends the binding. Existing direct requests and grants are unchanged.
Expanded direct assistant tools
Direct instance connections expose 37 explicitly registered operations. The central
public directory broker retains its original ten tools and rejects expanded calls.
Sharing a setup link conveys no authority. Consent has one Write all of your Paperclip data checkbox,
checked by default for eligible roles. It approves the requested work and
configuration scopes together; unchecking it grants read-only access. Clients must
request paperclip:configure to configure agents, projects and skills. Existing
write connections do not acquire this scope, including after refresh; reconnect
with the expanded scopes to approve it.
Normal Paperclip permissions are required in addition to the connection scope.
- Work (
paperclip:write): update, finish or block tasks; write Markdown documents; register or update deliverables; upload attachments. Assignment and status changes can schedule agents. Pending execution reviews must be decided in Paperclip. - Configuration (
paperclip:configure): edit existing agents, model/budget and existing connection bindings; edit instructions; create/update projects and choose accessible repositories; create/update organization skills and their files. Credentials, execution commands, policies and agent creation are excluded. - Reads (
paperclip:read): task/document history, agent instructions, skill files, accessible repository choices and attachment downloads. Native domain read permissions still apply. Revision IDs from reads are required for content edits.
paperclip_search_api describes the same allowlisted named operations and their
schemas. paperclip_call_api takes an operation identifier and validated arguments.
It cannot accept an arbitrary URL, REST path, credential or actor override. Both
interfaces share scope checks and mutation receipts. Reuse the same request UUID
and arguments after a timeout. An unknown result means execution is uncertain;
inspect current state or retry that identity instead of starting another action.
To attach a video, compute its byte size and SHA-256, then call
paperclip_get_upload_url with its task, filename, content type and request UUID.
PUT the exact bytes using the returned Content-Type. Success returns the saved
attachment immediately; there is no completion call. Recover a lost response
by repeating the upload or requesting its URL with the same identity. Conflicting
bytes are rejected. paperclip_list_deliverables includes attachments, documents
and work products; paperclip_get_download_url downloads one authorized attachment.
Replacing a binary deliverable uses a new attachment and updates its reference.
File URLs are ten-minute, transfer-specific credentials: keep them out of chat and logs. Only their hashes are stored. Use host HTTP/file tools to send/receive bytes; if unavailable, upload/download through the Paperclip task page manually. The server never fetches a supplied remote URL or reads a supplied local path. Existing file type and size limits apply (10 MB default). Grants, membership, organization and write authority are checked again during transfer. Revocation prevents future use, including of previously issued file URLs. Expired pending storage is cleaned on subsequent transfer requests; completed attachments remain durable. Cloud deployments also need the narrowly scoped transfer proxy.
Instruction edits require a managed instruction file with a current revision/hash.
The legacy promptTemplate.legacy.md entry has no version protection, so MCP
rejects edits to it with MCP_LEGACY_INSTRUCTIONS_UNVERSIONED. Migrate the legacy
prompt to a managed instruction file in Paperclip first; native runner behavior
is unchanged.
Client-side tool approval remains separate from OAuth consent. For example, a noninteractive Codex invocation that forbids tool approvals may read successfully but refuse a write. Approve the intended tool in the host rather than weakening server permissions. The qualification record distinguishes paid model tests, actual-client proof and staging verification.