Skip to content
Back to search

doorward

An authentication gateway for MCP servers: sign-in, per-tool access rules and a record of every call.

Safety scan

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

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/matpb--doorward/badge.svg)](/listings/matpb--doorward)

HTML

<a href="/listings/matpb--doorward"><img src="/api/listings/matpb--doorward/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 · 253 lines
  1. # Doorward
  2. Doorward is an authentication gateway in front of MCP servers hosted anywhere. People sign
  3. in with an email and a password, an admin decides who may use which server and which tool,
  4. and every request is checked before it reaches a server. It ships as one binary with one
  5. SQLite database.
  6. Status: pre-release (0.1.0).
  7. <picture>
  8. <source media="(prefers-color-scheme: dark)" srcset="docs/images/overview-dark.png">
  9. <img src="docs/images/overview-light.png" alt="The Doorward admin panel: the navigation on the left, a warning about two servers that answer without the gateway, counts of servers, users, invitations and rules, and the latest activity" width="720">
  10. </picture>
  11. ## What it does
  12. - **One address per server.** Each MCP server you add gets a path, `https://gateway.example.com/<slug>`.
  13. A combined endpoint, `/mcp`, offers the tools of every server a person may use, named
  14. `<path>__<tool>`.
  15. - **Its own OAuth server.** MCP clients discover it, send the person to the gateway's own
  16. sign-in and consent pages, and get tokens that only work at the gateway. The upstream
  17. servers never see them.
  18. - **Invitations.** The first person to sign up owns the instance. Everyone else comes in
  19. through a one-time link that expires, and sets or resets their own password by email.
  20. - **Access rules.** Servers are assigned to people. Allow and deny rules cover all tools,
  21. one server, or one exact tool. A denied tool is left out of the tool list and refused
  22. when called.
  23. - **Activity log.** Every sign-in, admin change and tool call is recorded with the person
  24. who made it.
  25. - **Mail.** Raw SMTP, Resend or Mailgun, set from the admin panel.
  26. - **Both protocol generations.** The session form and the stateless form of MCP over HTTP
  27. are both served.
  28. ## Run with Docker
  29. Two Compose files are in this repository. Copy `.env.example` to `.env`, set
  30. `DOORWARD_PUBLIC_URL`, and follow [docs/DOCKER.md](docs/DOCKER.md).
  31. - `compose.caddy.yaml` runs Caddy in front of the gateway, with automatic HTTPS.
  32. - `compose.yaml` runs the gateway alone, on the host's loopback address, for a proxy or
  33. tunnel you already run.
  34. ## Run the binary
  35. The gateway runs on Linux; Windows is not supported. Build it with Rust 1.89 or newer:
  36. ```sh
  37. cargo build --release
  38. ```
  39. Write a config file. Four settings are enough to start. `doorward.example.toml` shows the
  40. main settings; the settings table in [docs/DOCKER.md](docs/DOCKER.md#settings) lists all of
  41. them, and every setting can also come from an environment variable.
  42. ```toml
  43. public_url = "https://gateway.example.com"
  44. listen = "127.0.0.1:8717"
  45. database = "/var/lib/doorward/doorward.db"
  46. trusted_proxies = ["127.0.0.1", "::1"]
  47. ```
  48. `trusted_proxies` names the proxy in front; the two loopback addresses fit a proxy on the same host.
  49. The directory of `database` must exist and be writable by the gateway.
  50. Start it. The config file is read only from `--config` or `DOORWARD_CONFIG`.
  51. ```sh
  52. ./target/release/doorward --config doorward.toml
  53. ```
  54. The first start prints a setup code on standard error. Open `/setup`, enter the code, and
  55. the account you create becomes the owner. The code stops working once an owner exists.
  56. The admin panel is at `/admin`; an admin's account page links to it.
  57. Set up mail in the panel before you need it. A lost password, the owner's included, is
  58. reset by email only: there is no command that sets one.
  59. The encryption key for stored secrets is created next to the database, as a file readable
  60. only by its owner. Back it up with the database: one is useless without the other.
  61. Two more commands exist: `doorward unlock` clears a sign-in block for an account, and
  62. `doorward health` checks a running gateway.
  63. ## Put HTTPS in front
  64. The gateway speaks plain HTTP and expects a proxy that terminates TLS: Caddy, nginx, a
  65. tunnel, or a load balancer.
  66. - `public_url` must be `https` unless it is a loopback address.
  67. - Set `trusted_proxies` to the addresses of the proxies you run. The gateway then reads the
  68. visitor's address from `X-Forwarded-For`, which sign-in throttling and rate limits need.
  69. - With an `https` address and no trusted proxy the gateway refuses to start and says why.
  70. `shared_client_address = true` accepts that every visitor shares one address instead. Then
  71. everyone shares one set of address rate limits and one sign-in block, so anyone on the
  72. internet can lock out every user and client by sending junk requests or wrong passwords. Use
  73. it only on a private network where every visitor is trusted. For an install reachable from
  74. the internet, list the proxy in `trusted_proxies` and have it send `X-Forwarded-For`, as the
  75. bullet above describes.
  76. Caddy needs nothing more than the address. It gets the certificate, sends
  77. `X-Forwarded-For` and passes event streams through as they arrive:
  78. ```
  79. gateway.example.com {
  80. reverse_proxy 127.0.0.1:8717
  81. }
  82. ```
  83. nginx buffers answers and closes a connection that is silent for 60 seconds unless told
  84. otherwise, which breaks event streams. Inside the `server` block that holds your
  85. certificate:
  86. ```
  87. location / {
  88. proxy_pass http://127.0.0.1:8717;
  89. proxy_http_version 1.1;
  90. proxy_set_header Host $host;
  91. proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  92. proxy_buffering off;
  93. proxy_read_timeout 1h;
  94. }
  95. ```
  96. ## Add a server and lock it down
  97. In the admin panel, add a server with a name, a path and its upstream address. Then make sure
  98. the server only answers the gateway:
  99. 1. Give the server a secret header (a name and a value) and configure the server to refuse
  100. any request without it. The gateway adds the header to every request it forwards and
  101. removes the visitor's own credentials.
  102. 2. Press "Check lock-down" on the server page. The gateway calls the server without the
  103. secret and shows one of three states. "Locked down" means the server refused a request
  104. without the secret. "Answers without the gateway" means anyone who can reach its address
  105. can use it, gateway or not. "Not checked" means the check has not run yet, or the server
  106. did not answer the check.
  107. 3. Where you can, also restrict the server's network so that only the gateway reaches it.
  108. <picture>
  109. <source media="(prefers-color-scheme: dark)" srcset="docs/images/servers-dark.png">
  110. <img src="docs/images/servers-light.png" alt="The servers page: each server with its path, tool count, user count and lock-down state" width="720">
  111. </picture>
  112. The gateway never follows redirects from a server, and only relays the answers an MCP
  113. server is expected to give.
  114. Two things to know about server addresses. An admin can point a server at any address the
  115. gateway can reach, one on your private network included, so give the admin role only to
  116. people you would give that reach. And an `http` address carries the secret header
  117. unencrypted between the gateway and the server: use `https` unless the server runs on the
  118. same host or on a network you trust.
  119. ## Give people access
  120. Invite a person from the invitations page of the admin panel (`/admin/invitations`). Assign
  121. servers to them from their page or from the server's page. An admin can do this for
  122. anyone, the owner and other admins included; only the owner changes roles and mail
  123. settings. With no matching deny rule, every tool of an assigned server is allowed. Rules
  124. allow or deny all tools, one server, or one exact tool, for one person or for everyone.
  125. ## Connect a client
  126. Give the client the address of one server (`https://gateway.example.com/<slug>`) or the
  127. combined endpoint (`https://gateway.example.com/mcp`). Any MCP client that supports
  128. streamable HTTP and OAuth should work: it finds the sign-in pages by itself, and both
  129. client registration methods are supported.
  130. Claude Code:
  131. ```sh
  132. claude mcp add --transport http <name> https://gateway.example.com/<slug>
  133. claude mcp login <name>
  134. ```
  135. Codex:
  136. ```sh
  137. codex mcp add <name> --url https://gateway.example.com/<slug>
  138. codex mcp login <name>
  139. ```
  140. The browser opens the gateway's sign-in page, then a consent page that names the client,
  141. the server and the signed-in person. Approve only a sign-in you started yourself.
  142. <picture>
  143. <source media="(prefers-color-scheme: dark)" srcset="docs/images/consent-dark.png">
  144. <img src="docs/images/consent-light.png" alt="The consent page on a phone: where the sign-in will be sent, a warning about the client's name, the server, the signed-in person, Approve and Deny" width="320">
  145. </picture>
  146. Each person sees their connected clients on their account page and can disconnect one
  147. there. Claude Code, Codex and the Cursor command line client were run against 0.1.0.
  148. ## Limits worth knowing
  149. - Five wrong passwords for one account from one address block further tries on that
  150. account from that address for 15 minutes. Other limits and all defaults are in
  151. [docs/DOCKER.md](docs/DOCKER.md#rate-limits).
  152. - A browser page on another origin cannot call the MCP paths unless its origin is listed
  153. in `allowed_origins`.
  154. - A server's answer larger than `tools_list_bytes` (4 MiB by default) is not relayed. A larger
  155. JSON answer, such as a tool list or a tool result, gets a `502`. A larger event in a stream
  156. ends that stream. On the combined endpoint, a server that is too large is left out of the
  157. tool list.
  158. - Access tokens last 60 minutes and refresh tokens rotate. A refresh token presented again
  159. within 30 seconds gets the same new pair, which covers a lost answer; presented later, it
  160. ends that client's connection.
  161. ## What the gateway does not do
  162. - Every user reaches a server under one identity: the server's single stored secret header,
  163. when it has one. Per-user permissions exist only in the gateway. Anything the server caches
  164. or stores per caller is shared.
  165. - Allow and deny rules cover tools only. A server's resources and prompts are switched on or
  166. off per server. When a switch is on, they pass for every user assigned to that server.
  167. - The combined endpoint `/mcp` puts the tool descriptions of every assigned server in one list.
  168. A compromised server can word its descriptions to steer an agent toward other servers' tools.
  169. - The lock-down check proves that the server refuses a request without the secret. It cannot
  170. prove that the server never reveals the secret, for example by echoing request headers back.
  171. Keep the network restriction in step 3 as well.
  172. - A new deny rule applies to the next call. It does not end a call that is already running.
  173. - A tool call still succeeds when its activity row cannot be written, for example on a full disk.
  174. - `Mcp-Param-*` request headers go to the server as the client sent them. The gateway does not
  175. compare them with the message, and it decides nothing from them. The MCP specification
  176. leaves that check to the server.
  177. ## Run the tests
  178. `./check.sh` runs formatting, lints, every test, the dependency audits and the repository
  179. hygiene scan, and prints `CHECK PASS` when all of them pass.
  180. The proof scripts (`scripts/prove-*.sh`, with helpers in `scripts/prove/`) drive real clients
  181. and real HTTP against a throwaway gateway. [CONTRIBUTING.md](CONTRIBUTING.md) describes them.
  182. ## Questions and bugs
  183. Bugs and questions go to the repository's issue tracker. Security reports do not: see
  184. [SECURITY.md](SECURITY.md) for how to make one.
  185. ## More
  186. - [docs/DOCKER.md](docs/DOCKER.md): containers, every setting, backups, upgrades.
  187. - [docs/DESIGN.md](docs/DESIGN.md): how the gateway is built and why.
  188. - [docs/INTERFACE.md](docs/INTERFACE.md): every page and endpoint.
  189. - [docs/TESTS.md](docs/TESTS.md): the test catalogue.
  190. - [SECURITY.md](SECURITY.md): how to report a vulnerability, and the known limits.
  191. - [CONTRIBUTING.md](CONTRIBUTING.md): how a change is made and checked.
  192. ## License
  193. Licensed under MIT OR Apache-2.0. See `LICENSE-MIT` and `LICENSE-APACHE`.
  194. The bundled fonts, Atkinson Hyperlegible Next and Atkinson Hyperlegible Mono, are licensed
  195. under the SIL Open Font License 1.1, with the license texts in `assets/fonts/`.

Ratings and comments

Sign in to rate this skill.

Sign in

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