agentsync-remote

Part of the xylem stack.

A Cloudflare Worker MCP server that makes claude.ai on your phone a peer in the agentsync coordination mesh — the same claims.json, the same agentsync branch, the same overlap and compare-and-swap rules as local agentsync, with no git and no local clone.

Your laptop's Claude Code (local agentsync) and your phone's claude.ai (agentsync-remote) claim work against the one shared claims.json. Two transports, one mesh. A local peer and this remote peer are indistinguishable in claims.json except by their agent id.

Sibling, not a fork. This is a second transport onto the same coordination file as local agentsync — not a variant of it. See DESIGN.md for how git push-as-CAS becomes GitHub-contents-API-as-CAS.

What it gives you

Seven tools over Streamable HTTP MCP:

Deploy your own (one click, no command line)

Self-host this Worker in your own Cloudflare account. Every step is a click path — you never touch a terminal.

1. Click Deploy to Cloudflare

Click the button above. Cloudflare will:

• fork agentsync-remote into your GitHub account,
• create the Worker in your Cloudflare account, and
• connect Workers Builds so future pushes to your fork redeploy automatically.

There are no databases or other resources to provision — this Worker keeps no state of its own (everything lives in your GitHub repo), so the deploy is just the Worker itself.

During the deploy dialog Cloudflare shows the Worker's variables. Set:

Finish the deploy. (If you skipped setting REPO here, you can set it later in the dashboard — see below.)

2. Make a GitHub token, then add the two Worker secrets

The Worker reads two secrets. These are not part of the deploy dialog — you add them once in the dashboard after the first deploy.

First, make the GitHub token (this is the GH_PAT value):

GitHub → Settings → Developer settings → Fine-grained personal access tokens → Generate new token:

• Repository access: Only select repositories → pick only your coordination repo (the one you put in REPO).
• Permissions → Repository permissions → Contents: Read and write.
• Nothing else. Generate it and copy the token.

Then add both secrets to the Worker:

Cloudflare dashboard → Workers & Pages → your Worker → Settings → Variables and Secrets → Add → type Secret → add each, then Deploy:

While you're on this screen, confirm the REPO variable points at your coordination repo (set it here if you skipped it in the deploy dialog).

Until AUTH_TOKEN is set the Worker answers every request with 404 (it fails closed). Until GH_PAT is set the tools return a clear error naming the missing secret. This is by design — an unconfigured endpoint looks like it doesn't exist.

3. Add the connector in claude.ai

Find your Worker's URL: Workers & Pages → your Worker shows it, in the form https://<your-worker-name>.<your-subdomain>.workers.dev.

claude.ai (web) → Settings → Connectors → Add custom connector. Paste your Worker URL with /mcp/ and your AUTH_TOKEN appended:

https://<your-worker-name>.<your-subdomain>.workers.dev/mcp/<AUTH_TOKEN>

The token in the path is the auth — there is no separate login.

4. Test it

Ask Claude: "call survey". You should get the coordination board back (empty claims on a fresh mesh — the Worker bootstraps the branch and file for you, so a brand-new empty repo needs no manual setup).

🔒 Security — the connector URL is a credential

The connector URL embeds your AUTH_TOKEN in the path (…/mcp/<AUTH_TOKEN>). Anyone who has that URL can call your Worker and read/write your coordination file. Treat the whole URL like a password:

• Don't paste it into screenshots, issues, chats, or commits.
• Anyone with the URL is a peer in your mesh — share it only with agents/people you trust.
• Rotating the token invalidates old URLs. To revoke access, change AUTH_TOKEN in Settings → Variables and Secrets and redeploy; every old …/mcp/<old-token> URL immediately returns 404. Update the connector in claude.ai with the new URL.

GH_PAT is likewise a credential — scope it to only your coordination repo with only Contents: Read and write, so a leak can't reach anything else.

Why the token is in the URL path, and what that costs you

This is a deliberate design choice, not an oversight. claude.ai custom connectors do not reliably send custom headers, so an Authorization: header — the obvious alternative — cannot be depended on. Putting the credential in the path is what makes the connector work at all.

Be clear about the price, because it is not the same as a header:

• URLs get recorded in places request bodies never do. Browser history, shell history, proxy and CDN access logs, crash reports, bug reports, screenshots, "copy link" buttons, and agent session transcripts. During the audit that produced this section, the connector URLs for these Workers were found in ~54 occurrences across 13 local session transcripts on a single machine — none pasted deliberately; they were simply part of the tool configuration an agent echoed back.
• The Worker itself does not log it. Every log line records the route as /mcp/***. The leak surface is everything around the Worker, which is exactly what you cannot audit.
• A leaked token makes the holder a full peer in your mesh — able to claim, force-claim over you, release your claims, and post to the mailbox — with no second factor and no per-caller identity. There is nothing to revoke except the token, and no log that will tell you who used it.

Practical guidance:

1. Rotate on a schedule, not just on suspicion — assume the URL has been recorded somewhere you don't control. Rotation is cheap: change AUTH_TOKEN, update the connector.
2. Rotate immediately if you've shared a terminal recording, a transcript, a screen capture, or a bug report from a machine where the connector is configured.
3. Use a long random token (32+ bytes, e.g. openssl rand -hex 32). The comparison is constant-time in both content and length, so length is not observable — but entropy is still your only defence against guessing.
4. If you ever get the chance to use a header or OAuth instead, take it. This tradeoff is forced by the client, not preferred.

Cross-transport walkthrough — two transports, one mesh

This is the whole point. The laptop and the phone coordinate through one file.

On the PC (local agentsync, Claude Code):

> agentsync claim --task "refactor auth" --touches src/auth --branch feature/auth
{"status": "claimed", ...}          # writes claims["laptop"] on the agentsync branch

On the phone (claude.ai + agentsync-remote):

You: call survey
Claude: laptop is active — task "refactor auth", touches src/auth, branch feature/auth.

You: claim task "tidy auth helpers", touches src/auth/helpers.ts
Claude: blocked. Overlap with an active peer claim:
        laptop — "refactor auth" — shared_files: ["src/auth/helpers.ts"]
        Narrow `touches`, wait, or re-call with force=true.

You: mailbox "Taking src/auth/helpers.ts once you land the refactor — ok?" to "laptop"
Claude: posted.

Back on the PC, the desktop agent (or you) reads the note via survey / mailbox, answers it, and releases:

> agentsync mailbox "go for it, helpers are stable now"
> agentsync release --note "refactor landed"
{"status": "released"}              # laptop's claim -> status "done"