@ni-c/mcp-hub 0.9.2 → 0.10.0

package/CHANGELOG.md

@@ -7,6 +7,237 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 <!-- #region changelog -->
 
+## [0.10.0] - 2026-08-27
+
+### Added
+
+- `allowTools` and `denyTools` on any server in `mcp.json` decide which of its
+  tools the hub exposes. Each entry is an exact tool name or a prefix with a
+  single trailing `*`; the allow list decides what is in and the deny list is
+  subtracted from it. They apply to every kind of server — stdio, remote, docker
+  and socket — because an upstream you do not control is the strongest case for
+  filtering one. Nothing changes for a server that sets neither.
+
+  **It is a boundary, not a tidy-up.** A filtered tool is absent from
+  `tools/list` on the server's own path and from `list_tools` on `/hub`, and a
+  client that calls it anyway is refused on both routes — before the server is
+  woken, so a forbidden name cannot cost a container start. The refusal is the
+  same "unknown tool" a server gives for a name it never had: `/hub` tokens go
+  to third-party connectors, and enumerating what was hidden would be a
+  disclosure in itself.
+
+  Unlike ni-c's own MCP servers, an entry that matches no tool is not a config
+  error — the hub only learns an upstream's tools once it has connected. The
+  supervisor logs it at the moment it filters, and `/health` carries `exposed`,
+  `hidden` and `unmatched` per filtered server. The latter two only once the
+  server has really listed its tools: a snapshot restored from the tool cache is
+  already filtered, so `/health` omits them rather than reporting a zero it did
+  not earn.
+
+  Filters tools only: resources, resource templates and prompts on a per-server
+  path are untouched. It also does not shrink what the hub accepts — the size
+  limits on a `tools/list` answer are measured against the raw upstream, so a
+  server that blows them still fails as a whole.
+
+- **Client ID Metadata Documents (CIMD), the registration mechanism the MCP
+  specification now prefers.** A client may use an HTTPS URL as its `client_id`
+  and host its own metadata there; the hub fetches that document, checks that it
+  vouches for itself and takes the client's name and redirect URIs from it.
+  Nothing is registered and nothing is stored, so a client that reinstalls or
+  moves to another machine is still recognised as the same client, and the
+  approval you gave it still holds. Dynamic registration remains available and
+  advertised beside it, so nothing that works today stops working: a
+  spec-compliant client picks CIMD on its own, everything else falls back.
+  Closes [#18](https://github.com/ni-c/mcp-hub/issues/18).
+
+- **`private_key_jwt` client authentication.** A CIMD client cannot hold a
+  shared secret, so a confidential one proves itself with a JWT signed by a key
+  it publishes in its own document (`jwks` or `jwks_uri`). This is the path
+  ChatGPT's connectors take; without it they were refused with `invalid_client`.
+  The assertion must name the client as both `iss` and `sub`, target the token
+  endpoint or the issuer, carry a `jti` that is accepted exactly once, and
+  expire within five minutes.
+
+- **`CLIENT_REGISTRATION`** names the mechanisms a client may use to obtain a
+  `client_id` — `cimd`, `dcr`, or both, which is the default. Dropping `dcr`
+  removes `registration_endpoint` from the discovery document and makes
+  `/register` answer `404`, which is how you retire dynamic registration once
+  every client you use supports CIMD. `CIMD_ALLOWED_ORIGINS` restricts which
+  origins may serve a metadata document (only origins can be pinned — ChatGPT's
+  per-connector document path is random), and `CIMD_ALLOW_PRIVATE_ADDRESSES`
+  relaxes the SSRF guard for local development only.
+
+- **The authorization page names what cannot be forged.** For a
+  metadata-document client it shows the document URL under *Identified by*: the
+  name in that document is self-declared, the origin serving it is not. When
+  every redirect URI is a loopback address the page says so outright, because a
+  code sent to `http://127.0.0.1:…` could be collected by any program on that
+  machine.
+
+- **The hub can authenticate itself to upstream MCP servers with OAuth.** A
+  remote server may carry an `oauth` block instead of a static `Authorization`
+  header, and the hub then obtains and refreshes the token itself — no
+  `mcp-remote` bridge, no token cache to babysit. It identifies itself with
+  credentials the upstream issued (`mode: "static"`, with an optional
+  `clientSecret` from `${VAR}`), by registering dynamically (`"dcr"`, RFC 7591)
+  or with its own client metadata document (`"cimd"`), and uses either the
+  `client_credentials` grant, which needs no attention at all, or
+  `authorization_code`, which needs one browser visit started with
+  `mcp-hub-admin upstream login <server>`. The CLI prints a URL, the upstream
+  redirects back to the hub, and the server connects. `upstream list`, `status`,
+  `register`, `refresh` and `logout` cover the rest; `logout` also revokes the
+  token (RFC 7009) and deletes a dynamic registration (RFC 7592) at the upstream.
+  Replaces the `mcp-remote` workaround the configuration guide used to recommend.
+
+- **`mcp-hub-admin clients add`** issues a `client_id` and secret by hand, for a
+  client that supports neither dynamic registration nor a metadata document —
+  the one case that previously had no answer but an API token. Creating it
+  counts as approving it for the redirect URI you named, and it is exempt from
+  the lifecycle rules: nothing removes it but `clients delete`.
+
+- **Outbound `private_key_jwt`.** An upstream can be told
+  `"clientAuth": "private_key_jwt"` and the hub signs an RFC 7523 assertion
+  instead of presenting a shared secret. The signing key lives at
+  `<DATA_PATH>/upstream-key.pem` and is deliberately not the key that signs the
+  hub's own access tokens; its public half travels with the client metadata
+  document or the registration request, which is how the upstream verifies it.
+
+- **A client metadata document per upstream.** The hub previously published one
+  document built from the first server using `mode: "cimd"`, so a second such
+  server was registered with the first one's scopes. Each now has its own at
+  `/.well-known/mcp-hub-client/<id>.json`, where the identifier is derived from
+  the server name rather than being it — the URL is public, the names are not.
+
+- **A remote server whose authorization is missing or refused enters a new
+  `unauthorized` state** instead of restarting every five minutes for ever. It
+  is reported in `/health` and `list_servers`, and the log names the command to
+  run. A completed login brings it up again without a restart of the hub.
+
+- **A registration lifecycle for dynamic clients.** Anyone may register, so
+  registrations no longer stay forever: one that is never approved is dropped
+  after `DCR_PENDING_TTL_HOURS` (24), an approved one nobody has used after
+  `DCR_INACTIVE_DAYS` (90) along with its approval and refresh tokens, and the
+  store holds at most `DCR_MAX_CLIENTS` (500). Reaching the ceiling evicts the
+  oldest never-approved registrations; when every one of them has been approved
+  the newcomer is refused instead, so registering repeatedly cannot push a
+  working connector out. Opening the authorization page counts as use, so a slow
+  login is not cut short. The sweep runs at startup and every fifteen minutes,
+  and an existing state file is given a fresh clock rather than being read as
+  idle since the day each client registered. Client ID Metadata Document clients
+  are unaffected — they are never stored.
+
+- **Clients can manage their own registration (RFC 7592).** The registration
+  response now carries `registration_access_token` and
+  `registration_client_uri`, and `GET`, `PUT` and `DELETE` on
+  `/register/<client_id>` let a client read, change or remove what it
+  registered. Only a hash of the token is stored, so it is shown exactly once.
+  `DELETE` takes the approval and every refresh token with it. Changing the
+  redirect URIs through `PUT` withdraws the approval — consent was given for a
+  destination and does not transfer to a new one — while changing a name or a
+  logo leaves it in place. A wrong token and an unknown `client_id` get the same
+  answer, so the endpoint cannot be used to enumerate registrations. None of
+  this comes from the SDK, whose registration router accepts `POST` and nothing
+  else.
+
+- `mcp-hub-admin clients delete <client-id>` removes a registration outright,
+  where `clients revoke` withdraws access but keeps it, and
+  `mcp-hub-admin clients prune [--dry-run]` applies the lifecycle rules on
+  demand instead of waiting for the next sweep.
+
+- `mcp-hub-admin clients list` now also lists clients that were approved
+  without ever being registered, and says which mechanism each one came in
+  through. A metadata-document client leaves no registration behind, so its
+  approval is the whole record; `clients revoke` works on it either way.
+
+- **A `demo/` directory you can run without owning anything.**
+  `docker compose up -d` brings up a hub with three fake MCP servers —
+  weather, tickets and a small index of these docs — and
+  [the page that goes with it](https://mcp-hub.ni-c.de/guide/demo) shows how to
+  point the MCP Inspector or MCPJam at it. The servers answer from tables
+  compiled into them: no network, no filesystem, no stored state, so the same
+  call gives the same answer and nothing a visitor does outlasts the request.
+  `demo/token.sh` mints the API tokens. It exists because the first question
+  about a gateway is what it looks like from the client side, and until now the
+  only way to find out was to deploy one.
+
+### Changed
+
+- The README now carries the same eight badges, in the same order, as every other
+  MCP server in this family, all of them reading from npm rather than hard-coded;
+  the opening follows one shape; and the standalone "Full documentation" line is
+  gone, because the docs badge three lines above it points at the same page.
+
+- The authorization-server metadata advertises
+  `client_id_metadata_document_supported`, and `private_key_jwt` alongside
+  `client_secret_post` and `none` in `token_endpoint_auth_methods_supported`.
+  The enriched document is served at the root path, the RFC 8414 path-inserted
+  form and the OpenID Connect discovery alias alike.
+
+### Security
+
+- Metadata documents are fetched from a URL an unauthenticated caller chose, so
+  the request is treated as hostile: `https` only, redirects never followed,
+  private, loopback, link-local and CGNAT addresses refused after DNS
+  resolution, a 5 kB cap enforced while reading, a 5-second timeout and a JSON
+  content type required. Documents carrying a `client_secret` or declaring a
+  symmetric authentication method are refused outright. Concurrent lookups of
+  one URL collapse into a single request, rejections are remembered for 30
+  seconds and the cache is bounded, so a `client_id` cannot be used to point the
+  hub at a third party. Every rejection answers a bare `invalid_client`; the
+  reason goes to the log only, so the admission policy cannot be mapped by
+  probing.
+
+- **A client declaring `private_key_jwt` must present an assertion.** Client
+  authentication is driven by the stored record, and a metadata-document client
+  never has a `client_secret` — so a token request that simply omitted
+  `client_assertion` was treated as a public client and accepted on its
+  `client_id` alone. A leaked refresh token or authorization code was therefore
+  redeemable without the private key that exists to prevent exactly that. The
+  assertion is now required whenever the document declares it.
+
+- **The connection is pinned to the address that was checked.** The SSRF guard
+  resolved the hostname and then handed the name to `fetch`, which resolved it
+  again; a zone answering differently the second time could move the request
+  onto an internal address or a cloud metadata endpoint. The vetted address is
+  now what the socket connects to, with the certificate still validated against
+  the hostname. The IPv6 forms that carry an IPv4 address (NAT64 `64:ff9b::/96`,
+  6to4 `2002::/16`) and several reserved IPv4 ranges are refused as well.
+
+- **The `jwks_uri` fetch is capped at 64 kB.** It inherited the redirect,
+  timeout and address guards but not the size limit, and the JWKS is parsed
+  whole — an unauthenticated token request naming a document with a hostile
+  `jwks_uri` could push an unbounded body into the heap and take the hub, and
+  every MCP server it supervises, down with it. The cache of remote key sets is
+  now bounded too; entries were created before the signature was checked.
+
+- **Untrusted values can no longer forge a log record.** A `client_id` may
+  contain newlines — the URL parser strips them, so the value passed every
+  structural check while the raw string reached the log, where each line is
+  given a valid timestamp. A forged `mcp-hub: authentication failure from …`
+  line matches the fail2ban filter this project ships, which made it possible
+  to have any address banned by sending unauthenticated requests. Client-chosen
+  values are escaped and capped at the point they enter a log line.
+
+- **Redirect URIs are held to one rule for both registration mechanisms.**
+  Dynamic registration accepted anything outside the SDK's three-scheme
+  denylist, including a plaintext `http://` callback on a remote host, which
+  delivers the authorization code in the clear. Registration now requires
+  `https`, a loopback address, or an application-specific scheme for native
+  clients, and answers `400 invalid_client_metadata` otherwise.
+
+- Self-declared client names are reduced to a single short line before they are
+  stored or shown. They were escaped but unbounded, so a name of several hundred
+  characters could push the redirect target and the loopback warning off the
+  consent page.
+
+- `/health` is authenticated and bound to the `hub` resource; only `/livez` is
+  public. A stale comment claimed the opposite, which would have justified
+  exposing the deployment topology.
+
+- Revocation markers are dropped once they are older than the longest-lived
+  refresh token they could reject. They were the one part of the state file
+  that only ever grew.
+
 ## [0.9.2] - 2026-08-24
 
 ### Fixed

package/README.md

@@ -1,20 +1,23 @@
 # mcp-hub
 
-[![CI](https://github.com/ni-c/mcp-hub/actions/workflows/ci.yml/badge.svg)](https://github.com/ni-c/mcp-hub/actions/workflows/ci.yml)
+[![CI](https://img.shields.io/github/actions/workflow/status/ni-c/mcp-hub/ci.yml?branch=main&label=CI)](https://github.com/ni-c/mcp-hub/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/%40ni-c%2Fmcp-hub)](https://www.npmjs.com/package/@ni-c/mcp-hub)
 [![npm downloads](https://img.shields.io/npm/dm/%40ni-c%2Fmcp-hub)](https://www.npmjs.com/package/@ni-c/mcp-hub)
-[![Container](https://img.shields.io/badge/ghcr.io-ni--c%2Fmcp--hub-2496ED?logo=docker&logoColor=white)](https://github.com/ni-c/mcp-hub/pkgs/container/mcp-hub)
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
-[![Docs](https://img.shields.io/badge/docs-mcp--hub.ni--c.de-4f46e5)](https://mcp-hub.ni-c.de)
-
-📖 **Full documentation: <https://mcp-hub.ni-c.de>**
-
-Serve many stdio MCP servers from **one container**, published over HTTPS for
-ChatGPT connectors, Claude (Web and Code), Mistral Le Chat, Cursor, LibreChat
-and any other Streamable-HTTP MCP client — with a built-in OAuth 2.1 login
-protected by a single password, plus long-lived API tokens for clients that
-cannot do OAuth (OpenAI Responses API, xAI API, Gemini API). Per-client
-recipes: [client compatibility](https://mcp-hub.ni-c.de/guide/client-compatibility).
+[![node](https://img.shields.io/node/v/%40ni-c%2Fmcp-hub)](https://nodejs.org)
+[![license](https://img.shields.io/npm/l/%40ni-c%2Fmcp-hub)](LICENSE)
+[![container](https://img.shields.io/badge/ghcr.io-ni--c%2Fmcp--hub-blue)](https://github.com/ni-c/mcp-hub/pkgs/container/mcp-hub)
+[![docs](https://img.shields.io/badge/docs-mcp--hub.ni--c.de-informational)](https://mcp-hub.ni-c.de)
+[![sponsor](https://img.shields.io/badge/sponsor-ni--c-ea4aaa?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/ni-c)
+
+A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) gateway: it serves
+many stdio MCP servers from **one container**, published over HTTPS.
+
+Lets MCP clients that cannot spawn a local process — ChatGPT connectors, Claude on
+the Web and in Code, Mistral Le Chat, Cursor, LibreChat and any other
+Streamable-HTTP client — reach every server behind it, with a built-in OAuth 2.1
+login protected by a single password, plus long-lived API tokens for clients that
+cannot do OAuth (OpenAI Responses API, xAI API, Gemini API). Per-client recipes:
+[client compatibility](https://mcp-hub.ni-c.de/guide/client-compatibility).
 
 <!-- <picture> is resolved against the colour scheme of the page showing it, so GitHub
      picks the variant that matches its own theme toggle. npm strips <picture> and
@@ -28,18 +31,29 @@ recipes: [client compatibility](https://mcp-hub.ni-c.de/guide/client-compatibili
 
 ![Demo: config in, hub up, servers reachable through one endpoint](https://mcp-hub.ni-c.de/demo.gif)
 
+**Want to poke at it first?** [`demo/`](demo/) is a throwaway hub with three
+fake servers — `docker compose up -d`, then point the
+[MCP Inspector](https://mcp-hub.ni-c.de/guide/demo#mcp-inspector) or
+[MCPJam](https://mcp-hub.ni-c.de/guide/demo#mcpjam) at it. Nothing to
+configure, nothing to clean up but a volume.
+
 ## Why
 
 Wrapping each stdio MCP server in its own auth-proxy container costs a full
-image, an OAuth stack, a hostname and a compose stack *per server*. mcp-hub
+image, an OAuth stack, a hostname and a compose stack _per server_. mcp-hub
 replaces N containers with one process:
 
 - **Config is exactly Claude Code's `mcpServers` format** — copy entries 1:1.
 - **Path-based routing**: `https://host/paperless`, `https://host/homeassistant`, …
-- **`/hub` aggregate**: register a *single* connector and reach every server
+- **`/hub` aggregate**: register a _single_ connector and reach every server
   through 6 meta-tools (`list_servers`, `list_tools`, `get_tool_schema`,
   `call_tool`, `wake_server`, `sleep_server`) without flooding the model
   context with N×tools schemas.
+- **Per-server tool filtering**: `allowTools` / `denyTools` on any server decide
+  which of its tools the hub exposes — exact names or `list_*` prefixes. A
+  filtered tool is hidden from `tools/list` _and_ refused if a client calls it
+  anyway, before the server is even woken, so a client holding a stale schema
+  cannot reach it.
 - **Also without HTTP**: `mcp-hub --stdio` serves that same aggregate on
   stdin/stdout for clients that can only spawn a local process (Claude Desktop,
   Codex, …) — same `mcp.json`, no TLS, no reverse proxy, no login. Auth exists
@@ -48,6 +62,20 @@ replaces N containers with one process:
   after 60 idle minutes, answering `initialize`/`tools/list` from a persistent
   snapshot meanwhile — a dozen servers cost only the memory of the ones in
   use. `keepAlive: true` exempts a server, `IDLE_TIMEOUT_MINUTES=0` the hub.
+- **CIMD-first OAuth 2.1**: clients identify themselves with a [Client ID
+  Metadata Document](https://mcp-hub.ni-c.de/guide/client-registration) — the
+  registration-free path the MCP spec now prefers — including `private_key_jwt`
+  against the keys in their own document (metadata-document clients only). RFC
+  7591 dynamic registration stays advertised beside it for older clients,
+  `mcp-hub-admin clients add` issues credentials by hand for anything that can
+  do neither, and `CLIENT_REGISTRATION` turns either mechanism off.
+- **OAuth outwards, too**: a remote server that speaks OAuth gets an `oauth`
+  block instead of a static header. The hub registers itself — with credentials
+  the upstream issued, via RFC 7591, or with its own client metadata document —
+  then obtains and refreshes the token. `client_credentials` upstreams need no
+  attention at all; where a person must sign in, `mcp-hub-admin upstream login`
+  prints one URL. An upstream that needs re-authorizing shows up as one server
+  `unauthorized`, not as a confusing 401 in your client.
 - **Supervision**: children are pinged and restarted with exponential backoff
   when they die. A down server answers 503, not silence; a crash-looping
   server nobody uses is parked instead of restarted forever.
@@ -81,6 +109,11 @@ version in your image; do not download mutable packages at runtime:
       "headers": { "Authorization": "Bearer ${HA_TOKEN}" }
     },
     "private-thing": { "command": "some-mcp", "args": [], "hub": false },
+    "paperless-readonly": {
+      "command": "paperless-mcp",
+      "allowTools": ["search_*", "get_document"],
+      "denyTools": ["delete_document"]
+    },
     "untrusted": {
       "type": "docker",
       "image": "ghcr.io/example/untrusted-mcp@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
@@ -95,13 +128,16 @@ Stdio servers (`command`/`args`/`env`) are spawned as supervised child
 processes. Remote servers (`type: "http"` or `"sse"` with `url` and optional
 `headers`) are connected as MCP clients with the configured headers injected
 on every request — the same supervision (ping, backoff reconnect, hot reload)
-applies. Upstreams that require their own *interactive* OAuth cannot be
-configured with static headers; bridge those with an
-[`mcp-remote`](https://github.com/geelen/mcp-remote) stdio entry and persist
-its token cache (`MCP_REMOTE_CONFIG_DIR`) under `/data`.
+applies. An upstream that speaks OAuth gets an `oauth` block instead of a
+header: the hub registers itself (statically, via RFC 7591 or via a client
+metadata document), obtains the token and refreshes it, with one browser visit
+started from the admin CLI where the grant needs a person.
 `"hub": false` hides a server from the `/hub` aggregate; its own path keeps
-working. Reserved names: `mcp`, `hub`, `authorize`, `token`, `register`,
-`login`, `consent`, `health`, `livez`, `revoke`.
+working. `allowTools` / `denyTools` cut finer and apply to every kind of
+server: a filtered tool is absent from both `tools/list` and `/hub`, and is
+refused if called anyway — before the server is woken.
+Reserved names: `mcp`, `hub`, `authorize`, `token`, `register`,
+`login`, `consent`, `health`, `livez`, `revoke`, `upstream`, `.well-known`.
 
 All stdio children share the hub's Unix user and can read its mounted files.
 Only install fully trusted stdio servers. A server with a different trust level
@@ -126,7 +162,7 @@ and [SECURITY.md](SECURITY.md).
 For a custom image, pin every package to an exact version:
 
 ```dockerfile
-FROM ghcr.io/ni-c/mcp-hub:0.6.0   # pin @sha256:<digest> in production
+FROM ghcr.io/ni-c/mcp-hub:0.10.0   # pin @sha256:<digest> in production
 USER root
 RUN npm install -g your-mcp-package@1.2.3
 USER node
@@ -134,24 +170,38 @@ USER node
 
 ### Environment
 
-| Variable | Required | Description |
-|---|---|---|
-| `EXTERNAL_URL` | yes | Public base URL, e.g. `https://mcp.example.net` (no path) |
-| `PASSWORD_HASH` | one of | bcrypt hash of the login password (`htpasswd -bnBC 10 "" 'pw' \| tr -d ':\n'`) |
-| `PASSWORD` | one of | plain-text alternative to `PASSWORD_HASH` |
-| `TRUSTED_PROXIES` | no | comma-separated IPs/CIDRs allowed to set `X-Forwarded-*` (see below) |
-| `RESOURCE_BOUND_TOKENS` | no | RFC 8707 tokens bound to `/hub` or one `/<name>/mcp`, default `true`; set `false` only to keep pre-0.5 unbound tokens working |
-| `DEFAULT_RESOURCE` | no | server name (or `hub`) to bind tokens to when a client sends no `resource` parameter; unset → such requests are refused |
-| `MCP_BODY_LIMIT` | no | authenticated MCP JSON body limit, default `1mb` |
-| `MCP_REQUESTS_PER_MINUTE` | no | limit per OAuth client, default `120` |
-| `MCP_MAX_CONCURRENT_REQUESTS` | no | in-flight request limit per OAuth client, default `4` |
-| `MCP_MAX_CONCURRENT_STREAMS` | no | open SSE listening streams per OAuth client — one per connected session, default `32` |
-| `HTTP_HEADERS_TIMEOUT_MS` | no | Node HTTP header timeout, default `10000` |
-| `HTTP_REQUEST_TIMEOUT_MS` | no | complete request timeout, default `310000` (slightly above the tool-call timeout) |
-| `PORT` | no | listen port (default 80 in the image, 3000 outside) |
-| `CONFIG_PATH` | no | default `/config/mcp.json` |
-| `DATA_PATH` | no | default `/data` |
-| `LOG_FILE` | no | additionally mirror all log output into this file, e.g. `/data/mcp-hub.log` (see below) |
+| Variable                        | Required            | Description                                                                                                                   |
+| ------------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `EXTERNAL_URL`                  | yes                 | Public base URL, e.g. `https://mcp.example.net` (no path)                                                                     |
+| `PASSWORD_HASH`                 | one of              | bcrypt hash of the login password (`htpasswd -bnBC 10 "" 'pw' \| tr -d ':\n'`)                                                |
+| `PASSWORD`                      | one of              | plain-text alternative to `PASSWORD_HASH`                                                                                     |
+| `TRUSTED_PROXIES`               | no                  | comma-separated IPs/CIDRs allowed to set `X-Forwarded-*` (see below)                                                          |
+| `RESOURCE_BOUND_TOKENS`         | no                  | RFC 8707 tokens bound to `/hub` or one `/<name>/mcp`, default `true`; set `false` only to keep pre-0.5 unbound tokens working |
+| `DEFAULT_RESOURCE`              | no                  | server name (or `hub`) to bind tokens to when a client sends no `resource` parameter; unset → such requests are refused       |
+| `MCP_BODY_LIMIT`                | no                  | authenticated MCP JSON body limit, default `1mb`                                                                              |
+| `MCP_REQUESTS_PER_MINUTE`       | no                  | limit per OAuth client, default `120`                                                                                         |
+| `MCP_MAX_CONCURRENT_REQUESTS`   | no                  | in-flight request limit per OAuth client, default `4`                                                                         |
+| `MCP_MAX_CONCURRENT_STREAMS`    | no                  | open SSE listening streams per OAuth client — one per connected session, default `32`                                         |
+| `HTTP_HEADERS_TIMEOUT_MS`       | no                  | Node HTTP header timeout, default `10000`                                                                                     |
+| `HTTP_REQUEST_TIMEOUT_MS`       | no                  | complete request timeout, default `310000` (slightly above the tool-call timeout)                                             |
+| `PORT`                          | no                  | listen port (default 80 in the image, 3000 outside)                                                                           |
+| `CONFIG_PATH`                   | no                  | default `/config/mcp.json`                                                                                                    |
+| `DATA_PATH`                     | no                  | default `/data`                                                                                                               |
+| `LOG_FILE`                      | no                  | additionally mirror all log output into this file, e.g. `/data/mcp-hub.log` (see below)                                       |
+| `CLIENT_REGISTRATION`           | no                  | which mechanisms a client may use for a `client_id`: `cimd`, `dcr` or both (default)                                          |
+| `CIMD_ALLOWED_ORIGINS`          | no                  | bare https origins whose metadata documents are accepted; unset → any                                                         |
+| `CIMD_ALLOW_PRIVATE_ADDRESSES`  | no                  | local development only; relaxes the SSRF guard, warns on every start                                                          |
+| `DCR_MAX_CLIENTS`               | no                  | ceiling on stored dynamic registrations, default `500`                                                                        |
+| `DCR_PENDING_TTL_HOURS`         | no                  | how long a never-approved registration is kept, default `24`                                                                  |
+| `DCR_INACTIVE_DAYS`             | no                  | how long an unused approved registration is kept, default `90`                                                                |
+| `IDLE_TIMEOUT_MINUTES`          | no                  | idle minutes before an on-demand server sleeps, default `60`; `0` disables it                                                 |
+| `TOOL_CACHE_PATH`               | no                  | snapshots of sleeping servers, default `<DATA_PATH>/tool-cache.json`                                                          |
+| `MCP_CALL_TIMEOUT_MS`           | no                  | deadline for one forwarded tool call, default `300000`                                                                        |
+| `MCP_RESET_TIMEOUT_ON_PROGRESS` | no                  | let progress notifications extend that deadline, default `false`                                                              |
+| `DOCKER_HOST`                   | with docker servers | the **policy proxy's** socket; a direct daemon socket fails closed                                                            |
+
+The full table, including what applies in stdio mode, is in the
+[environment reference](https://mcp-hub.ni-c.de/reference/environment).
 
 `/data` holds the Ed25519 JWT key, registered OAuth clients, approvals and
 refresh tokens. **Mount it as a volume** — recreating it invalidates every
@@ -170,7 +220,7 @@ invalidates those unbound tokens, so every connector authorizes once more.
 
 `TRUSTED_PROXIES` decides what `req.ip` is, and therefore what the login rate
 limiter counts. List **only** your own reverse proxy, and make sure it
-*overwrites* `X-Forwarded-For` rather than appending to it — otherwise a
+_overwrites_ `X-Forwarded-For` rather than appending to it — otherwise a
 client can supply its own address and rotate it to sidestep the per-IP limit.
 If the variable is unset, every request appears to come from the proxy and
 per-IP limiting degrades to a single global counter (the hub logs a warning
@@ -185,7 +235,7 @@ Published on every push to `main` and every `vX.Y.Z` release tag, for
 [package page](https://github.com/ni-c/mcp-hub/pkgs/container/mcp-hub).
 
 ```sh
-docker pull ghcr.io/ni-c/mcp-hub:0.6.0
+docker pull ghcr.io/ni-c/mcp-hub:0.10.0
 ```
 
 Tags: `latest` (tip of `main`), `X.Y.Z` and `X.Y` (releases), and
@@ -200,7 +250,7 @@ With compose, copy the example and point it at the image instead of building:
 ```yaml
 services:
   mcp-hub:
-    image: ghcr.io/ni-c/mcp-hub:0.6.0   # replaces `build: .`; pin a digest in production
+    image: ghcr.io/ni-c/mcp-hub:0.10.0 # replaces `build: .`; pin a digest in production
     # ...rest of docker-compose.example.yml unchanged
 ```
 
@@ -222,7 +272,7 @@ docker run -d --name mcp-hub \
   -e TRUSTED_PROXIES="192.168.1.0/24" \
   -v "$PWD/config:/config:ro" \
   -v "$PWD/data:/data" \
-  ghcr.io/ni-c/mcp-hub:0.6.0
+  ghcr.io/ni-c/mcp-hub:0.10.0
 ```
 
 Update to a newer image with `docker compose pull && docker compose up -d`
@@ -263,7 +313,7 @@ see [client compatibility](https://mcp-hub.ni-c.de/guide/client-compatibility).
 
 Each client is confirmed once. Entering the password approves the client that
 asked; while a login session is still valid, a client you have not seen before
-gets an explicit *Approve / Deny* page instead of a code. Approved clients
+gets an explicit _Approve / Deny_ page instead of a code. Approved clients
 reconnect silently from then on.
 
 List clients or revoke one. The CLI shares `/data` with the running hub and
@@ -273,10 +323,17 @@ live container — a revocation takes effect on the next request:
 ```sh
 docker exec mcp-hub node /app/dist/admin.js clients list
 docker exec mcp-hub node /app/dist/admin.js clients revoke CLIENT_ID
+docker exec mcp-hub node /app/dist/admin.js clients delete CLIENT_ID
+docker exec mcp-hub node /app/dist/admin.js clients prune --dry-run
 ```
 
 Revocation removes the approval and all refresh tokens and immediately rejects
 already-issued access tokens. The next connection needs explicit approval.
+`delete` goes further and removes the registration itself, and `prune` applies
+the [registration lifecycle rules](https://mcp-hub.ni-c.de/guide/client-registration)
+on demand — registrations that were never approved expire after a day, unused
+ones after 90 days, and a dynamically registered client can also remove its own
+registration through RFC 7592.
 
 For clients that cannot do OAuth at all — the OpenAI Responses API, the xAI
 API, Gemini's `mcp_server` tool, plain-header clients — the same CLI mints
@@ -294,15 +351,18 @@ immediately. Per-client recipes:
 
 ## Endpoints
 
-| Path | Auth | Purpose |
-|---|---|---|
-| `/<name>`, `/<name>/mcp` | Bearer | Streamable HTTP endpoint of one server |
-| `/hub` | Bearer | aggregate endpoint with the 4 meta-tools |
-| `/livez` | none | minimal process liveness (`200`) |
-| `/health` | Bearer | per-server status (`200` all up / `503` degraded) |
-| `/authorize`, `/token`, `/register`, `/login`, `/consent`, `/revoke` | — | OAuth 2.1 + DCR |
-| `/.well-known/oauth-authorization-server[/…]` | none | RFC 8414 metadata |
-| `/.well-known/oauth-protected-resource[/…]` | none | RFC 9728 metadata (path-scoped) |
+| Path                                                                 | Auth                       | Purpose                                                           |
+| -------------------------------------------------------------------- | -------------------------- | ----------------------------------------------------------------- |
+| `/<name>`, `/<name>/mcp`                                             | Bearer                     | Streamable HTTP endpoint of one server                            |
+| `/hub`                                                               | Bearer                     | aggregate endpoint with the 6 meta-tools                          |
+| `/livez`                                                             | none                       | minimal process liveness (`200`)                                  |
+| `/health`                                                            | Bearer                     | per-server status (`200` all up / `503` degraded)                 |
+| `/authorize`, `/token`, `/register`, `/login`, `/consent`, `/revoke` | —                          | OAuth 2.1 · CIMD + DCR                                            |
+| `/register/<client_id>`                                              | registration token         | RFC 7592: a client reads, changes or removes its own registration |
+| `/upstream/callback`                                                 | signed state + hub session | where an upstream returns after `upstream login`                  |
+| `/.well-known/mcp-hub-client/<id>.json`                              | none                       | the hub's own client metadata document, one per `cimd` upstream   |
+| `/.well-known/oauth-authorization-server[/…]`                        | none                       | RFC 8414 metadata                                                 |
+| `/.well-known/oauth-protected-resource[/…]`                          | none                       | RFC 9728 metadata (path-scoped)                                   |
 
 ## Notes & limitations