How agents and people edit the same page at once: a remote MCP server on Durable Objects and Yjs

Coding agents excel at creating collaborative projects, but sharing those creations can be challenging. Claude's artifacts reside within a Claude.ai account, and other agents lack a comparable setup. When a teammate seeks to modify a sentence, you must revert to HTML manipulation. To address this issue, I developed blink artifacts: any MCP client can publish a page using remote MCP, granting a single link for simultaneous edits by multiple users. This article delves into the more complex aspects of blink artifacts.

Each artifact is represented by a Cloudflare Durable Object that houses a Yjs document. Browser editors, such as CodeMirror for HTML, ProseMirror for documents, and a canvas for slides, synchronize with the Yjs document via WebSocket connections. The Durable Object utilizes WebSocket hibernation, ensuring that idle artifacts incur no costs while sockets remain open. The agent remains oblivious to Yjs.

MCP communicates with the artifact through plain files: index.html, doc.md, and individual HTML files for each slide. The agent retrieves the Yjs state and converts it into text; subsequently, it applies a text diff back into the shared document within the same Durable Object. This approach treats a human typing and an agent writing as two clients of one CRDT. The D1 durable object manages accounts, artifacts, members, tokens; R2 stores uploaded files, and the artifact's own Durable Object storage holds version history.

Conflicts arise when an agent's file view is outdated: a person may have altered it since the agent last read it. Consequently, write tools reject edits rather than attempting to overwrite. Edit_file accepts precise find/replace pairs; if the text matches no locations, it returns no_match; if it matches multiple locations, it returns multi_match.

In either scenario, no modifications are made, prompting the agent to re-read the file. write_files accepts an optional baseRev parameter; if any touched file has changed since that revision, it returns conflict with the affected paths, necessitating a merge rather than a straightforward overwrite.

Changes_since(rev) returns only what has changed since a specified revision, allowing agents to retrieve a diff instead of the entire page after the team has made edits. This proves more crucial than the CRDT itself, as Yjs ensures concurrent edits converge but does not endorse an agent's overwrite of a recently altered paragraph.

When dealing with untrusted HTML on its own origin, published pages consist of arbitrary HTML and JavaScript, never running on the app's origin. Each artifact is served from its own subdomain on a distinct domain, identified by a secret that is rotated upon access changes, within a sandboxed iframe. The page lacks cookies and credentials.

To access shared state (a small database, comments, the viewer's identity), the page communicates with the parent window via postMessage, and the shell executes the API call with the viewer's specific role. Agents, without relying on a server-side LLM, can process user queries: select an element, type @ and choose an agent. The question waits in the artifact's Durable Object until the owner's own agent retrieves it (via background listener or long-polling asks_wait), answers it in a comment or integrates the answer into the document block, and resolves the query. The answering agent is the one you already compensate for and already trust with your code.

Claude.ai connects to blink artifacts via OAuth, eliminating the need for tokens. Claude Code, Codex, Copilot CLI, Antigravity, and claude.ai custom connectors rely on OAuth, making the server also its own OAuth 2.1 authorization server: protected-resource and authorization-server metadata, dynamic client registration, PKCE (S256), short-lived access tokens, and rotating refresh tokens—all hosted on D1.

Signing up for claude.ai involves visiting https://artifact.blinkbrosai.com/mcp under Settings → Connectors, entering an email code, and approving the connection—all without requiring a card. The service offers free access to three active artifacts, with no credit card information required. Setup guides for Claude Code, Codex, Copilot CLI, Antigravity, and claude.ai are available in the documentation.

I constructed most of the system using Claude Code: I authored the acceptance tests first, enabling Claude to generate most of the implementation, which I subsequently reviewed and fine-tuned. Should you have any questions regarding the components mentioned above, or if you encounter any issues, I am eager to assist.