Skip to content
Back to search

brokers

Remote MCP servers on Cloudflare Workers that lend an agent a bot or app identity without exposing its credentials (Discord, GitHub)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 20 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/CycleFive/brokers with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/CycleFive/brokers'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/cyclefive--brokers/badge.svg)](/listings/cyclefive--brokers)

HTML

<a href="/listings/cyclefive--brokers"><img src="/api/listings/cyclefive--brokers/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 148 lines
  1. # brokers
  2. A broker is a remote MCP server on Cloudflare Workers that lends an MCP client (Claude) one
  3. upstream account, a Discord bot or a GitHub App installation, behind an OAuth sign-in and an
  4. allowlist, without ever exposing the upstream token or key.
  5. | Broker | What it brokers |
  6. | --- | --- |
  7. | [`brokers/discord`](brokers/discord/README.md) | a Discord bot |
  8. | [`brokers/github`](brokers/github/README.md) | a GitHub App installation |
  9. ## Layout
  10. ```
  11. brokers/discord Discord broker Worker
  12. brokers/github GitHub broker Worker
  13. packages/core broker-core: code both brokers share
  14. packages/mailbox the mailbox tool: renders configs from a manifest, deploys, verifies
  15. ```
  16. One npm workspace; `npm install` at the root installs everything.
  17. ## What is shared
  18. `packages/core` (`broker-core`) holds what both brokers use: the utilities (`publicUrl`, `required`, `base64url`) and `VERSION`; the tool types with `ToolInputError`, `validateArgs` and `truncate`; the MCP server; the sign-in flow and its pages; `createBroker`, the request router; the two `Feed` helpers; and, under `broker-core/testing`, the in-memory KV and sign-in driver the tests use. `vitest.shared.ts` holds the test settings every package shares, including the Node stand-in for `cloudflare:workers`. Every `package.json` states the same version, and a core test checks that.
  19. ## Commands
  20. ```sh
  21. npm install
  22. npm run typecheck # core and both brokers
  23. npm test # core and both brokers
  24. ```
  25. ## Mailboxes
  26. A mailbox is one agent's own copy of each broker (its own Worker, KV namespace, upstream
  27. application and allowlist), plus its entry in the separate
  28. [mailroom](https://github.com/CycleFive/mailroom) service. One manifest describes every
  29. mailbox, and `npm run mailbox` generates each wrangler config from it, deploys and verifies.
  30. It needs Node 22.18 or later, because it runs TypeScript directly.
  31. ### The manifest
  32. Copy [`mailboxes.example.jsonc`](mailboxes.example.jsonc) to `mailboxes.jsonc` and fill it in.
  33. The example comments every key. The tool looks for the manifest in this order:
  34. 1. `--manifest <path>`
  35. 2. the `MAILBOXES` environment variable
  36. 3. `mailboxes.jsonc` at the repository root (git-ignored; a symlink to a file kept elsewhere works)
  37. The manifest holds no secret, but it decides who may sign in to each broker. Keep it out of
  38. this public repository, and out of anywhere the brokered agents themselves can write.
  39. ### Commands
  40. ```sh
  41. npm run mailbox -- <command> [mailbox...] [--manifest <path>] [--mailroom] [--allow-change] [--no-input]
  42. ```
  43. Name one or more mailboxes to act on only those; name none to act on all of them.
  44. | Command | What it does |
  45. | --- | --- |
  46. | `check` | Validates the manifest, including mailroom's part (its directory, its example and that some mailbox has `mail`), and prints each copy's mailbox, broker, Worker name and URL. Changes nothing. |
  47. | `render` | Writes each broker's generated `wrangler.<mailbox>.jsonc`, and `wrangler.jsonc` in mailroom's directory when the manifest has a `mailroom` entry and no mailbox is named. Needs a logged-in wrangler, because it lists your KV namespaces. It skips, and says so, a copy whose KV namespace does not exist yet (the first `deploy` creates it), and then exits 1. |
  48. | `deploy` | Creates a missing KV namespace, renders, deploys each copy, checks that its secrets are set, then verifies the running Worker (version and sign-in issuer). Prints the addresses to enter on the upstream applications. With `--mailroom`, then deploys `mailroom-core`: see below. |
  49. | `status` | Reads each copy's secrets and running version without deploying, and exits 1 if anything is missing or unverified. |
  50. `--no-input` stops `deploy` from prompting for missing secrets; it prints the
  51. `wrangler secret put` commands instead. It does the same when there is no terminal.
  52. `deploy --mailroom` deploys mailroom only when every chosen copy succeeded (deployed, no
  53. missing secret, verified), and always with the entry of every mailbox in the manifest, not
  54. only the chosen ones. So every mailbox with `mail` must already be deployed; otherwise
  55. mailroom's own deploy fails and changes nothing. `--mailroom` is only for `deploy`, and it is
  56. an error when the manifest has no `mailroom` entry. `check` validates the mailroom part, so
  57. run it first.
  58. **"this would change ... run again with --allow-change".** The tool refuses to overwrite a
  59. generated `wrangler.<mailbox>.jsonc` whose Worker name, KV namespace or `PUBLIC_URL` differs
  60. from what it is about to write, and refuses to rename a binding in mailroom's `wrangler.jsonc`
  61. (mailroom would lose its read positions). Both usually mean the manifest was edited by
  62. mistake. If the change is intended, run the same command again with `--allow-change`.
  63. **"<host> already resolves, so it belongs to something else".** A Worker that does not exist
  64. yet is not deployed to a hostname that already has a DNS record, because wrangler would take
  65. the hostname over without asking. This also happens when a Worker was deleted and its DNS
  66. record or custom domain was left behind, or when a wildcard record covers the name. Remove
  67. the record (Cloudflare dashboard, the zone's DNS page), or give the copy another `url`.
  68. Check a manifest without touching Cloudflare: `npm run mailbox -- check --manifest mailboxes.example.jsonc`.
  69. ### Adding a mailbox
  70. 1. Create the upstream applications: a Discord application and a GitHub App, as each
  71. broker's README describes in its Setup step 1.
  72. 2. Add the mailbox to `mailboxes.jsonc`, with each broker's `vars` and, if agents read its
  73. mail, a `mail` entry. Run `npm run mailbox -- check` to see the names and URLs it will use.
  74. 3. Run `npm run mailbox -- deploy <name> --mailroom`. It creates each Worker and its KV
  75. namespace, asks for each secret (type them when it does), deploys and verifies each copy,
  76. then deploys mailroom with every mailbox's entry. A new hostname takes a few minutes to
  77. get its DNS record and certificate; the command waits up to ten minutes for it.
  78. 4. Enter what the command prints: on the Discord application and the GitHub App, each
  79. copy's redirect (`<url>/callback`); on mailroom's sign-in application, mailroom's redirect
  80. (`<mailroom url>/callback`); and connect each copy's `<url>/mcp` and mailroom's
  81. `<mailroom url>/<mailbox>/mcp` as connectors in the agent's client.
  82. Run `npm run mailbox -- status <name>` afterwards to confirm everything verifies.
  83. An existing copy, deployed before you used the manifest, must pin its `kv` id, and its
  84. `worker`, `url` and `binding` wherever they differ from the defaults. The tool refuses to
  85. create a KV namespace for a Worker that already exists, because an empty namespace signs
  86. everyone out. Mailroom keys its read positions by binding name, so keep the existing `binding`.
  87. The first time the tool writes mailroom's `wrangler.jsonc` over a hand-written one, it keeps
  88. the old file once as `wrangler.jsonc.bak`.
  89. A `hostname` that is not `*.workers.dev` becomes a Cloudflare custom domain. Its zone must be
  90. on the same Cloudflare account as the Worker. The Worker then has no `workers.dev` address.
  91. ### Releasing
  92. Run `npm run mailbox -- deploy` to deploy every broker copy of every mailbox. To try a
  93. release on one copy first, run `npm run mailbox -- deploy <name>`, check it, then run the
  94. full command.
  95. ### One copy, no manifest
  96. Someone running a single copy can skip all of this: copy a broker's `wrangler.example.jsonc`
  97. to `wrangler.jsonc` (git-ignored) and run `npx wrangler deploy` in the broker's directory.
  98. Each broker's README walks through it.
  99. ## Adding a broker
  100. Make a directory `brokers/<name>` with:
  101. - `package.json` and `tsconfig.json`, copied from an existing broker
  102. - `vitest.config.ts`
  103. - `wrangler.example.jsonc`, with `vars` (which must contain `PUBLIC_URL`) and one
  104. `kv_namespaces` entry, and no `secrets` key; its `"name"` must equal the name you give
  105. `createBroker`, because verification reads the service name from the banner
  106. - in `package.json`, `"broker": { "secrets": [...] }` naming the secrets the mailbox tool must
  107. find set (wrangler refuses to deploy a config that requires secrets before they exist, and a
  108. new Worker cannot have secrets until it is deployed, so they cannot go in the example)
  109. - `src/index.ts`, which calls `createBroker`
  110. The mailbox tool and CI find the new broker with no change. Mailroom does not read its
  111. `Feed` until mailroom gains a source type for it.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.