@ni-c/mcp-hub 0.9.2 → 0.11.0

package/CHANGELOG.md

@@ -7,6 +7,625 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 <!-- #region changelog -->
 
+## [0.11.0] - 2026-09-03
+
+### Added
+
+- **The meta-tools answer in both channels.** Five of the six now declare an
+  `outputSchema` and return the same object as `structuredContent` as well as
+  the JSON text block they always returned. A client that wants to *use* the
+  answer no longer has to parse a string and hope; one that wants to read it
+  still gets the text, because the SDK does not synthesize a text block for an
+  object-shaped value and dropping it would have left older clients with
+  nothing.
+
+  `list_servers` and `list_tools` therefore answer with `{"servers": […]}` and
+  `{"tools": […]}` rather than a bare array. That is the breaking part of this
+  change, and it is not cosmetic: the 2025 wire cannot carry a non-object
+  `structuredContent`, so the SDK wraps one in `{"result": …}` — and an
+  array-rooted answer would let a client tell from the payload which protocol
+  revision it had been given. The hub's promise is that it cannot. There is a
+  test comparing both eras field for field.
+
+  `call_tool` is the one without a schema. It returns the child's own result,
+  and a schema of the hub's would only be honest if the hub wrapped somebody
+  else's payload — which would break the passthrough the era matrix pins across
+  all four client/child combinations.
+
+- **`get_tool_schema` hands on the child's `outputSchema`.** This is the gap the
+  rest of the work uncovered. `call_tool` has always returned a child's
+  `structuredContent` verbatim, but the schema to validate it against was
+  dropped on the way out of `/hub`, so an aggregate client received structured
+  data it had no way to check — while `hub-tools.md` claimed structured content
+  "passes through". Half of it did.
+
+  `list_tools` marks such a tool with `hasOutputSchema: true` rather than
+  inlining the schema, so a large server's list stays a list. Both follow the
+  rule `annotations` already followed: the child's own document, verbatim, and
+  the key absent when it declared none.
+
+- **`list_tools` and `get_tool_schema` carry a child's tool annotations
+  through.** Over `/hub` a client never sees the child's own `tools/list`, so
+  those two answers are the only place it can learn that one of two similarly
+  named tools deletes and the other does not. They came back as name plus
+  description, which left every tool looking identical at exactly the moment a
+  model decides which to call. The proxy endpoint `/<name>/mcp` was already
+  correct; there is a test for it now too, because "already correct" is a
+  property that stops being true silently.
+
+  Verbatim, not summarised into a marker of the hub's own. The specification
+  says a client "MUST consider tool annotations to be untrusted unless they come
+  from trusted servers", and the hub is in no position to vouch for a child it
+  merely forwards to — a derived `kind` would have been the hub's claim about
+  somebody else's server. A child that declared nothing arrives with no
+  `annotations` key at all; an empty object would read as all four defaults,
+  which is a claim it did not make.
+
+- **The six meta-tools annotate themselves**, which they never did. The
+  specification gives `destructiveHint` and `openWorldHint` a default of `true`,
+  so silence declared `list_servers` a destructive tool in an open world.
+  `call_tool` is the one where that really is the answer: whatever the named
+  tool does, `call_tool` does.
+
+- **The hub speaks both MCP revisions on every endpoint.** `2026-07-28` and
+  `2025-11-25`, on `/hub`, on `/<name>/mcp` and over `--stdio`; the client
+  picks during its opening exchange and cannot tell from the answers which one
+  it got. Which traffic is carried on which revision is a
+  [matrix](https://mcp-hub.ni-c.de/reference/standards#what-is-carried-per-revision)
+  now, with a test behind every row, because this project has twice announced
+  something it did not deliver.
+
+  The 2025 path is untouched: it is served by the same transport that always
+  served it, so a `GET` still opens a stream and a `DELETE` still answers 200
+  rather than the 405 the modern handler's own fallback would give. claude.ai
+  opens that stream on every reconnect.
+
+- **Change notifications travel, on both sides.** A `2026-07-28` client opens a
+  `subscriptions/listen` stream and names what it wants — tool, prompt and
+  resource list changes, or specific resource URIs — and the hub delivers.
+  Upstream it subscribes to each child the way that child understands:
+  `subscriptions/listen` to a 2026 server, `resources/subscribe` to a 2025 one.
+  So a server that has never heard of the newer mechanism still reaches a client
+  that speaks nothing else, which is the common case in practice.
+  [Details](https://mcp-hub.ni-c.de/guide/subscriptions).
+
+  This is the second thing the 2026 revision made possible for a stateless
+  gateway, and for the same reason as the first: the state is the open HTTP
+  response rather than a session table, so a client reconnecting without closing
+  anything leaves nothing behind. One handler per route now outlives the
+  request, because it owns those streams — it holds the sockets currently open
+  and no record of who opened them.
+
+  The bookkeeping is a lease per stream rather than a reference count per URI.
+  A count cannot tell "nobody wants this any more" from "the one leaving wanted
+  it too", and gets it wrong in the direction that silently stops delivering to
+  the client that stayed.
+
+  A sleeping [on-demand](https://mcp-hub.ni-c.de/guide/on-demand) server watches
+  nothing: subscribing does not wake it — the acknowledgment comes from the
+  cached capabilities — and the subscription is re-established when something
+  else does, followed by a re-read signal for everything that client was
+  watching. What changed during the nap is not reported, only that there is
+  reason to look. `subscriptions: "off"` withdraws one server's right to push.
+
+- **An end-to-end suite that runs the hub the way it ships.** Three tiers: in
+  this process, as `node dist/index.js`, and as the published image through
+  `demo/compose.yml`. It is not part of `npm test`, which stays fast and stays
+  the pull-request gate; this one runs nightly, on any pull request that touches
+  it, and as a gate on release tags. [What it is
+  for](https://github.com/ni-c/mcp-hub/blob/main/e2e/README.md).
+
+  The tiers exist because a class of question cannot be asked from inside the
+  process being tested. `src/index.ts`'s startup block — environment parsing,
+  the listener, signal handlers — is entered only when the file is the program.
+  `mcp-hub-admin` is a *separate program* sharing `/data` with a running hub,
+  and a test that called the same `AuthStore` instance proves the hub can read
+  its own memory; that mistake shipped once, as a revocation that reported
+  success and did nothing. An `uncaughtException` in-process takes the test
+  runner down rather than the hub. And uid 1000, a read-only root filesystem,
+  the healthcheck and tini cannot be wrong in a bare process at all.
+
+  The consumer is a scripted agent rather than a model. It discovers through the
+  six meta-tools and then builds its arguments *from the schema the hub
+  published*, which is the whole point: a schema damaged in transit — truncated,
+  budget-clipped, missing a property it declares required — stops working there
+  and nowhere else. A model handed a broken schema improvises around it, and
+  improvisation is not an assertion.
+
+  Alongside it: thirteen fixture servers that each misbehave in one specific way
+  no off-the-shelf server does, a four-cell client-era × child-era matrix built
+  on one catalogue registered twice so a difference can only be the hub's, raw
+  `fetch` conformance checks that assert an HTTP status and a JSON-RPC code
+  together, and a recorder for what real clients put on the wire.
+
+- **`src/timings.ts`.** The supervisor's ping interval, wake timeout, idle
+  sweep and backoff curve read the environment, the same way `mcp-limits.ts`
+  already did for the call deadline. `IDLE_TIMEOUT_MS` is the sub-minute sibling
+  of `IDLE_TIMEOUT_MINUTES`.
+
+  Defaults are unchanged, so no deployment behaves differently. What changes is
+  that the behaviour becomes observable: at the shipped numbers, watching a
+  server fall asleep costs a minute and the five-minute backoff ceiling cannot
+  be reached at all. Four minutes of a test suite spent asleep is four minutes
+  somebody eventually deletes.
+
+- **`describe_connection`, behind `MCP_DIAGNOSTICS`.** A seventh meta-tool that
+  answers the one question a client cannot answer for itself: which protocol
+  era this connection is on, whether this request carried an elicitation
+  capability, and — for a named server — whether a question from it would
+  actually reach the person at the far end.
+
+  It exists because a server falling back to its two-call token looks identical
+  to a server that simply did not ask. From inside the client both are silence,
+  and only the hub knows which one it was. The first thing it reported in
+  anger: a connector on the `2026-07-28` era that declares no `elicitation`
+  capability at all — which the era, unlike the older one, would let it do.
+
+  Off by default. Not for safety — it reports only what the caller's own request
+  already carried, and nothing about any other client — but because every tool a
+  client can see costs context in every conversation it has, and "six meta-tools
+  instead of N×tools" is the argument for the aggregate. With the switch on,
+  `/hub` and `--stdio` serve seven.
+
+- **One log line when a question is dropped.** When the hub declines to carry a
+  child's elicitation it now says so once per client, server and reason, instead
+  of leaving the only trace inside a tool result that one caller sees. The
+  decision itself moved into a single function that both the forwarding path and
+  the new tool call, so the explanation cannot drift from the behaviour.
+
+### Fixed
+
+- **The meta-tools no longer advertise an empty schema where they mean
+  "anything".** Five fields carry a document the hub does not own — a child's
+  `annotations` on `list_tools` and `get_tool_schema`, the two schemas on
+  `get_tool_schema`, and the `arguments` of `call_tool` — and zod writes that
+  as `"additionalProperties": {}`. An empty schema is legal and means exactly
+  what `true` means, but it is the spelling some MCP clients refuse or
+  mishandle, which is the worst kind of bug to own: the tool works against the
+  client you tested with and fails against the one you did not.
+
+  Only the emitted JSON Schema changes. The runtime is still as permissive as
+  it has to be, and deliberately so: those fields are validated against the zod
+  schema, a child is free to put anything in them, and the SDK turns a refused
+  answer into an error result. A test walks every schema the hub advertises and
+  fails on any node that constrains nothing, so a future zod release cannot put
+  the spelling back without saying so.
+
+- **A non-object output schema now reaches a 2025 client with its value wrapped
+  to match.** The per-server endpoint writes its own `tools/call` handler, and
+  such a handler has to run the result through the wire codec itself. It did
+  not. The schema half was already being rewritten to `{"result": …}` on the
+  way out, so a child whose `outputSchema` describes an array handed a 2025
+  client a bare array to validate against a schema saying "object" — correct
+  data that looks broken. Both halves are projected now, and a fixture with an
+  array-rooted schema pins it on every era pair.
+
+  The e2e agent, which checks that a result carries everything its schema
+  requires, was silently doing nothing on the `/hub` door for the same reason:
+  the schema it read from `get_tool_schema` was always `undefined`. It bites
+  there now, and it also asserts that the text block and `structuredContent`
+  agree.
+
+- **Three capabilities the hub announced but did not serve.** `listChanged` for
+  tools, prompts and resources is now advertised only on the revision that
+  carries it, and is true there; `resources.subscribe` likewise, having been
+  stripped outright since 0.6.3. `logging` is no longer advertised at all —
+  `logging/setLevel` never had a handler, so a client that believed it got a
+  `-32601` at call time, and on `2026-07-28` the level is per-request `_meta`
+  with no RPC left to implement.
+
+  A 2025 client is now told none of the three. That is a visible change, and the
+  honest one: it was never going to receive any of them.
+
+- **A `subscriptions/listen` POST no longer occupies an in-flight slot.** It is
+  a POST whose response stays open for the life of the subscription, so counted
+  as work in progress it held one of `MCP_MAX_CONCURRENT_REQUESTS` (default
+  four) the entire time — a handful of subscribed clients would have locked
+  every tool call on the hub out with a 429 while nothing was running. It is the
+  standing channel by another name and is charged to
+  `MCP_MAX_CONCURRENT_STREAMS`, where the 2025 era's `GET` already went.
+
+- **Elicitation travels end to end.** A child server that needs to ask the
+  person at the far end something — `smtp-mcp` before it sends, `imap-mcp`
+  before it expunges a mailbox — now reaches them through the hub instead of
+  silently falling back to a weaker check. On `2026-07-28` a question is a
+  *result*, not a push: the call ends, the person decides, the client retries
+  with the answer. Nothing is held open, so the stateless transport is what
+  makes this work rather than what prevented it.
+
+  The hub adds what follows from the question crossing a trust boundary. It is
+  attributed to the server that asked, after the text has been stripped of the
+  bidirectional and zero-width characters that could visually undo that line.
+  Embedded `sampling/createMessage` and `roots/list` requests are dropped and
+  named in the log — relaying them would spend the caller's model budget and
+  hand out its workspace layout on a child's say-so. The child's `_meta` is
+  removed. The resumption state is signed and bound to the server, the tool,
+  the OAuth client and the endpoint, so it cannot be pasted onto another call.
+
+  The capability is mirrored per request from what the client itself declared,
+  and never widened — so it is announced only for a call whose answer has
+  somewhere to go. A `2025-11-25` client over HTTP is therefore not offered it
+  at all, and the child takes its own fallback, which is the same rule this
+  project already applies to `listChanged`.
+
+  `"passthrough": "off"` on a server withdraws its right to put words in front
+  of the user without switching it off; `MCP_ELICITATION=false` is the global
+  brake. Four further `MCP_ELICITATION_*` variables bound rounds, lifetime,
+  message size and payload size. See
+  [Elicitation](https://mcp-hub.ni-c.de/guide/elicitation).
+
+- **A question from a server that had gone to sleep was lost.** The hub decided
+  whether a child could be asked by reading the protocol era off its client,
+  and an on-demand child that is asleep has none — so the first tool call after
+  an idle nap silently took the weaker path and the second one worked. The wake
+  now happens before the decision.
+
+### Changed
+
+- **On MCP SDK 2.0.** The single `@modelcontextprotocol/sdk` package has been
+  replaced by the split `@modelcontextprotocol/{core,client,server,node,express}`.
+  Behaviour is unchanged by the migration itself: no wire format, endpoint or
+  response differs, and deployments need do nothing. Speaking `2026-07-28` as
+  well is a separate change, listed under Added above — it is what the
+  migration was for.
+
+  Notably **not** installed is `@modelcontextprotocol/server-legacy`, the frozen
+  copy of v1's authorization-server helpers that npm marks deprecated on
+  install. Replacing the hand-written OAuth server with `oidc-provider` first is
+  what made that possible — this migration only had to touch the MCP wire layer.
+
+  Two things the mechanical migration would have changed quietly, and did not:
+  `tools/list` is still walked one page at a time, because v2's `listTools()`
+  aggregates the whole pagination internally and would have bypassed the tool
+  count and metadata budgets that bound what a hostile child can make the hub
+  hold in memory; and a malformed line on a child's stdio is still reported,
+  because v2's read buffer skips unparseable lines in silence.
+
+- **The authorization server is now `oidc-provider` instead of ~900 lines of
+  hand-written OAuth.** Every endpoint keeps its path, the login and consent
+  pages are the same pages, and the discovery document advertises everything it
+  advertised before — there is a test that compares it field by field against
+  the old one and fails on anything that is not a written-down decision.
+
+  **This is a clean cut, not a migration: every client re-registers and
+  authorizes once more.** Tokens issued by the previous server are refused
+  rather than honoured, because a credential nothing can revoke is worse than a
+  reconnect. Registrations, approvals and API tokens in `state.json` are
+  untouched; only the OAuth artifacts are new.
+
+  Access tokens are **opaque** rather than JWTs. That is what makes
+  `mcp-hub-admin clients revoke` take effect on the next call instead of when
+  the token expires: oidc-provider never persists a JWT, so a JWT could not be
+  withdrawn at all. Nothing that presents a token has to change.
+
+  Several things got stricter on the way. Replaying a rotated refresh token now
+  revokes the grant's access tokens as well. Client assertions may not be valid
+  for longer than five minutes. Nothing an authorization server holds is written
+  to `state.json` in a form anyone could present — the file used to keep hashes
+  of refresh tokens, and now keeps hashes of everything. A `Host` header can no
+  longer influence the URLs in the discovery document.
+
+  Visible differences, none of which change what is allowed: redirects use
+  `303` where they used `302`, `invalid_client` may be answered `401` rather
+  than `400` (RFC 6749 §5.2 allows either), a rejected redirect URI is reported
+  as `invalid_redirect_uri`, and the login page lives at `/interaction/<id>/`
+  instead of being rendered by `/authorize` directly. The discovery document
+  gained the OpenID fields oidc-provider always publishes; no ID token is ever
+  issued.
+
+- **Four more reserved server names: `jwks`, `interaction`, `session` and
+  `userinfo`.** They are paths the authorization server answers on, and a server
+  configured under one of them would shadow the login flow rather than merely be
+  unreachable. A configuration using one of these names is now refused at
+  startup with the same message as for `token` or `authorize`.
+
+- **Both images now run on Node 24 ("Krypton"), the active LTS line, instead of
+  Node 26.** Node 26 is Current until October, and a non-LTS build leaves
+  `process.release.lts` unset — which is not cosmetic, because libraries branch
+  on it. It is also what the CI matrix already tests against, so the container
+  and the test runs no longer sat on different majors.
+
+  Nothing else changes: npm is still replaced wholesale and its three vulnerable
+  vendored packages still overwritten in place, verified against the built
+  image.
+
+### Security
+
+Five findings from an internal review of the authorization surface, which is the
+half that was rewritten onto oidc-provider in this cycle and had not been looked
+at adversarially since.
+
+- **`/token` bounds the body it reads.** It is the one provider path whose
+  request stream the hub takes away from the library — `stripPhantomSecret` has
+  to read it to strip a presented secret — and it read it without a ceiling.
+  `/token` cannot ask who is calling before it reads, because the credentials
+  are in the body, so an anonymous 300 MB request took the process from 157 MB
+  resident to 1.4 GB, and the per-path budget still allows fifty of them per
+  caller per window. The ceiling is oidc-provider's own 56 KiB, so nothing a
+  legitimate client sends changes, and an oversized body now gets the same
+  answer the library would have given it.
+
+- **A public client's record no longer carries a secret.** RFC 7591 makes
+  `client_secret_basic` the default when `token_endpoint_auth_method` is
+  omitted — which is what Claude and ChatGPT both do — so the authorization
+  server minted and persisted a real secret before `clientDefaults` rewrote the
+  method to `none`. Two consequences, neither visible from outside:
+  `state.json` gained a value someone could present, which is the one thing it
+  is careful never to hold; and `stripPhantomSecret` gates on the stored client
+  having no secret, so it stopped firing for exactly the clients it exists for.
+  A connector that echoed the secret from its registration response got
+  `401 invalid_client` — the failure quirk 2 was written to prevent. The
+  response still carries a secret, because ChatGPT insists on one; only the
+  record is cleaned.
+
+- **A hundred wrong passwords no longer lock the operator out.** The global
+  failure ceiling refused every address once it was reached, so an attacker
+  could close the only administrative way in — from one host, in under a second,
+  renewable every fifteen minutes — and the operator holding the correct
+  password got `429` from an address that had never touched the form. The
+  ceiling now refuses the callers that are guessing, and refuses them on their
+  first failure rather than their tenth once the hub is under a distributed
+  attempt, so the total number of guesses still collapses. What it no longer
+  does is let them spend somebody else's budget.
+
+- **Every per-caller budget counts an IPv6 /64, not an address.** A /64 is the
+  smallest block one subscriber is handed, and a /56 or /48 is what a
+  residential line usually gets, so a limiter keyed on the full address counted
+  one host as billions of callers: twenty-five registrations from twenty-five
+  addresses in one network spent twenty-five budgets of twenty. IPv4 keeps its
+  own address, and an IPv4-mapped form is folded back onto it so the same caller
+  is not counted twice for arriving over a dual-stack listener. Log lines are
+  unchanged — fail2ban still gets the host that actually connected.
+
+- **A `TRUSTED_PROXIES` list that never matches is now said out loud.** It is
+  compared against the address the connection came from, and the easiest way to
+  get it wrong is the least visible: a proxy configured as
+  `proxy_pass http://localhost:…` on a dual-stack host arrives over `::1`,
+  which `127.0.0.1` does not cover. Every forwarded header is then ignored and
+  per-caller limiting collapses into one global counter — the exact failure the
+  startup warning covers for an *unset* list, with nothing said when the list is
+  merely wrong. The hub now says so once, when a forwarded header arrives from
+  an address it does not trust.
+
+Unchanged, and confirmed by the same review: the docker policy proxy refused
+every one of thirty-three attempts to reach the daemon past it — privileged
+containers, host mounts, `Mounts` instead of `Binds`, foreign images, prototype
+pollution in the create body, duplicate query parameters, encoded traversal in a
+container name, `exec`, `build`, `networks/create`; and the metadata-document
+fetcher refused literal private addresses, IPv4-mapped ones and public names
+that resolve inward.
+
+## [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