cambium-remote

Part of the xylem stack.

A Cloudflare Worker MCP server that makes cambium's promoted knowledge recallable from claude.ai (including mobile) — read-only.

Local cambium is a desktop stdio server; its team knowledge lives on a cambium branch of each project repo and its org knowledge lives in a dedicated knowledge repo — both plain knowledge.json files in git. This Worker reads those files through the GitHub Contents API and serves recall() over them, the same pattern agentsync-remote uses for the coordination board.

Read-only by design. It exposes recall and status. It does not distill, endorse, or promote (those are CAS writes / the generalization gate — desktop-only), and recall here does not increment recall counts (so it never feeds promotion). Local (personal, unpromoted) scope is desktop-only and not reachable remotely — only the promoted team and org tiers are.

Tools

• recall(query, scope?, limit?) — search team + org knowledge. scope: auto (default, team+org) | team | org. Abstains with no_confident_match below the relevance floor, exactly like local cambium.
• status() — what the Worker is configured to read and how many active items each scope holds. Call it first if recall looks empty.

⚠️ Trust model — read this before pointing it at an org

Team "scope" is a read selector, not an authorization control. It answers "where do we look", not "who is allowed to tell us things". Nothing in this Worker checks provenance, signatures, or authorship of the knowledge it serves.

In the default TEAM_SCOPE_MODE = "discover" mode, the entire membership test for team scope is:

does this repo, owned by TEAM_OWNER, have a branch named TEAM_BRANCH?

There is no allowlist and no denylist. So:

• Anyone who can push a cambium branch to any repo under TEAM_OWNER can inject into your org-wide recall — an outside contributor with write access to one small repo, a compromised CI token, a collaborator you forgot to remove. Their knowledge.json is read as authoritative team knowledge.
• It takes effect within the 5-minute discovery cache TTL. No redeploy, no review, no notification.
• recall() output is exactly the kind of thing an agent treats as established fact and acts on. This is an injection path into agent behaviour, not merely a data-quality problem.

Discovery remains the default because it is genuinely safe in the single-operator case this was built for, and because changing it silently would empty team scope on existing deployments. It is safe only if you are the only person who can push under TEAM_OWNER.

If anyone else can push under TEAM_OWNER, use strict mode

TEAM_SCOPE_MODE = "allowlist"
TEAM_REPOS = "owner/repo-a,owner/repo-b"

Team scope then becomes exactly those repos. No discovery scan is performed, and TEAM_OWNER is ignored entirely — so leaving it set in wrangler.toml cannot silently re-widen your scope later. Adding a repo becomes a deliberate config change.

status() reports which model is in force, in plain language, in its own output. If you are unsure what a deployment is doing, call it.

What status() deliberately does not tell you

By default status() returns the count of team repos, not their names. In discover mode those names are the output of a scan over everything TEAM_OWNER owns, so they enumerate private repositories — their existence and their names — to anyone holding the path token, who has no GitHub identity and no repo permissions of their own. The count answers the actual diagnostic question ("is team scope finding anything?"). Set STATUS_DISCLOSE_REPOS = "true" to opt back in. In allowlist mode names are always shown: they are your own committed config, not a discovery result.

GH_PAT is the broadest credential in the xylem stack

Discovery requires Metadata: Read + Contents: Read across every repo under TEAM_OWNER, including private ones. That makes this Worker's PAT substantially more powerful than agentsync-remote's (scoped to one coordination repo). Two consequences worth acting on:

• Prefer allowlist mode, which lets you scope the PAT to only the listed repos instead of the whole account.
• Treat a leak of AUTH_TOKEN here as more serious than for the siblings: the Worker will read any in-scope repo on the caller's behalf.

Configure (wrangler.toml vars)

In discover mode team scope is a growing set: a newly team-promoted repo shows up on mobile within minutes with no redeploy. One GraphQL scan per few minutes (cached in-isolate) lists the repos; a repo without the branch is skipped.

Deploy

npm install
npm run typecheck && npm test
npx wrangler deploy
# then set the two secrets in the Cloudflare dashboard (never in the repo):
npx wrangler secret put AUTH_TOKEN   # the path-token credential; URL is /mcp/<AUTH_TOKEN>
npx wrangler secret put GH_PAT       # fine-grained GitHub token: Metadata: Read + Contents: Read across your repos
#                                    # (team scope is auto-discovered, so it needs to see all of TEAM_OWNER's repos)

Then add https://cambium-remote.<subdomain>.workers.dev/mcp/<AUTH_TOKEN> as a custom connector in claude.ai → Settings → Connectors. The whole URL is the credential — treat it like a password.

🔒 Auth — the connector URL is a credential

Path-token: POST /mcp/<token>, compared against the AUTH_TOKEN secret in time independent of both content and length; anything else returns a bare 404. Same scheme, and now literally the same code (src/shared/mcp-core.ts), as the sibling Workers.

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 leak here is the worst of the three, because this Worker's GH_PAT spans every repo under TEAM_OWNER (see Trust model).

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).
4. Scope GH_PAT as narrowly as your TEAM_SCOPE_MODE allows.
5. If you ever get the chance to use a header or OAuth instead, take it. This tradeoff is forced by the client, not preferred.

Development

npm install
npm run typecheck
npm test

CI (.github/workflows/ci.yml) runs typecheck + tests on every push and PR, including in forks. .github/workflows/deploy.yml deploys the canonical repo on green main only, and is guarded by if: github.repository == … so a fork never attempts a deploy it has no secrets for.

License

MIT — see LICENSE, matching the sibling agentsync-remote and context-keeper-remote Workers.

Note for the maintainer: this README previously stated PolyForm Noncommercial 1.0.0 while the repo shipped no LICENSE file at all. An MIT LICENSE has been added here to match both siblings. If PolyForm was the intended licence for this Worker, replace LICENSE and this section before merging — the discrepancy was pre-existing and is flagged rather than assumed.