@ni-c/mcp-hub 0.9.2 → 0.11.0

package/README.md

@@ -1,20 +1,32 @@
 # 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 dual-era [Model Context Protocol](https://modelcontextprotocol.io) (MCP) gateway: it
+serves many stdio MCP servers from **one container**, published over HTTPS, and speaks
+**both MCP revisions on every endpoint** — `2026-07-28` and `2025-11-25`. The client
+picks, and cannot tell which one it is on from the answers. On the 2026 revision that
+includes **elicitation** — a child server's question reaches the person at the far end
+instead of dying at the gateway
+([how](https://mcp-hub.ni-c.de/guide/elicitation)) — and **subscriptions**: the hub
+serves `subscriptions/listen` to its clients and subscribes to its children on
+whichever revision _they_ speak, so a server that has never heard of it still reaches
+a client that speaks nothing else
+([how](https://mcp-hub.ni-c.de/guide/subscriptions)).
+
+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 +40,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 +71,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.
@@ -55,11 +92,62 @@ replaces N containers with one process:
   servers.
 - **Stateless Streamable HTTP**: no session state, so claude.ai's
   reconnect-without-DELETE behaviour cannot leak processes or memory.
+- **Dual-era**: every endpoint — `/hub`, `/<name>/mcp` and `--stdio` — answers
+  MCP `2026-07-28` and `2025-11-25` alike; the client picks and cannot tell
+  from the answers which it got. On the 2026 revision that includes
+  **elicitation**: a server asking the user something returns the question
+  rather than pushing it, so it reaches the person at the far end instead of
+  dying at the gateway. The hub attributes it to the server that asked, strips
+  what could lie about that, drops embedded sampling and roots requests, and
+  seals the resumption state against the call it belongs to. `passthrough:
+"off"` withdraws one server's right to ask;
+  [details](https://mcp-hub.ni-c.de/guide/elicitation).
+- **Change notifications, in both eras**: a client opens a
+  `subscriptions/listen` stream and hears when a child's tools, prompts or
+  resources change. The hub subscribes to each child the way that child
+  understands — `subscriptions/listen` to a 2026 server, `resources/subscribe`
+  to a 2025 one — so the era gap is the gateway's problem rather than either
+  end's. The state is the open response, not a session table, so this costs the
+  stateless design nothing. A sleeping server watches nothing and is told to
+  re-read on waking; `subscriptions: "off"` withdraws one server's right to
+  push; [details](https://mcp-hub.ni-c.de/guide/subscriptions).
 - **Lightweight by design**: one Node process, no database (state is one JSON
-  file plus a JWT key under `/data`), a handful of runtime dependencies, and
+  file plus a signing key under `/data`), six runtime dependencies, and
   multi-arch images — a stated project goal is to run comfortably on a
   single-board computer like a Raspberry Pi.
 
+## Servers to run behind it
+
+The hub is server-agnostic — it serves any stdio MCP server whose entry fits
+Claude Code's `mcpServers` format, which is most of them. These seventeen are
+built and maintained alongside it, so their documentation carries the hub entry
+you need and their tool filters line up with the hub's own `allowTools` /
+`denyTools`:
+
+| Server                                                                 | npm                               | What it reaches                                                                |
+| ---------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------ |
+| [audiobookshelf-mcp](https://audiobookshelf-mcp.ni-c.de)               | `audiobookshelf-mcp`              | Audiobookshelf — libraries, listening progress, collections and playlists      |
+| [calibreweb-mcp](https://calibreweb-mcp.ni-c.de)                       | `calibreweb-mcp`                  | Calibre-Web — read-only library access through the OPDS feed                   |
+| [freshrss-mcp](https://freshrss-mcp.ni-c.de)                           | `@ni-c/freshrss-mcp`              | FreshRSS — feeds, categories and articles as plain text, not stream ids        |
+| [google-search-console-mcp](https://google-search-console-mcp.ni-c.de) | `@ni-c/google-search-console-mcp` | Google Search Console — properties, sitemaps, search analytics, URL inspection |
+| [healthchecks-mcp](https://healthchecks-mcp.ni-c.de)                   | `healthchecks-mcp`                | Healthchecks — cron and uptime checks, and why one failed                      |
+| [hetzner-dns-mcp](https://hetzner-dns-mcp.ni-c.de)                     | `hetzner-dns-mcp`                 | Hetzner Cloud DNS — zones, record sets and BIND import/export                  |
+| [imap-mcp](https://imap-mcp.ni-c.de)                                   | `@ni-c/imap-mcp`                  | IMAP mailboxes — read, search, organise and draft mail; it cannot send         |
+| [linkwarden-mcp](https://linkwarden-mcp.ni-c.de)                       | `linkwarden-mcp`                  | Linkwarden — bookmarks, collections and the article text it preserved          |
+| [mealie-mcp](https://mealie-mcp.ni-c.de)                               | `@ni-c/mealie-mcp`                | Mealie — recipes, meal plans, shopping lists and cookbooks                     |
+| [ntfy-mcp](https://ntfy-mcp.ni-c.de)                                   | `@ni-c/ntfy-mcp`                  | ntfy — publish and update notifications, manage users and topic access         |
+| [opengist-mcp](https://opengist-mcp.ni-c.de)                           | `opengist-mcp`                    | Opengist — gists, revisions, commit history and raw files                      |
+| [osm-mcp](https://osm-mcp.ni-c.de)                                     | `osm-mcp`                         | OpenStreetMap — geocoding, routing, isochrones and POI search                  |
+| [rustpad-mcp](https://rustpad-mcp.ni-c.de)                             | `rustpad-mcp`                     | Rustpad — collaborative pads edited through real OT, not overwrites            |
+| [smtp-mcp](https://smtp-mcp.ni-c.de)                                   | `@ni-c/smtp-mcp`                  | SMTP — sends mail, behind a recipient allowlist and a human confirmation       |
+| [wg-easy-mcp](https://wg-easy-mcp.ni-c.de)                             | `wg-easy-mcp`                     | wg-easy v15+ — the full WireGuard client lifecycle                             |
+| [wikijs-mcp](https://wikijs-mcp.ni-c.de)                               | `@ni-c/wikijs-mcp`                | Wiki.js — search, read and edit pages, plus assets, users and groups           |
+| [woodpecker-ci-mcp](https://woodpecker-ci-mcp.ni-c.de)                 | `@ni-c/woodpecker-ci-mcp`         | Woodpecker CI — repositories, pipelines, logs, secrets and crons               |
+
+Each one runs perfectly well on its own over stdio. Put them behind the hub when
+you want them reachable from a client that cannot spawn a local process, or when
+you would rather register one connector than seventeen.
+
 ## Configuration
 
 `/config/mcp.json` — identical to Claude Code (`${VAR}` expands from the
@@ -81,6 +169,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 +188,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 +222,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 +230,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 +280,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 +295,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 +310,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 +332,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 +373,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 +383,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,27 +411,35 @@ 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
 
-- Stateless transport: server-initiated notifications (`listChanged`,
-  subscriptions, sampling) are not delivered to clients. Tool/resource/prompt
-  request-response works fully; the hub's tool cache does follow
-  `tools/list_changed` internally.
-- Access tokens are self-contained 15-minute JWTs. Revoking a client rejects
-  its existing JWTs and removes all of its refresh tokens. Refresh tokens
-  rotate; replaying a token
-  that was already rotated away revokes its whole chain, and a refresh cannot
-  ask for more scope than the original grant.
+- Change notifications (`listChanged`, resource updates) are carried on
+  `2026-07-28` via `subscriptions/listen`, whose state is the open response
+  rather than a session table. A `2025-11-25` client is offered neither, because
+  that revision needs a channel the stateless transport does not keep — so the
+  capability is withheld instead of announced and dropped. An on-demand server
+  watches nothing while it sleeps; the subscription is re-established on the
+  next wake and the client is told to re-read.
+- Elicitation travels end to end on `2026-07-28`: it is a result rather than a
+  push. Sampling and log messages are not forwarded.
+- Access tokens are opaque and last 15 minutes. Revoking a client takes effect
+  on its next request rather than when the token expires — the token is a
+  reference to a stored record, so withdrawing it is a deletion. Refresh tokens
+  rotate; replaying one that was already rotated away is treated as a leak and
+  revokes the whole grant, access tokens included.
 - Upstream auth is fully decoupled from the hub's own OAuth: an expired
   upstream token just marks that one server `down` (503 on its path, visible
   in `/health`) — clients never see the upstream's 401.