Memory
EXTERNAL-SERVICE → WORKSPACE ACCESS: options analysis (Sep 4, 2026, ~1:15pm BST, Perplexity, from cloudflare-os docs + package READMEs ingested same day). QUESTION (Mike): how can an external service make calls to a workspace and/or the gadgets it contains? CORE FINDING: upstream cloudflare-os has NO general service-token/REST API into the Workshop — the frontend speaks Cap'n Web RPC over WebSocket with session auth, and the router only exposes /api/* (session-authenticated) plus /gatekeeper/<name>/*. The designed inbound pattern is: THE GATEKEEPER IS THE INBOUND SURFACE. You never call the workspace directly; an external service calls a gatekeeper's endpoint, and the gatekeeper delivers into the gadget through governed channels. THE FIVE OPTIONS: 1. HOOKS (canonical upstream mechanism) — a gadget exports a WorkerEntrypoint implementing a hook interface (e.g. EmailHook.receiveEmail); the agent wires binding→export via the setBindingHook tool; the gatekeeper stores the hook Fetcher in a DO keyed by resource (e.g. mailbox local-part) and invokes it per event 'via Overseer loopback'. Canonical example: gatekeeper-email — the gatekeeper IS the service (a Cloudflare Email Worker behind Email Routing), parses mail with postal-mime, and calls the gadget's hook with structured data. SECURITY: hooks are 'live write channels into a gadget' — they are inside observer-verification scope (observers.md), so hook-delivered data participates in the sharing invariants. 2. CUSTOM GATEKEEPER HTTP ENDPOINTS + OBSERVATION/ACTION MACHINERY — a gatekeeper worker can expose arbitrary endpoints (OAuth callbacks, connect pages, and startAppUi management UIs already work this way). Map external calls to: reads → recorded as observations (audited, observer-checked); writes → staged→pending→applied through the approval queue (at-most-once apply discipline per mcp-shared/action-store; auto-apply only via user-enabled rules + vetted trust tier). THIS IS THE PATTERN ALREADY BUILT in docuclear_control's ambient sphere gatekeeper (12 reads + 11 queued actions, sphere.capture only auto-approvable, forget/export/etc never agent-reachable — 4b8031cf). 3. SERVE MCP INBOUND — upstream's MCP support is OUTBOUND-only (gatekeeper-mcp: user-pasted endpoints; gatekeeper-mcp-portal: one admin-configured portal; trust boundary in mcp-shared/tools.ts: readOnlyHint→observation, else queued; auto-apply writes needs vetted tier via MCP_PORTAL_TRUST_ANNOTATIONS). Nothing upstream serves a workspace OVER MCP. DocuClear-native build: a gatekeeper-shaped worker serving Streamable HTTP MCP, reusing mcp-shared's OAuth chain/account DO base, tools mapped onto the observation/action machinery. The two-tier trust model (vetted internal vs BYO external) deployed Sep 3 maps directly onto how you'd tier external MCP callers. 4. GIT AS INBOUND CHANNEL (new upstream, #384 merged Sep 3) — external service pushes to GitHub; the agent mounts the repo as a worktree (pure JS/TS in a DO, no containers), edits, commits, pushes back, opens PRs via the GitHub gatekeeper. Code-shaped external interactions are now upstream-supported end-to-end. 5. HUMANS, NOT SERVICES — collaborators/share links (capability at open(), build>use roles, HMAC'd 128-bit share keys, lazy revocation via permission-graph reachability) and public-server mode (auth gatekeepers: Google/GitHub/Cloudflare sign-in, AI Gateway billing) cover external PEOPLE, not service-to-service. ADJACENT SIGNALS: #427 (open, draft) createExternalResource — the other half of requestConnection: agent mints a new vendor resource (first consumer Google Docs) with simulated-until-approved creation. #381 renames prohibitAllSharing→containsRestrictedData. observers.md: adding a binding restarts live sessions so collaborators get re-verified at the new scope — inbound-data governance is actively maintained upstream. DOCUCLEAR SYNTHESIS: the answer composes existing pieces — (a) inbound webhooks/service calls land on purpose-built gatekeeper endpoints (per-service auth: OAuth/token/HMAC); (b) data enters gadgets as hook invocations or observations; (c) mutations queue through the action machinery with the evidence log; (d) for agent callers, serve MCP from a gatekeeper-tier worker under the two-tier trust model. Every inbound path stays inside the gatekeeper trust boundary = the evidence-bay story holds for ingress as well as egress. OPEN DESIGN QUESTION for DocuClear: whether 'external service calls workspace' is a PLATFORM capability (docuclear_control fronts it, like the sphere gatekeeper) or a PER-CUSTOMER-SPHERE capability (each sphere exposes its own inbound endpoint surface) — the sphere-auth open thread (441278e2) gates this.
Tags: cloudflare-os, docuclear, external-access, hooks, inbound, mcp, gatekeepers, design-options, architecture, volatility:state, project:cloudflare-os, kind:episodic — Source: mcp — 2026-09-04 12:16:03 UTC