mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-19 07:42:38 +01:00
## 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>
55 lines
4.1 KiB
TypeScript
55 lines
4.1 KiB
TypeScript
import { and, eq, isNull } from "drizzle-orm";
|
|
import { agents, dotAgentBindings, mcpOauthGrants, type Db } from "@paperclipai/db";
|
|
import { canConfigureAgentConnection } from "../modules/agent-lifecycle/index.js";
|
|
import { accessService } from "./access.js";
|
|
import { boardAuthService } from "./board-auth.js";
|
|
import { instanceSettingsService } from "./instance-settings.js";
|
|
import { McpOAuthError, type McpPrincipal } from "./public-mcp/oauth.js";
|
|
|
|
export async function externalBotEnabled(db: Db, provider: "openai_dot" | "grok_bot", queryOwner?: Pick<Db, "select">) {
|
|
const settings = instanceSettingsService(db);
|
|
const experimental = queryOwner
|
|
? await settings.getExperimentalReadOnly(queryOwner)
|
|
: await settings.getExperimental();
|
|
return provider === "openai_dot" ? experimental.enableOpenAiDot : experimental.enableGrokBot && experimental.enableNativeRunner;
|
|
}
|
|
|
|
/** Persistent agent authority, distinct from task/run authority enforced by the broker. */
|
|
export async function authorizeExternalBotBinding(db: Db, principal: McpPrincipal, options: {
|
|
requireReady?: boolean; allowPaused?: boolean; provider?: "openai_dot" | "grok_bot";
|
|
} = {}) {
|
|
const requireReady = options.requireReady ?? true;
|
|
if (principal.grant.purpose !== "agent" || !principal.grant.scopes.includes("paperclip:agent")) {
|
|
throw new McpOAuthError("access_denied", "Use a dedicated external-agent connection.", 403);
|
|
}
|
|
const [binding] = await db.select().from(dotAgentBindings).where(and(eq(dotAgentBindings.grantId, principal.grant.id),
|
|
eq(dotAgentBindings.companyId, principal.grant.companyId), isNull(dotAgentBindings.revokedAt)));
|
|
if (!binding || (options.provider && binding.providerKind !== options.provider)
|
|
|| (requireReady && binding.status !== "ready")) throw new McpOAuthError("access_denied", "Connect this agent and complete its wake verification first.", 409);
|
|
if (!await externalBotEnabled(db, binding.providerKind)) throw new McpOAuthError("access_denied", "This external provider is disabled.", 409);
|
|
const [grant] = await db.select().from(mcpOauthGrants).where(and(eq(mcpOauthGrants.id, principal.grant.id), isNull(mcpOauthGrants.revokedAt)));
|
|
const [agent] = await db.select().from(agents).where(and(eq(agents.id, binding.agentId), eq(agents.companyId, binding.companyId)));
|
|
const access = grant ? await boardAuthService(db).resolveBoardAccess(grant.userId) : null;
|
|
const membership = access?.memberships.find(m => m.companyId === binding.companyId && m.status === "active");
|
|
if (!access?.user || !membership || membership.membershipRole === "viewer" || !grant || grant.agentId !== binding.agentId || !agent
|
|
|| agent.adapterType !== "paperclip_runner" || agent.adapterConfig.provider !== binding.providerKind
|
|
|| ["terminated", "pending_approval"].includes(agent.status)
|
|
|| (!options.allowPaused && (requireReady ? agent.status === "paused" : !canConfigureAgentConnection(agent)))) {
|
|
throw new McpOAuthError("access_denied", "Agent connection authority is unavailable.", 409);
|
|
}
|
|
if (binding.providerKind === "grok_bot" && agent.adapterConfig.externalBindingId !== binding.id) throw new McpOAuthError("access_denied", "This agent connection was replaced.", 409);
|
|
if (binding.providerKind === "grok_bot") await authorizeExternalBotOperator(db, binding.companyId, binding.operatorId);
|
|
return binding;
|
|
}
|
|
|
|
export async function authorizeExternalBotOperator(db: Db, companyId: string, operatorId: string) {
|
|
const access = await boardAuthService(db).resolveBoardAccess(operatorId);
|
|
const membership = access.memberships.find(m => m.companyId === companyId && m.status === "active");
|
|
if (!access.user || !membership || membership.membershipRole === "viewer") throw new McpOAuthError("access_denied", "Sign in with permission to manage this agent.", 403);
|
|
const decision = await accessService(db).decide({ actor: { type: "board", source: "session", userId: operatorId,
|
|
companyIds: [companyId], memberships: [membership], isInstanceAdmin: false },
|
|
action: "agents:create", resource: { type: "company", companyId } });
|
|
if (!decision.allowed) throw new McpOAuthError("access_denied", decision.explanation, 403);
|
|
return access;
|
|
}
|